luokai0 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.txtfor 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
dtif needed - Check stiffness with
scripts/stiffness_detector.pyif multiple scales - Analyze custom schemes with
scripts/von_neumann_analyzer.py - Check conditioning with
scripts/matrix_condition.pyfor 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!
- Fourier number:
- Recommend fix:
- Reduce dt to
2.5e-5(to get Fo = 0.25) - Or increase dx, or switch to implicit
- Reduce dt to
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
dtor 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
# 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