numerical-stability

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

Python 3.8+
NumPy（用于matrix_condition.py和von_neumann_analyzer.py）
依赖项请查看
```
scripts/requirements.txt
```

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`

输入	说明	示例
网格间距 `dx`	空间离散化	`0.01 m`
时间步长 `dt`	时间离散化	`1e-4 s`
速度 `v`	平流速度	`1.0 m/s`
扩散系数 `D`	热/质量扩散系数	`1e-5 m²/s`
反应速率 `k`	一阶速率常数	`100 s⁻¹`
维度	1D、2D或3D	`2`
格式类型	显式或隐式	`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

问题是否具有刚性（快+慢动态特性）？
├── 是 → 使用隐式或IMEX格式
│         └── 用matrix_condition.py检查条件数
└── 否 → 合理的dt是否满足CFL/Fourier准则？
    ├── 是 → 使用显式格式（每步成本更低）
    └── 否 → 考虑隐式格式或减小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)

物理过程	无量纲数	显式格式限制（一维）	公式
平流	CFL	C ≤ 1	`C = v·dt/dx`
扩散	Fourier	Fo ≤ 0.5	`Fo = D·dt/dx²`
反应	反应数	R ≤ 1	`R = k·dt`

多维修正：对于d维，扩散限制为

Fo ≤ 1/(2d)

。

Script Outputs (JSON Fields)

脚本输出（JSON字段）

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`

脚本	关键输出
`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

识别主导物理过程（平流vs扩散vs反应）
运行CFL检查器，执行
```
scripts/cfl_checker.py
```
与限制值对比，必要时调整
```
dt
```
若存在多尺度，检查刚性，执行
```
scripts/stiffness_detector.py
```
用
scripts/von_neumann_analyzer.py
分析自定义格式
对隐式求解，用
scripts/matrix_condition.py
检查条件数
记录稳定性结论和推荐的时间步长

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

用户：我的相场模拟在100步后发生数值爆炸。我使用显式欧拉格式，dx=0.01，dt=1e-4，扩散系数D=1e-3。

Agent工作流程：

检查稳定性准则：

bash

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

解读结果：
- Fourier数：
```
Fo = 1e-3 × 1e-4 / (0.01)² = 1.0
```
- 二维限制：
```
Fo ≤ 0.25
```
- 违反准则：Fo = 1.0 > 0.25，不稳定！
推荐修复方案：
- 将dt减小到
```
2.5e-5
```
  （使Fo=0.25）
- 或者增大dx，或者切换到隐式格式

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

识别主导物理过程和无量纲数
用
```
cfl_checker.py
```
计算CFL/Fourier/反应数
若使用显式格式且违反限制，减小
```
dt
```
或更换格式
若刚性比>1000，选择隐式/刚性积分器
对自定义格式，验证放大因子≤1
记录稳定性分析结论、输入参数和输出结果

CLI Examples

CLI示例

bash

undefined

bash

undefined

Check CFL/Fourier for 2D diffusion-advection

检查二维平流-扩散问题的CFL/Fourier准则

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

对自定义3点模板进行冯·诺依曼分析

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

undefined

python3 scripts/matrix_condition.py --matrix A.npy --norm 2 --json

undefined

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

错误	原因	解决方法
`dx and dt must be positive`	输入零或负值	提供有效的正数
`No stability criteria applied`	缺少速度/扩散系数	至少提供一个物理参数
`Matrix file not found`	路径无效	检查矩阵文件是否存在
`Could not compute eigenvalues`	矩阵奇异或格式错误	检查矩阵有效性

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

场景	含义	操作
`stable: true`	所有检查的准则均满足	继续进行模拟
`stable: false`	至少违反了一项限制	减小dt或更换格式
`stable: null`	无法应用任何准则	提供更多物理输入参数
刚性比>1000	问题具有刚性	使用隐式积分器
条件数>10⁶	矩阵病态	使用缩放/预处理方法

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

仅支持显式格式的CFL/Fourier检查（隐式格式无条件稳定）
冯·诺依曼分析假设线性、常系数、周期性边界条件
刚性检测需要用户提供特征值估计值

References

参考资料

```
references/stability_criteria.md
```
- Decision thresholds and formulas
```
references/common_pitfalls.md
```
- Frequent failure modes and fixes
```
references/scheme_catalog.md
```
- Stability properties of common schemes

```
references/stability_criteria.md
```
- 决策阈值和公式
```
references/common_pitfalls.md
```
- 常见失效模式及修复方法
```
references/scheme_catalog.md
```
- 常见格式的稳定性特性

Version History

版本历史

v1.1.0 (2024-12-24): Enhanced documentation, decision guidance, examples
v1.0.0: Initial release with 4 stability analysis scripts

v1.1.0 (2024-12-24)：增强文档、决策指导和示例
v1.0.0：初始版本，包含4个稳定性分析脚本