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
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 propertiesreferences/tolerance_guidelines.md - Choosing rtol/atolreferences/error_control.md - Error norm and adaptation formulasreferences/imex_guidelines.md - Stiff/non-stiff splittingreferences/splitting_catalog.md - Operator splitting patternsreferences/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
1---2name: numerical-integration3description: Select and configure time integration methods for ODE/PDE simulations. Use when choosing explicit/implicit schemes, setting error tolerances, adapting time steps, diagnosing integration accuracy, planning IMEX splitting, or handling stiff/non-stiff coupled systems.4---5
6# Numerical Integration
7
8## Goal
9
10Provide a reliable workflow to select integrators, set tolerances, and manage adaptive time stepping for time-dependent simulations.
11
12## Requirements
13
14- Python 3.8+
15- NumPy (for some scripts)
16- No heavy dependencies for core functionality
17
18## Inputs to Gather
19
20| Input | Description | Example |
21|-------|-------------|---------|
22| Problem type | ODE/PDE, stiff/non-stiff | `stiff PDE` |
23| Jacobian available | Can compute ∂f/∂u? | `yes` |
24| Target accuracy | Desired error level | `1e-6` |
25| Constraints | Memory, implicit allowed? | `implicit OK` |
26| Time scale | Characteristic time | `1e-3 s` |
27
28## Decision Guidance
29
30### Choosing an Integrator
31
32```
33Is the problem stiff?
34├── YES → Is Jacobian available?
35│ ├── YES → Use Rosenbrock or BDF
36│ └── NO → Use BDF with numerical Jacobian
37└── NO → Is high accuracy needed?
38 ├── YES → Use RK45 or DOP853
39 └── NO → Use RK4 or Adams-Bashforth
40```
41
42### Stiff vs Non-Stiff Detection
43
44| Symptom | Likely Stiff | Action |
45|---------|--------------|--------|
46| dt shrinks to tiny values | Yes | Switch to implicit |
47| Eigenvalues span many decades | Yes | Use BDF/Radau |
48| Smooth solution, reasonable dt | No | Stay explicit |
49
50## Script Outputs (JSON Fields)
51
52| Script | Key Outputs |
53|--------|-------------|
54| `scripts/error_norm.py` | `error_norm`, `scale_min`, `scale_max` |
55| `scripts/adaptive_step_controller.py` | `accept`, `dt_next`, `factor` |
56| `scripts/integrator_selector.py` | `recommended`, `alternatives`, `notes` |
57| `scripts/imex_split_planner.py` | `implicit_terms`, `explicit_terms`, `splitting_strategy` |
58| `scripts/splitting_error_estimator.py` | `error_estimate`, `substeps` |
59
60## Workflow
61
621. **Classify stiffness** - Check eigenvalue spread or use stiffness_detector
632. **Choose tolerances** - See `references/tolerance_guidelines.md`
643. **Select integrator** - Run `scripts/integrator_selector.py`
654. **Compute error norms** - Use `scripts/error_norm.py` for step acceptance
665. **Adapt step size** - Use `scripts/adaptive_step_controller.py`
676. **Plan IMEX/splitting** - If mixed stiff/nonstiff, use `scripts/imex_split_planner.py`
687. **Validate convergence** - Repeat with tighter tolerances
69
70## Conversational Workflow Example
71
72**User**: I'm solving the Allen-Cahn equation with a stiff double-well potential. What integrator should I use?
73
74**Agent workflow**:
751. Check integrator options:
76 ```bash
77 python3 scripts/integrator_selector.py --stiff --jacobian-available --accuracy high --json
78 ```
792. Plan the IMEX splitting (diffusion implicit, reaction explicit):
80 ```bash
81 python3 scripts/imex_split_planner.py --stiff-terms diffusion --nonstiff-terms reaction --coupling weak --json
82 ```
833. Recommend: Use IMEX-BDF2 with diffusion term implicit, double-well reaction explicit.
84
85## Pre-Integration Checklist
86
87- [ ] Identify stiffness and dominant time scales
88- [ ] Set `rtol`/`atol` consistent with physics and units
89- [ ] Confirm integrator compatibility with stiffness
90- [ ] Use error norm to accept/reject steps
91- [ ] Verify convergence with tighter tolerance run
92
93## CLI Examples
94
95```bash
96# Select integrator for stiff problem with Jacobian
97python3 scripts/integrator_selector.py --stiff --jacobian-available --accuracy high --json
98
99# Compute scaled error norm
100python3 scripts/error_norm.py --error 0.01,0.02 --solution 1.0,2.0 --rtol 1e-3 --atol 1e-6 --json
101
102# Adaptive step control with PI controller
103python3 scripts/adaptive_step_controller.py --dt 1e-2 --error-norm 0.8 --order 4 --controller pi --json
104
105# Plan IMEX splitting
106python3 scripts/imex_split_planner.py --stiff-terms diffusion,elastic --nonstiff-terms reaction --coupling strong --json
107
108# Estimate splitting error
109python3 scripts/splitting_error_estimator.py --dt 1e-4 --scheme strang --commutator-norm 50 --target-error 1e-6 --json
110```
111
112## Error Handling
113
114| Error | Cause | Resolution |
115|-------|-------|------------|
116| `rtol and atol must be positive` | Invalid tolerances | Use positive values |
117| `error-norm must be positive` | Negative error norm | Check error computation |
118| `Unknown controller` | Invalid controller type | Use `i`, `pi`, or `pid` |
119| `Splitting requires at least one term` | Empty term list | Specify stiff or nonstiff terms |
120
121## Interpretation Guidance
122
123### Error Norm Values
124
125| Error Norm | Meaning | Action |
126|------------|---------|--------|
127| < 1.0 | Step acceptable | Accept, maybe increase dt |
128| ≈ 1.0 | At tolerance boundary | Accept with current dt |
129| > 1.0 | Step rejected | Reject, reduce dt |
130
131### Controller Selection
132
133| Controller | Properties | Best For |
134|------------|------------|----------|
135| I (integral) | Simple, some overshoot | Non-stiff, moderate accuracy |
136| PI (proportional-integral) | Smooth, robust | General use |
137| PID | Aggressive adaptation | Rapidly varying dynamics |
138
139### IMEX Strategy
140
141| Coupling | Strategy |
142|----------|----------|
143| Weak | Simple operator splitting |
144| Moderate | Strang splitting |
145| Strong | Fully coupled IMEX-RK |
146
147## Limitations
148
149- **No automatic stiffness detection**: Use stiffness_detector from numerical-stability
150- **Splitting assumes separability**: Terms must be cleanly separable
151- **Jacobian requirement**: Some methods need analytical or numerical Jacobian
152
153## References
154
155- `references/method_catalog.md` - Integrator options and properties
156- `references/tolerance_guidelines.md` - Choosing rtol/atol
157- `references/error_control.md` - Error norm and adaptation formulas
158- `references/imex_guidelines.md` - Stiff/non-stiff splitting
159- `references/splitting_catalog.md` - Operator splitting patterns
160- `references/multiphase_field_patterns.md` - Phase-field specific splits
161
162## Version History
163
164- **v1.1.0** (2024-12-24): Enhanced documentation, decision guidance, examples
165- **v1.0.0**: Initial release with 5 integration scripts
tools-only