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:
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
CLI Examples
# Check CFL/Fourier for 2D diffusion-advection
python3 scripts/cfl_checker.py --dx 0.1 --dt 0.01 --velocity 1.0 --diffusivity 0.1 --dimensions 2 --json
# Von Neumann analysis for custom 3-point stencil
python3 scripts/von_neumann_analyzer.py --coeffs 0.2,0.6,0.2 --dx 1.0 --nk 128 --json
# Detect stiffness from eigenvalue estimates
python3 scripts/stiffness_detector.py --eigs=-1,-1000 --json
# Check matrix conditioning for implicit system
python3 scripts/matrix_condition.py --matrix A.npy --norm 2 --json
Error Handling
| Error |
Cause |
Resolution |
dx and dt must be positive |
Zero or negative values |
Provide valid positive numbers |
No stability criteria applied |
Missing velocity/diffusivity |
Provide at least one physics parameter |
Matrix file not found |
Invalid path |
Check matrix file exists |
Could not compute eigenvalues |
Singular or ill-formed matrix |
Check matrix validity |
Interpretation Guidance
| Scenario |
Meaning |
Action |
stable: true |
All checked criteria satisfied |
Proceed with simulation |
stable: false |
At least one limit violated |
Reduce dt or change scheme |
stable: null |
No criteria could be applied |
Provide more physics inputs |
| Stiffness ratio > 1000 |
Problem is stiff |
Use implicit integrator |
| Condition number > 10⁶ |
Ill-conditioned |
Use scaling/preconditioning |
Limitations
- Explicit schemes only for CFL/Fourier checks (implicit is unconditionally stable)
- Von Neumann analysis assumes linear, constant-coefficient, periodic BCs
- Stiffness detection requires eigenvalue estimates from user
References
references/stability_criteria.md - Decision thresholds and formulasreferences/common_pitfalls.md - Frequent failure modes and fixesreferences/scheme_catalog.md - Stability properties of common schemes
Version History
- v1.1.0 (2024-12-24): Enhanced documentation, decision guidance, examples
- v1.0.0: Initial release with 4 stability analysis scripts
1---2name: numerical-stability3description: 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.4---5
6# Numerical Stability
7
8## Goal
9
10Provide a repeatable checklist and script-driven checks to keep time-dependent simulations stable and defensible.
11
12## Requirements
13
14- Python 3.8+
15- NumPy (for matrix_condition.py and von_neumann_analyzer.py)
16- See `scripts/requirements.txt` for dependencies
17
18## Inputs to Gather
19
20| Input | Description | Example |
21|-------|-------------|---------|
22| Grid spacing `dx` | Spatial discretization | `0.01 m` |
23| Time step `dt` | Temporal discretization | `1e-4 s` |
24| Velocity `v` | Advection speed | `1.0 m/s` |
25| Diffusivity `D` | Thermal/mass diffusivity | `1e-5 m²/s` |
26| Reaction rate `k` | First-order rate constant | `100 s⁻¹` |
27| Dimensions | 1D, 2D, or 3D | `2` |
28| Scheme type | Explicit or implicit | `explicit` |
29
30## Decision Guidance
31
32### Choosing Explicit vs Implicit
33
34```
35Is the problem stiff (fast + slow dynamics)?
36├── YES → Use implicit or IMEX scheme
37│ └── Check conditioning with matrix_condition.py
38└── NO → Is CFL/Fourier satisfied with reasonable dt?
39 ├── YES → Use explicit scheme (cheaper per step)
40 └── NO → Consider implicit or reduce dx
41```
42
43### Stability Limit Quick Reference
44
45| Physics | Number | Explicit Limit (1D) | Formula |
46|---------|--------|---------------------|---------|
47| Advection | CFL | C ≤ 1 | `C = v·dt/dx` |
48| Diffusion | Fourier | Fo ≤ 0.5 | `Fo = D·dt/dx²` |
49| Reaction | Reaction | R ≤ 1 | `R = k·dt` |
50
51**Multi-dimensional correction**: For d dimensions, diffusion limit is `Fo ≤ 1/(2d)`.
52
53## Script Outputs (JSON Fields)
54
55| Script | Key Outputs |
56|--------|-------------|
57| `scripts/cfl_checker.py` | `metrics.cfl`, `metrics.fourier`, `recommended_dt`, `stable` |
58| `scripts/von_neumann_analyzer.py` | `results.max_amplification`, `results.stable` |
59| `scripts/matrix_condition.py` | `results.condition_number`, `results.is_symmetric` |
60| `scripts/stiffness_detector.py` | `results.stiffness_ratio`, `results.stiff`, `results.recommendation` |
61
62## Workflow
63
641. **Identify dominant physics** (advection vs diffusion vs reaction)
652. **Run CFL checker** with `scripts/cfl_checker.py`
663. **Compare to limits** and adjust `dt` if needed
674. **Check stiffness** with `scripts/stiffness_detector.py` if multiple scales
685. **Analyze custom schemes** with `scripts/von_neumann_analyzer.py`
696. **Check conditioning** with `scripts/matrix_condition.py` for implicit solves
707. **Document** the stability verdict and recommended time step
71
72## Conversational Workflow Example
73
74**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.
75
76**Agent workflow**:
771. Check stability criteria:
78 ```bash
79 python3 scripts/cfl_checker.py --dx 0.01 --dt 1e-4 --diffusivity 1e-3 --dimensions 2 --json
80 ```
812. Interpret results:
82 - Fourier number: `Fo = 1e-3 × 1e-4 / (0.01)² = 1.0`
83 - 2D limit: `Fo ≤ 0.25`
84 - **Violation**: Fo = 1.0 > 0.25, unstable!
853. Recommend fix:
86 - Reduce dt to `2.5e-5` (to get Fo = 0.25)
87 - Or increase dx, or switch to implicit
88
89## Pre-Simulation Stability Checklist
90
91- [ ] Identify dominant physics and nondimensional groups
92- [ ] Compute CFL/Fourier/Reaction numbers with `cfl_checker.py`
93- [ ] If explicit and limit violated, reduce `dt` or change scheme
94- [ ] If stiffness ratio > 1000, select implicit/stiff integrator
95- [ ] For custom schemes, verify amplification factor ≤ 1
96- [ ] Document stability reasoning with inputs and outputs
97
98## CLI Examples
99
100```bash
101# Check CFL/Fourier for 2D diffusion-advection
102python3 scripts/cfl_checker.py --dx 0.1 --dt 0.01 --velocity 1.0 --diffusivity 0.1 --dimensions 2 --json
103
104# Von Neumann analysis for custom 3-point stencil
105python3 scripts/von_neumann_analyzer.py --coeffs 0.2,0.6,0.2 --dx 1.0 --nk 128 --json
106
107# Detect stiffness from eigenvalue estimates
108python3 scripts/stiffness_detector.py --eigs=-1,-1000 --json
109
110# Check matrix conditioning for implicit system
111python3 scripts/matrix_condition.py --matrix A.npy --norm 2 --json
112```
113
114## Error Handling
115
116| Error | Cause | Resolution |
117|-------|-------|------------|
118| `dx and dt must be positive` | Zero or negative values | Provide valid positive numbers |
119| `No stability criteria applied` | Missing velocity/diffusivity | Provide at least one physics parameter |
120| `Matrix file not found` | Invalid path | Check matrix file exists |
121| `Could not compute eigenvalues` | Singular or ill-formed matrix | Check matrix validity |
122
123## Interpretation Guidance
124
125| Scenario | Meaning | Action |
126|----------|---------|--------|
127| `stable: true` | All checked criteria satisfied | Proceed with simulation |
128| `stable: false` | At least one limit violated | Reduce dt or change scheme |
129| `stable: null` | No criteria could be applied | Provide more physics inputs |
130| Stiffness ratio > 1000 | Problem is stiff | Use implicit integrator |
131| Condition number > 10⁶ | Ill-conditioned | Use scaling/preconditioning |
132
133## Limitations
134
135- **Explicit schemes only** for CFL/Fourier checks (implicit is unconditionally stable)
136- **Von Neumann analysis** assumes linear, constant-coefficient, periodic BCs
137- **Stiffness detection** requires eigenvalue estimates from user
138
139## References
140
141- `references/stability_criteria.md` - Decision thresholds and formulas
142- `references/common_pitfalls.md` - Frequent failure modes and fixes
143- `references/scheme_catalog.md` - Stability properties of common schemes
144
145## Version History
146
147- **v1.1.0** (2024-12-24): Enhanced documentation, decision guidance, examples
148- **v1.0.0**: Initial release with 4 stability analysis scripts
tools-only