numerical-stability

Original：🇺🇸 English

Translated

4 scriptsChecked / no sensitive code detected

Analyze and enforce numerical stability for time-dependent PDE simulations. Use when selecting time steps, choosing explicit/implicit schemes, diagnosing numerical blow-up, checking CFL/Fourier criteria, von Neumann analysis, matrix conditioning, or detecting stiffness in advection/diffusion/reaction problems.

1installs

Sourceheshamfs/materials-simulation-skills

Added on2026-02-22

NPX Install

npx skill4agent add heshamfs/materials-simulation-skills numerical-stability

SKILL.md Content

View Translation Comparison →

Numerical Stability

Goal

Provide a repeatable checklist and script-driven checks to keep time-dependent simulations stable and defensible.

Requirements

Python 3.8+
NumPy (for matrix_condition.py and von_neumann_analyzer.py)
See
```
scripts/requirements.txt
```
for dependencies

Inputs to Gather

Input	Description	Example
Grid spacing `dx`	Spatial discretization	`0.01 m`
Time step `dt`	Temporal discretization	`1e-4 s`
Velocity `v`	Advection speed	`1.0 m/s`
Diffusivity `D`	Thermal/mass diffusivity	`1e-5 m²/s`
Reaction rate `k`	First-order rate constant	`100 s⁻¹`
Dimensions	1D, 2D, or 3D	`2`
Scheme type	Explicit or implicit	`explicit`

Decision Guidance

Choosing Explicit vs Implicit

Is the problem stiff (fast + slow dynamics)?
├── YES → Use implicit or IMEX scheme
│         └── Check conditioning with matrix_condition.py
└── NO → Is CFL/Fourier satisfied with reasonable dt?
    ├── YES → Use explicit scheme (cheaper per step)
    └── NO → Consider implicit or reduce dx

Stability Limit Quick Reference

Physics	Number	Explicit Limit (1D)	Formula
Advection	CFL	C ≤ 1	`C = v·dt/dx`
Diffusion	Fourier	Fo ≤ 0.5	`Fo = D·dt/dx²`
Reaction	Reaction	R ≤ 1	`R = k·dt`

Multi-dimensional correction: For d dimensions, diffusion limit is

Fo ≤ 1/(2d)

.

Script Outputs (JSON Fields)

Script	Key Outputs
`scripts/cfl_checker.py`	`metrics.cfl` , `metrics.fourier` , `recommended_dt` , `stable`
`scripts/von_neumann_analyzer.py`	`results.max_amplification` , `results.stable`
`scripts/matrix_condition.py`	`results.condition_number` , `results.is_symmetric`
`scripts/stiffness_detector.py`	`results.stiffness_ratio` , `results.stiff` , `results.recommendation`

Workflow

Identify dominant physics (advection vs diffusion vs reaction)
Run CFL checker with
```
scripts/cfl_checker.py
```
Compare to limits and adjust
```
dt
```
if needed
Check stiffness with
```
scripts/stiffness_detector.py
```
if multiple scales
Analyze custom schemes with
```
scripts/von_neumann_analyzer.py
```
Check conditioning with
```
scripts/matrix_condition.py
```
for implicit solves
Document the stability verdict and recommended time step

Conversational Workflow Example

User: My phase-field simulation is blowing up after 100 steps. I'm using explicit Euler with dx=0.01, dt=1e-4, and diffusivity D=1e-3.

Agent workflow:

Check stability criteria:

bash

python3 scripts/cfl_checker.py --dx 0.01 --dt 1e-4 --diffusivity 1e-3 --dimensions 2 --json

Interpret results:
- Fourier number:
```
Fo = 1e-3 × 1e-4 / (0.01)² = 1.0
```
- 2D limit:
```
Fo ≤ 0.25
```
- Violation: Fo = 1.0 > 0.25, unstable!
Recommend fix:
- Reduce dt to
```
2.5e-5
```
  (to get Fo = 0.25)
- Or increase dx, or switch to implicit

Pre-Simulation Stability Checklist

Identify dominant physics and nondimensional groups
Compute CFL/Fourier/Reaction numbers with
```
cfl_checker.py
```
If explicit and limit violated, reduce
```
dt
```
or change scheme
If stiffness ratio > 1000, select implicit/stiff integrator
For custom schemes, verify amplification factor ≤ 1
Document stability reasoning with inputs and outputs

CLI Examples