numerical-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

Python 3.8+
NumPy（部分脚本需要）
核心功能无重型依赖

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`

输入项	描述	示例
问题类型	ODE/PDE、刚性/非刚性	`stiff PDE`
可获取雅可比矩阵	是否能计算∂f/∂u？	`yes`
目标精度	期望的误差水平	`1e-6`
约束条件	内存限制、是否允许使用隐式方法？	`implicit OK`
时间尺度	特征时间	`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

问题是否为刚性？
├── 是 → 是否可获取雅可比矩阵？
│   ├── 是 → 使用Rosenbrock或BDF
│   └── 否 → 使用带数值雅可比矩阵的BDF
└── 否 → 是否需要高精度？
    ├── 是 → 使用RK45或DOP853
    └── 否 → 使用RK4或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

特征	大概率为刚性	处理措施
dt缩小至极小值	是	切换为隐式方法
特征值跨越多个数量级	是	使用BDF/Radau
解平滑、dt合理	否	保留显式方法

Script Outputs (JSON Fields)

脚本输出（JSON字段）

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`

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

分类刚性 - 检查特征值分布或使用stiffness_detector
设置容限 - 参考
```
references/tolerance_guidelines.md
```
选择积分器 - 运行
```
scripts/integrator_selector.py
```
计算误差范数 - 使用
```
scripts/error_norm.py
```
进行步长接受判断
自适应步长 - 使用
```
scripts/adaptive_step_controller.py
```
规划IMEX/分裂 - 若为混合刚性/非刚性问题，使用
```
scripts/imex_split_planner.py
```
验证收敛性 - 使用更严格的容限重复运行

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:

bash

python3 scripts/integrator_selector.py --stiff --jacobian-available --accuracy high --json

Plan the IMEX splitting (diffusion implicit, reaction explicit):

bash

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.

用户：我正在求解带刚性双势阱的Allen-Cahn方程，应该使用哪种积分器？

Agent工作流:

检查积分器选项:

bash

python3 scripts/integrator_selector.py --stiff --jacobian-available --accuracy high --json

规划IMEX分裂（扩散项隐式，反应项显式）:

bash

python3 scripts/imex_split_planner.py --stiff-terms diffusion --nonstiff-terms reaction --coupling weak --json

推荐：使用IMEX-BDF2，其中扩散项采用隐式，双势阱反应项采用显式。

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

识别刚性和主导时间尺度
设置与物理规律和单位一致的
```
rtol
```
/
```
atol
```
确认积分器与刚性问题的兼容性
使用误差范数判断步长是否接受
通过更严格容限的运行验证收敛性

CLI Examples

CLI示例

bash

undefined

bash

undefined

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

使用PI控制器进行自适应步长控制

python3 scripts/adaptive_step_controller.py --dt 1e-2 --error-norm 0.8 --order 4 --controller pi --json

Plan IMEX splitting

规划IMEX分裂

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

undefined

python3 scripts/splitting_error_estimator.py --dt 1e-4 --scheme strang --commutator-norm 50 --target-error 1e-6 --json

undefined

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

错误信息	原因	解决方法
`rtol and atol must be positive`	容限设置无效	使用正值
`error-norm must be positive`	误差范数为负	检查误差计算过程
`Unknown controller`	控制器类型无效	使用 `i` 、 `pi` 或 `pid`
`Splitting requires at least one term`	项列表为空	指定刚性或非刚性项

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

误差范数	含义	处理措施
< 1.0	步长可接受	接受步长，可尝试增大dt
≈ 1.0	处于容限边界	接受当前dt
> 1.0	步长被拒绝	拒绝步长，减小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

控制器	特性	最佳适用场景
I（积分型）	简单，存在一定过冲	非刚性问题、中等精度需求
PI（比例-积分型）	平滑、鲁棒	通用场景
PID	自适应调整激进	快速变化的动力学系统

IMEX Strategy

IMEX策略

Coupling	Strategy
Weak	Simple operator splitting
Moderate	Strang splitting
Strong	Fully coupled IMEX-RK

耦合强度	策略
弱	简单算子分裂
中等	Strang分裂
强	完全耦合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

无自动刚性检测：需使用numerical-stability中的stiffness_detector
分裂假设可分离性：项必须能清晰分离
雅可比矩阵要求：部分方法需要解析或数值雅可比矩阵

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

```
references/method_catalog.md
```
- 积分器选项及特性
```
references/tolerance_guidelines.md
```
- rtol/atol选择指南
```
references/error_control.md
```
- 误差范数与自适应公式
```
references/imex_guidelines.md
```
- 刚性/非刚性分裂指南
```
references/splitting_catalog.md
```
- 算子分裂模式
```
references/multiphase_field_patterns.md
```
- 相场特定分裂模式

Version History

版本历史

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

v1.1.0 (2024-12-24)：增强文档、决策指导及示例
v1.0.0：初始版本，包含5个积分相关脚本