What if a Jacobian isn’t available for a stiff problem?

Use BDF with a numerical Jacobian to maintain stability, or switch to an explicit method only if the problem is non-stiff.

How should I choose tolerances (rtol/atol)?

Set them to reflect the physics, units, and desired accuracy; consult tolerance guidelines referenced in the workflow and adjust after convergence checks.

When should I prefer implicit over explicit methods?

If stiffness is detected (rapidly decaying modes, eigenvalue spread, shrinking dt), prefer implicit (Rosenbrock/BDF). If the problem is non-stiff and high accuracy is needed, explicit methods like RK45 or DOP853 are suitable.

numerical-integration

npx machina-cli add skill HeshamFS/materials-simulation-skills/numerical-integration --openclaw

Files (1)

SKILL.md

6.1 KB

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

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

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

Source

git clone https://github.com/HeshamFS/materials-simulation-skills/blob/main/skills/core-numerical/numerical-integration/SKILL.md

View on GitHub

Overview

Provides a practical workflow to pick integrators, set tolerances, and manage adaptive time stepping for time-dependent simulations. It covers stiffness assessment, IMEX splitting planning, and choosing explicit versus implicit schemes (e.g., Rosenbrock, BDF, RK45, DOP853) to meet accuracy and performance goals.

How This Skill Works

Classify stiffness and dominant time scales, then choose an appropriate integrator (RK4, RK45, DOP853, BDF, Rosenbrock) or IMEX split. Set rtol/atol, run error norm and adaptive step tests, and adjust dt_next with a controller. Use dedicated scripts (integrator_selector, error_norm, adaptive_step_controller, imex_split_planner) to guide the workflow.

When to Use It

You have a stiff PDE/ODE system and want implicit integration (with potential Jacobian availability).
You need high accuracy and can use explicit methods like RK45 or DOP853 for non-stiff problems.
You want adaptive time stepping to balance error control and performance.
You are planning IMEX splitting for mixed stiff/nonstiff terms (e.g., diffusion implicit, reaction explicit).
You are diagnosing convergence or selecting an integrator with stiffness detection evidence (eigenvalue spread, dt behavior).

Quick Start

Step 1: Classify stiffness and set initial tolerances, then select an integrator with the integrator_selector script (e.g., python3 scripts/integrator_selector.py --stiff --jacobian-available --accuracy high --json).
Step 2: If mixed stiffness exists, plan IMEX splitting with imex_split_planner (e.g., python3 scripts/imex_split_planner.py --stiff-terms diffusion --nonstiff-terms reaction --coupling weak --json).
Step 3: Run with the recommended method and verify via error norms and adaptive stepping (e.g., use error_norm.py and adaptive_step_controller.py; adjust rtol/atol as needed).

Best Practices

Identify stiffness early by checking eigenvalue spread or using a stiffness detector.
Set rtol/atol consistently with physics units and desired accuracy.
If a Jacobian is available and the problem is stiff, prefer Rosenbrock or BDF; if not available, use BDF with a numerical Jacobian.
For non-stiff problems requiring accuracy, prefer RK45 or DOP853; for cheaper schemes, RK4 or Adams-Bashforth can suffice.
Validate convergence by repeating runs with tighter tolerances and verifying consistent results.

Example Use Cases

Allen-Cahn equation with a stiff double-well potential analyzed via IMEX-BDF2 with diffusion implicit and reaction explicit.
Stiff PDE with diffusion-reaction coupling where IMEX splitting is planned to balance stiffness and speed.
Non-stiff ODE system where RK45 or DOP853 achieves high accuracy efficiently.
Problem with available Jacobian demonstrating Rosenbrock or BDF choice for stiff dynamics.
Mixed stiff/nonstiff system requiring explicit terms for non-stiff components and implicit terms for stiff components.

Frequently Asked Questions

Add this skill to your agents