Numerical Integration

Goal

Provide a reliable workflow to select integrators, set tolerances, and manage adaptive time stepping for time-dependent simulations.

Requirements

• Python 3.8+

• NumPy (for some scripts)

• No heavy dependencies for core functionality

Inputs to Gather

Input Description Example

Problem type ODE/PDE, stiff/non-stiff stiff PDE

Jacobian available Can compute ∂f/∂u? yes

Target accuracy Desired error level 1e-6

Constraints Memory, implicit allowed? implicit OK

Time scale Characteristic time 1e-3 s

Decision Guidance

Choosing an Integrator

Is the problem stiff? ├── YES → Is Jacobian available? │ ├── YES → Use Rosenbrock or BDF │ └── NO → Use BDF with numerical Jacobian └── NO → Is high accuracy needed? ├── YES → Use RK45 or DOP853 └── NO → Use RK4 or Adams-Bashforth

Stiff vs Non-Stiff Detection

Symptom Likely Stiff Action

dt shrinks to tiny values Yes Switch to implicit

Eigenvalues span many decades Yes Use BDF/Radau

Smooth solution, reasonable dt No Stay explicit

Script Outputs (JSON Fields)

Script Key Outputs

scripts/error_norm.py

error_norm , scale_min , scale_max

scripts/adaptive_step_controller.py

accept , dt_next , factor

scripts/integrator_selector.py

recommended , alternatives , notes

scripts/imex_split_planner.py

implicit_terms , explicit_terms , splitting_strategy

scripts/splitting_error_estimator.py

error_estimate , substeps

Workflow

• Classify stiffness - Check eigenvalue spread or use stiffness_detector

• Choose tolerances - See references/tolerance_guidelines.md

• Select integrator - Run scripts/integrator_selector.py

• Compute error norms - Use scripts/error_norm.py for step acceptance

• Adapt step size - Use scripts/adaptive_step_controller.py

• Plan IMEX/splitting - If mixed stiff/nonstiff, use scripts/imex_split_planner.py

• Validate convergence - Repeat with tighter tolerances

Conversational Workflow Example

User: I'm solving the Allen-Cahn equation with a stiff double-well potential. What integrator should I use?

Agent workflow:

• Check integrator options: python3 scripts/integrator_selector.py --stiff --jacobian-available --accuracy high --json

• Plan the IMEX splitting (diffusion implicit, reaction explicit): python3 scripts/imex_split_planner.py --stiff-terms diffusion --nonstiff-terms reaction --coupling weak --json

• Recommend: Use IMEX-BDF2 with diffusion term implicit, double-well reaction explicit.

Pre-Integration Checklist

• Identify stiffness and dominant time scales

• Set rtol /atol consistent with physics and units

• Confirm integrator compatibility with stiffness

• Use error norm to accept/reject steps

• Verify convergence with tighter tolerance run

CLI Examples

Select integrator for stiff problem with Jacobian

python3 scripts/integrator_selector.py --stiff --jacobian-available --accuracy high --json

Compute scaled error norm

python3 scripts/error_norm.py --error 0.01,0.02 --solution 1.0,2.0 --rtol 1e-3 --atol 1e-6 --json

Adaptive step control with PI controller

python3 scripts/adaptive_step_controller.py --dt 1e-2 --error-norm 0.8 --order 4 --controller pi --json

Plan IMEX splitting

python3 scripts/imex_split_planner.py --stiff-terms diffusion,elastic --nonstiff-terms reaction --coupling strong --json

Estimate splitting error

python3 scripts/splitting_error_estimator.py --dt 1e-4 --scheme strang --commutator-norm 50 --target-error 1e-6 --json

Error Handling

Error Cause Resolution

rtol and atol must be positive

Invalid tolerances Use positive values

error-norm must be positive

Negative error norm Check error computation

Unknown controller

Invalid controller type Use i , pi , or pid

Splitting requires at least one term

Empty term list Specify stiff or nonstiff terms

Interpretation Guidance

Error Norm Values

Error Norm Meaning Action

< 1.0 Step acceptable Accept, maybe increase dt

≈ 1.0 At tolerance boundary Accept with current dt

1.0 Step rejected Reject, reduce dt

Controller Selection

Controller Properties Best For

I (integral) Simple, some overshoot Non-stiff, moderate accuracy

PI (proportional-integral) Smooth, robust General use

PID Aggressive adaptation Rapidly varying dynamics

IMEX Strategy

Coupling Strategy

Weak Simple operator splitting

Moderate Strang splitting

Strong Fully coupled IMEX-RK

Limitations

• No automatic stiffness detection: Use stiffness_detector from numerical-stability

• Splitting assumes separability: Terms must be cleanly separable

• Jacobian requirement: Some methods need analytical or numerical Jacobian

References

• references/method_catalog.md

• Integrator options and properties

• references/tolerance_guidelines.md

• Choosing rtol/atol

• references/error_control.md

• Error norm and adaptation formulas

• references/imex_guidelines.md

• Stiff/non-stiff splitting

• references/splitting_catalog.md

• Operator splitting patterns

• references/multiphase_field_patterns.md

• Phase-field specific splits

Version History

• v1.1.0 (2024-12-24): Enhanced documentation, decision guidance, examples

• v1.0.0: Initial release with 5 integration scripts