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 |
Security
The numerical-integration scripts enforce the following safeguards:
- Term name validation:
imex_split_planner.py validates term names against [a-zA-Z_][a-zA-Z0-9_ -]* with length and count limits, preventing injection payloads in user-supplied term lists.
- Input length limits: Comma-separated value lists are capped at 100,000 entries to prevent resource exhaustion.
- Finite-value enforcement: All numeric inputs (
dt, rtol, atol, error_norm, stiffness_ratio, commutator_norm, etc.) are validated as finite numbers at the function boundary.
- Numeric bounds:
dimension capped at 10 billion, order at 20, stiffness_ratio at 1e30.
- Reduced tool surface: The skill's
allowed-tools excludes Bash to prevent the agent from executing arbitrary commands when processing user-provided inputs.
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---56# Numerical Integration78## Goal910Provide a reliable workflow to select integrators, set tolerances, and manage adaptive time stepping for time-dependent simulations.1112## Requirements1314- Python 3.8+15- NumPy (for some scripts)16- No heavy dependencies for core functionality1718## Inputs to Gather1920| 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` |2728## Decision Guidance2930### Choosing an Integrator3132```33Is the problem stiff?34├── YES → Is Jacobian available?35│ ├── YES → Use Rosenbrock or BDF36│ └── NO → Use BDF with numerical Jacobian37└── NO → Is high accuracy needed?38 ├── YES → Use RK45 or DOP85339 └── NO → Use RK4 or Adams-Bashforth40```4142### Stiff vs Non-Stiff Detection4344| 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 |4950## Script Outputs (JSON Fields)5152| 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` |5960## Workflow61621. **Classify stiffness** - Check eigenvalue spread or use stiffness_detector632. **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 acceptance665. **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 tolerances6970## Conversational Workflow Example7172**User**: I'm solving the Allen-Cahn equation with a stiff double-well potential. What integrator should I use?7374**Agent workflow**:751. Check integrator options:76 ```bash77 python3 scripts/integrator_selector.py --stiff --jacobian-available --accuracy high --json78 ```792. Plan the IMEX splitting (diffusion implicit, reaction explicit):80 ```bash81 python3 scripts/imex_split_planner.py --stiff-terms diffusion --nonstiff-terms reaction --coupling weak --json82 ```833. Recommend: Use IMEX-BDF2 with diffusion term implicit, double-well reaction explicit.8485## Pre-Integration Checklist8687- [ ] Identify stiffness and dominant time scales88- [ ] Set `rtol`/`atol` consistent with physics and units89- [ ] Confirm integrator compatibility with stiffness90- [ ] Use error norm to accept/reject steps91- [ ] Verify convergence with tighter tolerance run9293## CLI Examples9495```bash96# Select integrator for stiff problem with Jacobian97python3 scripts/integrator_selector.py --stiff --jacobian-available --accuracy high --json9899# Compute scaled error norm100python3 scripts/error_norm.py --error 0.01,0.02 --solution 1.0,2.0 --rtol 1e-3 --atol 1e-6 --json101102# Adaptive step control with PI controller103python3 scripts/adaptive_step_controller.py --dt 1e-2 --error-norm 0.8 --order 4 --controller pi --json104105# Plan IMEX splitting106python3 scripts/imex_split_planner.py --stiff-terms diffusion,elastic --nonstiff-terms reaction --coupling strong --json107108# Estimate splitting error109python3 scripts/splitting_error_estimator.py --dt 1e-4 --scheme strang --commutator-norm 50 --target-error 1e-6 --json110```111112## Error Handling113114| 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 |120121## Interpretation Guidance122123### Error Norm Values124125| 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 |130131### Controller Selection132133| 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 |138139### IMEX Strategy140141| Coupling | Strategy |142|----------|----------|143| Weak | Simple operator splitting |144| Moderate | Strang splitting |145| Strong | Fully coupled IMEX-RK |146147## Security148149The numerical-integration scripts enforce the following safeguards:150151- **Term name validation**: `imex_split_planner.py` validates term names against `[a-zA-Z_][a-zA-Z0-9_ -]*` with length and count limits, preventing injection payloads in user-supplied term lists.152- **Input length limits**: Comma-separated value lists are capped at 100,000 entries to prevent resource exhaustion.153- **Finite-value enforcement**: All numeric inputs (`dt`, `rtol`, `atol`, `error_norm`, `stiffness_ratio`, `commutator_norm`, etc.) are validated as finite numbers at the function boundary.154- **Numeric bounds**: `dimension` capped at 10 billion, `order` at 20, `stiffness_ratio` at 1e30.155- **Reduced tool surface**: The skill's `allowed-tools` excludes `Bash` to prevent the agent from executing arbitrary commands when processing user-provided inputs.156157## Limitations158159- **No automatic stiffness detection**: Use stiffness_detector from numerical-stability160- **Splitting assumes separability**: Terms must be cleanly separable161- **Jacobian requirement**: Some methods need analytical or numerical Jacobian162163## References164165- `references/method_catalog.md` - Integrator options and properties166- `references/tolerance_guidelines.md` - Choosing rtol/atol167- `references/error_control.md` - Error norm and adaptation formulas168- `references/imex_guidelines.md` - Stiff/non-stiff splitting169- `references/splitting_catalog.md` - Operator splitting patterns170- `references/multiphase_field_patterns.md` - Phase-field specific splits171172## Version History173174- **v1.1.0** (2024-12-24): Enhanced documentation, decision guidance, examples175- **v1.0.0**: Initial release with 5 integration scripts
luokai0