Numerical Integration

Goal

Requirements

• Python 3.8+
• NumPy (for some scripts)
• No heavy dependencies for core functionality

Inputs to Gather

stiff PDE

yes

1e-6

implicit OK

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

Script Outputs (JSON Fields)

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

1. Classify stiffness - Check eigenvalue spread or use stiffness_detector
2. Choose tolerances - See

   references/tolerance_guidelines.md

3. Select integrator - Run

   scripts/integrator_selector.py

4. Compute error norms - Use

   scripts/error_norm.py

   for step acceptance
5. Adapt step size - Use

   scripts/adaptive_step_controller.py

6. Plan IMEX/splitting - If mixed stiff/nonstiff, use

   scripts/imex_split_planner.py

7. Validate convergence - Repeat with tighter tolerances

Conversational Workflow Example

1. Check integrator options:
   bash

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

2. Plan the IMEX splitting (diffusion implicit, reaction explicit):
   bash

   python3 scripts/imex_split_planner.py --stiff-terms diffusion --nonstiff-terms reaction --coupling weak --json

3. 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

rtol and atol must be positive

error-norm must be positive

Unknown controller

i

pi

pid

Splitting requires at least one term

Interpretation Guidance

Error Norm Values

Controller Selection

IMEX Strategy

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