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 P/PI step-size 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/heshamfs/numerical-integration17 author: HeshamFS18 version: "1.2.2"19 security_tier: medium20 security_reviewed: true21 tested_with:22 - claude-code23 last_evaluated: "2026-06-24"24 eval_cases: 425 last_reviewed: "2026-06-23"26 standards:27 - "Hairer, Norsett & Wanner, Solving Ordinary Differential Equations I (Nonstiff): RK45 (Dormand-Prince), DOP853, embedded error estimation"28 - "Hairer & Wanner, Solving ODEs II (Stiff and DAE): BDF, Radau IIA, Rosenbrock methods"29 - "Gustafsson (1991/1994), control-theoretic PI step-size control"30 - "Strang (1968), operator splitting; with Lie-Trotter and Marchuk-Strang variants"31 - "Eyre (1998), unconditionally gradient-stable convex splitting for phase-field (Allen-Cahn / Cahn-Hilliard)"32---3334# Numerical Integration3536## Goal3738Provide a reliable workflow to select integrators, set tolerances, and manage adaptive time stepping for time-dependent simulations.3940## Requirements4142- Python 3.10+43- NumPy (for some scripts)44- No heavy dependencies for core functionality4546## Inputs to Gather4748| Input | Description | Example |49|-------|-------------|---------|50| Problem type | ODE/PDE, stiff/non-stiff | `stiff PDE` |51| Jacobian available | Can compute ∂f/∂u? | `yes` |52| Target accuracy | Desired error level | `1e-6` |53| Constraints | Memory, implicit allowed? | `implicit OK` |54| Time scale | Characteristic time | `1e-3 s` |5556## Decision Guidance5758### Choosing an Integrator5960```61Is the problem stiff?62├── YES → Is Jacobian available?63│ ├── YES → Use Rosenbrock or BDF64│ └── NO → Use BDF with numerical Jacobian65└── NO → Is high accuracy needed?66 ├── YES → Use RK45 or DOP85367 └── NO → Use RK4 or Adams-Bashforth68```6970### Stiff vs Non-Stiff Detection7172| Symptom | Likely Stiff | Action |73|---------|--------------|--------|74| dt shrinks to tiny values | Yes | Switch to implicit |75| Eigenvalues span many decades | Yes | Use BDF/Radau |76| Smooth solution, reasonable dt | No | Stay explicit |7778## Script Outputs (JSON Fields)7980| Script | Key Outputs |81|--------|-------------|82| `scripts/error_norm.py` | `error_norm`, `scale_min`, `scale_max` |83| `scripts/adaptive_step_controller.py` | `accept`, `dt_next`, `factor` |84| `scripts/integrator_selector.py` | `recommended`, `alternatives`, `notes` |85| `scripts/imex_split_planner.py` | `implicit_terms`, `explicit_terms`, `splitting_strategy` |86| `scripts/splitting_error_estimator.py` | `error_estimate`, `substeps` |8788## Workflow89901. **Classify stiffness** - Check eigenvalue spread or use stiffness_detector912. **Choose tolerances** - See `references/tolerance_guidelines.md`923. **Select integrator** - Run `scripts/integrator_selector.py`934. **Compute error norms** - Use `scripts/error_norm.py` for step acceptance945. **Adapt step size** - Use `scripts/adaptive_step_controller.py`956. **Plan IMEX/splitting** - If mixed stiff/nonstiff, use `scripts/imex_split_planner.py`967. **Validate convergence** - Repeat with tighter tolerances9798## Conversational Workflow Example99100**User**: I'm solving the Allen-Cahn equation with a stiff double-well potential. What integrator should I use?101102**Agent workflow**:1031. Check integrator options:104 ```bash105 python3 scripts/integrator_selector.py --stiff --jacobian-available --accuracy high --json106 ```1072. Plan the IMEX splitting (diffusion implicit, reaction explicit):108 ```bash109 python3 scripts/imex_split_planner.py --stiff-terms diffusion --nonstiff-terms reaction --coupling weak --json110 ```1113. Recommend: Use IMEX-BDF2 with diffusion term implicit, double-well reaction explicit.112113## Pre-Integration Checklist114115- [ ] Identify stiffness and dominant time scales116- [ ] Set `rtol`/`atol` consistent with physics and units117- [ ] Confirm integrator compatibility with stiffness118- [ ] Use error norm to accept/reject steps119- [ ] Verify convergence with tighter tolerance run120121## CLI Examples122123```bash124# Select integrator for stiff problem with Jacobian125python3 scripts/integrator_selector.py --stiff --jacobian-available --accuracy high --json126127# Compute scaled error norm128python3 scripts/error_norm.py --error 0.01,0.02 --solution 1.0,2.0 --rtol 1e-3 --atol 1e-6 --json129130# Adaptive step control with PI controller131python3 scripts/adaptive_step_controller.py --dt 1e-2 --error-norm 0.8 --order 4 --controller pi --json132133# Plan IMEX splitting134python3 scripts/imex_split_planner.py --stiff-terms diffusion,elastic --nonstiff-terms reaction --coupling strong --json135136# Estimate splitting error137python3 scripts/splitting_error_estimator.py --dt 1e-4 --scheme strang --commutator-norm 50 --target-error 1e-6 --json138```139140## Error Handling141142| Error | Cause | Resolution |143|-------|-------|------------|144| `rtol must be a non-negative finite number` / `atol must be a non-negative finite number` | Invalid tolerances | Use non-negative finite values |145| `error_norm must be finite and non-negative` | Negative or non-finite error norm | Check error computation |146| `scale must be positive; with min_scale=0 ensure atol>0 or rtol*\|y\|>0` | All scale entries collapsed to 0 (e.g. `rtol=0`, `atol=0`, default `min_scale=0`) | Set `atol>0`, `rtol>0`, or `--min-scale` > 0 |147| `argument --controller: invalid choice: ... (choose from p, pi)` | Invalid controller type | Use `p` or `pi` |148| `Provide at least one stiff or non-stiff term` | Empty term list | Specify stiff or nonstiff terms |149150## Interpretation Guidance151152### Error Norm Values153154| Error Norm | Meaning | Action |155|------------|---------|--------|156| < 1.0 | Step acceptable | Accept, maybe increase dt |157| ≈ 1.0 | At tolerance boundary | Accept with current dt |158| > 1.0 | Step rejected | Reject, reduce dt |159160### Controller Selection161162| Controller | CLI value | Properties | Best For |163|------------|-----------|------------|----------|164| P (elementary / integral) | `p` (default) | Simple, some overshoot | Non-stiff, moderate accuracy |165| PI (proportional-integral) | `pi` | Smooth, robust (requires `--prev-error`) | General use |166167> PID control is described in `references/error_control.md` for reference only; the168> `adaptive_step_controller.py` CLI implements `p` and `pi` controllers.169170### IMEX Strategy171172| Coupling | Strategy |173|----------|----------|174| Weak | Simple operator splitting |175| Moderate | Strang splitting |176| Strong | Fully coupled IMEX-RK |177178## Verification checklist179180- [ ] Recorded the scaled `error_norm` (and `scale_min`/`scale_max`) from `scripts/error_norm.py` and confirmed `scale_min > 0`, so no component reduced to atol-only scaling by accident.181- [ ] Confirmed each accepted step has `error_norm <= accept_threshold` (default 1.0) per `scripts/adaptive_step_controller.py`; logged any `accept: false` steps and the resulting `dt_next`/`factor` rather than forcing the step through.182- [ ] For the PI controller, supplied `--prev-error` and verified `controller_used` reported `pi` (not the silent `p` fallback that occurs when `--prev-error` is omitted).183- [ ] Ran `scripts/integrator_selector.py` with the actual `--stiff`/`--jacobian-available`/`--accuracy` flags matching the problem and recorded `recommended` plus the `notes` (e.g. the "expect smaller dt" warning for stiff-without-implicit).184- [ ] For operator splitting, recorded `error_estimate`, `substeps`, and `dt_effective` from `scripts/splitting_error_estimator.py` and confirmed `error_estimate <= target-error` after substepping, using the correct `--scheme` order (lie=1, strang=2).185- [ ] Ran the convergence validation (Workflow step 7): repeated with tighter `rtol`/`atol` and confirmed the solution change is below the target accuracy, rather than trusting a single tolerance run.186187## Common pitfalls & rationalizations188189| Tempting shortcut | Why it's wrong / what to do |190|-------------------|-----------------------------|191| "I picked an implicit/BDF method, so any `dt` is fine." | Unconditional *stability* is not *accuracy*; large `dt` still inflates temporal error. Check `error_norm` against the accept threshold and run the tighter-tolerance convergence check (Workflow step 7). |192| "`error_norm` came back < 1, so the step and the whole run are correct." | The norm only certifies the local step under the chosen `rtol`/`atol`. A loose tolerance passes every step while the global solution is wrong — tighten tolerances and confirm convergence before trusting results. |193| "I'll use the PI controller for smoother stepping" but omit `--prev-error`. | Without `--prev-error` the script silently falls back to the P controller (`controller_used: p`). You get no PI benefit. Pass the previous accepted `error_norm` and verify `controller_used: pi`. |194| "Strang vs Lie splitting won't matter much here." | Splitting error scales as `commutator_norm * dt^(order+1)` with order 1 (lie) vs 2 (strang). For a nonzero commutator the schemes differ by a full power of `dt` — run `splitting_error_estimator.py` with the actual `--commutator-norm` and `--target-error` instead of guessing. |195| "The selector recommended IMEX/RK-Chebyshev, so I'll just run explicitly without a Jacobian." | That branch fires only for stiff problems *without* implicit solves and the script warns "expect smaller dt." Read the `notes`: provide a Jacobian/Jv product and use BDF/Radau if implicit solves are feasible. |196| "It ran to the final time without crashing, so the integration is valid." | Completion is not correctness. Verify step acceptance (`error_norm <= threshold`), splitting error within `target-error`, and convergence under tighter tolerances; for conservative problems pass `--conservative` to `imex_split_planner.py` and check conserved quantities. |197198## Security199200### Input Validation201- All numeric inputs (`dt`, `rtol`, `atol`, `error_norm`, `stiffness_ratio`, `commutator_norm`, etc.) are validated as finite numbers at the function boundary202- `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 lists203- Comma-separated value lists are capped at 100,000 entries to prevent resource exhaustion204- Numeric bounds enforced: `dimension` capped at 10 billion, `order` at 20, `stiffness_ratio` at 1e30205- `--controller` is validated against a fixed allowlist (`p`, `pi`)206- `--scheme` is validated against known splitting schemes (`lie`, `strang`)207208### File Access209- Scripts read no external files; all inputs are provided via CLI arguments210- Scripts write only to stdout (JSON output); no files are created unless the agent explicitly uses the Write tool211212### Tool Restrictions213- **Read**: Used to inspect script source, references, and user configuration files214- **Write**: Used to save integrator recommendations or splitting plans; writes are scoped to the user's working directory215- **Grep/Glob**: Used to locate relevant files and search references216- The skill's `allowed-tools` excludes `Bash` to prevent the agent from executing arbitrary commands when processing user-provided inputs217218### Safety Measures219- No `eval()`, `exec()`, or dynamic code generation220- All subprocess calls use explicit argument lists (no `shell=True`)221- Reduced tool surface (no Bash) limits the agent to read/write operations only222- Term names are sanitized before use, preventing shell metacharacter injection223224## Limitations225226- **No automatic stiffness detection**: Use stiffness_detector from numerical-stability227- **Splitting assumes separability**: Terms must be cleanly separable228- **Jacobian requirement**: Some methods need analytical or numerical Jacobian229230## References231232- `references/method_catalog.md` - Integrator options and properties233- `references/tolerance_guidelines.md` - Choosing rtol/atol234- `references/error_control.md` - Error norm and adaptation formulas235- `references/imex_guidelines.md` - Stiff/non-stiff splitting236- `references/splitting_catalog.md` - Operator splitting patterns237- `references/multiphase_field_patterns.md` - Phase-field specific splits238239## Version History240241- **v1.2.2** (2026-06-24): Added Verification checklist and Common pitfalls & rationalizations sections grounding step acceptance, PI controller usage, integrator selection, and splitting-error checks in the scripts' actual outputs242- **v1.2.0** (2026-06-23): Fixed PI controller coefficient/sign to standard form, fixed error_norm scale-collapse crash, corrected error-message and controller documentation to match the scripts243- **v1.1.0** (2024-12-24): Enhanced documentation, decision guidance, examples244- **v1.0.0**: Initial release with 5 integration scripts