Numerical Integration
Goal
Provide a reliable workflow to select integrators, set tolerances, and manage adaptive time stepping for time-dependent simulations.
Requirements
- Python 3.10+
- 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
Input Validation
- All numeric inputs (
dt, rtol, atol, error_norm, stiffness_ratio, commutator_norm, etc.) are validated as finite numbers at the function boundary
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
- Comma-separated value lists are capped at 100,000 entries to prevent resource exhaustion
- Numeric bounds enforced:
dimension capped at 10 billion, order at 20, stiffness_ratio at 1e30
--controller is validated against a fixed allowlist (i, pi, pid)
--scheme is validated against known splitting schemes (lie, strang)
File Access
- Scripts read no external files; all inputs are provided via CLI arguments
- Scripts write only to stdout (JSON output); no files are created unless the agent explicitly uses the Write tool
Tool Restrictions
- Read: Used to inspect script source, references, and user configuration files
- Write: Used to save integrator recommendations or splitting plans; writes are scoped to the user's working directory
- Grep/Glob: Used to locate relevant files and search references
- The skill's
allowed-tools excludes Bash to prevent the agent from executing arbitrary commands when processing user-provided inputs
Safety Measures
- No
eval(), exec(), or dynamic code generation
- All subprocess calls use explicit argument lists (no
shell=True)
- Reduced tool surface (no Bash) limits the agent to read/write operations only
- Term names are sanitized before use, preventing shell metacharacter injection
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
1---2name: numerical-integration3description: >4 Select and configure time integration methods for ODE and PDE simulations —5 choose among explicit Runge-Kutta, BDF, Rosenbrock, and Adams families,6 set relative and absolute error tolerances, implement adaptive step-size7 control with I/PI/PID controllers, plan IMEX operator splitting for mixed8 stiff and non-stiff terms, and estimate splitting errors. Use when picking9 an integrator for a new simulation, diagnosing step rejections or tolerance10 failures, setting up operator splitting for phase-field or reaction-diffusion11 problems, or deciding between explicit and implicit time marching, even if12 the user only says "my solver keeps rejecting steps" or "which ODE method13 should I use."14allowed-tools: Read, Write, Grep, Glob15metadata:16 source: https://skillmd.com/skills/zuoguyoupan2023/numerical-integration17 author: HeshamFS18 version: "1.1.0"19 security_tier: medium20 security_reviewed: true21 tested_with:22 - claude-code23 - gemini-cli24 - vs-code-copilot25 eval_cases: 426 last_reviewed: "2026-03-26"27---2829# Numerical Integration3031## Goal3233Provide a reliable workflow to select integrators, set tolerances, and manage adaptive time stepping for time-dependent simulations.3435## Requirements3637- Python 3.10+38- NumPy (for some scripts)39- No heavy dependencies for core functionality4041## Inputs to Gather4243| Input | Description | Example |44|-------|-------------|---------|45| Problem type | ODE/PDE, stiff/non-stiff | `stiff PDE` |46| Jacobian available | Can compute ∂f/∂u? | `yes` |47| Target accuracy | Desired error level | `1e-6` |48| Constraints | Memory, implicit allowed? | `implicit OK` |49| Time scale | Characteristic time | `1e-3 s` |5051## Decision Guidance5253### Choosing an Integrator5455```56Is the problem stiff?57├── YES → Is Jacobian available?58│ ├── YES → Use Rosenbrock or BDF59│ └── NO → Use BDF with numerical Jacobian60└── NO → Is high accuracy needed?61 ├── YES → Use RK45 or DOP85362 └── NO → Use RK4 or Adams-Bashforth63```6465### Stiff vs Non-Stiff Detection6667| Symptom | Likely Stiff | Action |68|---------|--------------|--------|69| dt shrinks to tiny values | Yes | Switch to implicit |70| Eigenvalues span many decades | Yes | Use BDF/Radau |71| Smooth solution, reasonable dt | No | Stay explicit |7273## Script Outputs (JSON Fields)7475| Script | Key Outputs |76|--------|-------------|77| `scripts/error_norm.py` | `error_norm`, `scale_min`, `scale_max` |78| `scripts/adaptive_step_controller.py` | `accept`, `dt_next`, `factor` |79| `scripts/integrator_selector.py` | `recommended`, `alternatives`, `notes` |80| `scripts/imex_split_planner.py` | `implicit_terms`, `explicit_terms`, `splitting_strategy` |81| `scripts/splitting_error_estimator.py` | `error_estimate`, `substeps` |8283## Workflow84851. **Classify stiffness** - Check eigenvalue spread or use stiffness_detector862. **Choose tolerances** - See `references/tolerance_guidelines.md`873. **Select integrator** - Run `scripts/integrator_selector.py`884. **Compute error norms** - Use `scripts/error_norm.py` for step acceptance895. **Adapt step size** - Use `scripts/adaptive_step_controller.py`906. **Plan IMEX/splitting** - If mixed stiff/nonstiff, use `scripts/imex_split_planner.py`917. **Validate convergence** - Repeat with tighter tolerances9293## Conversational Workflow Example9495**User**: I'm solving the Allen-Cahn equation with a stiff double-well potential. What integrator should I use?9697**Agent workflow**:981. Check integrator options:99 ```bash100 python3 scripts/integrator_selector.py --stiff --jacobian-available --accuracy high --json101 ```1022. Plan the IMEX splitting (diffusion implicit, reaction explicit):103 ```bash104 python3 scripts/imex_split_planner.py --stiff-terms diffusion --nonstiff-terms reaction --coupling weak --json105 ```1063. Recommend: Use IMEX-BDF2 with diffusion term implicit, double-well reaction explicit.107108## Pre-Integration Checklist109110- [ ] Identify stiffness and dominant time scales111- [ ] Set `rtol`/`atol` consistent with physics and units112- [ ] Confirm integrator compatibility with stiffness113- [ ] Use error norm to accept/reject steps114- [ ] Verify convergence with tighter tolerance run115116## CLI Examples117118```bash119# Select integrator for stiff problem with Jacobian120python3 scripts/integrator_selector.py --stiff --jacobian-available --accuracy high --json121122# Compute scaled error norm123python3 scripts/error_norm.py --error 0.01,0.02 --solution 1.0,2.0 --rtol 1e-3 --atol 1e-6 --json124125# Adaptive step control with PI controller126python3 scripts/adaptive_step_controller.py --dt 1e-2 --error-norm 0.8 --order 4 --controller pi --json127128# Plan IMEX splitting129python3 scripts/imex_split_planner.py --stiff-terms diffusion,elastic --nonstiff-terms reaction --coupling strong --json130131# Estimate splitting error132python3 scripts/splitting_error_estimator.py --dt 1e-4 --scheme strang --commutator-norm 50 --target-error 1e-6 --json133```134135## Error Handling136137| Error | Cause | Resolution |138|-------|-------|------------|139| `rtol and atol must be positive` | Invalid tolerances | Use positive values |140| `error-norm must be positive` | Negative error norm | Check error computation |141| `Unknown controller` | Invalid controller type | Use `i`, `pi`, or `pid` |142| `Splitting requires at least one term` | Empty term list | Specify stiff or nonstiff terms |143144## Interpretation Guidance145146### Error Norm Values147148| Error Norm | Meaning | Action |149|------------|---------|--------|150| < 1.0 | Step acceptable | Accept, maybe increase dt |151| ≈ 1.0 | At tolerance boundary | Accept with current dt |152| > 1.0 | Step rejected | Reject, reduce dt |153154### Controller Selection155156| Controller | Properties | Best For |157|------------|------------|----------|158| I (integral) | Simple, some overshoot | Non-stiff, moderate accuracy |159| PI (proportional-integral) | Smooth, robust | General use |160| PID | Aggressive adaptation | Rapidly varying dynamics |161162### IMEX Strategy163164| Coupling | Strategy |165|----------|----------|166| Weak | Simple operator splitting |167| Moderate | Strang splitting |168| Strong | Fully coupled IMEX-RK |169170## Security171172### Input Validation173- All numeric inputs (`dt`, `rtol`, `atol`, `error_norm`, `stiffness_ratio`, `commutator_norm`, etc.) are validated as finite numbers at the function boundary174- `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 lists175- Comma-separated value lists are capped at 100,000 entries to prevent resource exhaustion176- Numeric bounds enforced: `dimension` capped at 10 billion, `order` at 20, `stiffness_ratio` at 1e30177- `--controller` is validated against a fixed allowlist (`i`, `pi`, `pid`)178- `--scheme` is validated against known splitting schemes (`lie`, `strang`)179180### File Access181- Scripts read no external files; all inputs are provided via CLI arguments182- Scripts write only to stdout (JSON output); no files are created unless the agent explicitly uses the Write tool183184### Tool Restrictions185- **Read**: Used to inspect script source, references, and user configuration files186- **Write**: Used to save integrator recommendations or splitting plans; writes are scoped to the user's working directory187- **Grep/Glob**: Used to locate relevant files and search references188- The skill's `allowed-tools` excludes `Bash` to prevent the agent from executing arbitrary commands when processing user-provided inputs189190### Safety Measures191- No `eval()`, `exec()`, or dynamic code generation192- All subprocess calls use explicit argument lists (no `shell=True`)193- Reduced tool surface (no Bash) limits the agent to read/write operations only194- Term names are sanitized before use, preventing shell metacharacter injection195196## Limitations197198- **No automatic stiffness detection**: Use stiffness_detector from numerical-stability199- **Splitting assumes separability**: Terms must be cleanly separable200- **Jacobian requirement**: Some methods need analytical or numerical Jacobian201202## References203204- `references/method_catalog.md` - Integrator options and properties205- `references/tolerance_guidelines.md` - Choosing rtol/atol206- `references/error_control.md` - Error norm and adaptation formulas207- `references/imex_guidelines.md` - Stiff/non-stiff splitting208- `references/splitting_catalog.md` - Operator splitting patterns209- `references/multiphase_field_patterns.md` - Phase-field specific splits210211## Version History212213- **v1.1.0** (2024-12-24): Enhanced documentation, decision guidance, examples214- **v1.0.0**: Initial release with 5 integration scripts