numerical-integration

数值积分

目标

提供可靠的工作流，以选择积分器、设置容差并管理时变模拟中的自适应时间步进。

要求

• Python 3.10+
• NumPy（用于部分脚本）
• 核心功能无需重型依赖

需要收集的输入

输入	说明	示例
问题类型	ODE/PDE，刚性/非刚性	stiff PDE
是否提供雅可比矩阵	能否计算 ∂f/∂u？	yes
目标精度	所需误差级别	1e-6
约束条件	内存、是否允许隐式方法？	implicit OK
时间尺度	特征时间	1e-3 s

决策指南

选择积分器

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

刚性与非刚性的判别

症状	可能为刚性	操作
dt 缩小到极小值	是	切换到隐式方法
特征值跨越多个数量级	是	使用 BDF/Radau
解平滑，dt 合理	否	继续使用显式方法

脚本输出（JSON 字段）

脚本	主要输出
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

工作流

1. 判断刚性 - 检查特征值分布范围，或使用 stiffness_detector
2. 选择容差 - 参阅 references/tolerance_guidelines.md
3. 选择积分器 - 运行 scripts/integrator_selector.py
4. 计算误差范数 - 使用 scripts/error_norm.py 判断是否接受步长
5. 调整步长 - 使用 scripts/adaptive_step_controller.py
6. 规划 IMEX/算子分裂 - 若刚性与非刚性项混合，使用 scripts/imex_split_planner.py
7. 验证收敛性 - 使用更严格的容差重复计算

对话式工作流示例

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

Agent 工作流：

1. 检查积分器选项：

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

2. 规划 IMEX 算子分裂（扩散项隐式，反应项显式）：

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

3. 建议：使用 IMEX-BDF2，将扩散项设为隐式，将双阱反应项设为显式。

积分前检查清单

• 确定刚性和主导时间尺度
• 设置与物理特性和单位一致的 rtol/atol
• 确认积分器适用于该刚性问题
• 使用误差范数接受或拒绝步长
• 使用更严格容差再次运行，验证收敛性

CLI 示例

# 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
python3 scripts/adaptive_step_controller.py --dt 1e-2 --error-norm 0.8 --order 4 --controller pi --json

# Plan IMEX splitting
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

错误处理

错误	原因	解决方法
rtol must be a non-negative finite number / atol must be a non-negative finite number	容差无效	使用非负有限值
error_norm must be finite and non-negative	误差范数为负或非有限值	检查误差计算
scale must be positive; with min_scale=0 ensure atol>0 or rtol*|y|>0	所有尺度条目都变为 0（例如 rtol=0、atol=0、默认 min_scale=0）	设置 atol>0、rtol>0，或将 --min-scale 设为大于 0
argument --controller: invalid choice: ... (choose from p, pi)	控制器类型无效	使用 p 或 pi
Provide at least one stiff or non-stiff term	项列表为空	指定刚性项或非刚性项

结果解读指南

误差范数值

误差范数	含义	操作
< 1.0	步长可接受	接受，可适当增大 dt
≈ 1.0	位于容差边界	按当前 dt 接受
> 1.0	步长被拒绝	拒绝并减小 dt

控制器选择

控制器	CLI 值	特性	适用场景
P（初等／积分）	p（默认）	简单，有一定超调	非刚性、精度要求适中
PI（比例-积分）	pi	平滑、稳健（需要 --prev-error）	通用场景

PID 控制在 references/error_control.md 中介绍，仅供参考；adaptive_step_controller.py CLI 实现了 p 和 pi 控制器。

IMEX 策略

耦合程度	策略
弱	简单算子分裂
中等	Strang 分裂
强	完全耦合的 IMEX-RK

验证清单

• 记录 scripts/error_norm.py 输出的缩放后 error_norm（以及 scale_min/scale_max），并确认 scale_min > 0，确保没有组件意外地仅按 atol 缩放。
• 根据 scripts/adaptive_step_controller.py 确认每个接受的步均满足 error_norm <= accept_threshold（默认值为 1.0）；记录所有 accept: false 的步及其产生的 dt_next/factor，不要强行接受这些步。
• 对于 PI 控制器，传入 --prev-error，并确认 controller_used 报告的是 pi（而不是省略 --prev-error 时静默回退到的 p）。
• 使用与问题匹配的实际 --stiff/--jacobian-available/--accuracy 标志运行 scripts/integrator_selector.py，并记录 recommended 和 notes（例如，针对无隐式求解的刚性问题，警告会提示“预期需要更小的 dt”）。
• 对于算子分裂，记录 scripts/splitting_error_estimator.py 输出的 error_estimate、substeps 和 dt_effective，并确认子步进后 error_estimate <= target-error，同时使用正确的 --scheme 阶数（lie=1，strang=2）。
• 运行收敛验证（工作流第 7 步）：使用更严格的 rtol/atol 重复计算，并确认解的变化小于目标精度，而不是只相信单次容差运行。

常见陷阱与自我安慰

看似省事的做法	错误原因／正确做法
“我选了隐式／BDF 方法，所以任意 dt 都没问题。”	无条件的稳定性不等于精度；较大的 dt 仍会增大时间误差。检查 error_norm 是否低于接受阈值，并运行更严格容差下的收敛检查（工作流第 7 步）。
“error_norm 小于 1，所以这一步和整个计算都是正确的。”	该范数只能在所选 rtol/atol 下验证局部步。容差过宽时，每一步都可能通过，但全局解仍然错误——收紧容差并确认收敛后再相信结果。
“我想用 PI 控制器让步进更平滑”，却省略了 --prev-error。	不传入 --prev-error 时，脚本会静默回退到 P 控制器（controller_used: p）。这样就无法获得 PI 的效果。传入上一个已接受步的 error_norm，并确认 controller_used: pi。
“这里 Strang 分裂和 Lie 分裂的差别应该不大。”	分裂误差按 commutator_norm * dt^(order+1) 缩放，阶数分别为 1（lie）和 2（strang）。当对易子非零时，两种方案相差整整一个 dt 的幂次——不要猜测，应使用实际的 --commutator-norm 和 --target-error 运行 splitting_error_estimator.py。
“选择器推荐了 IMEX/RK-Chebyshev，所以我不提供 Jacobian，直接显式运行就行。”	只有在刚性问题且没有隐式求解时才会进入该分支，脚本还会警告“预期需要更小的 dt”。查看 notes：提供 Jacobian/Jv 乘积，并在隐式求解可行时使用 BDF/Radau。
“计算运行到终止时间且没有崩溃，所以积分是有效的。”	计算完成不代表结果正确。验证步是否接受（error_norm <= threshold）、分裂误差是否在 target-error 范围内，以及更严格容差下是否收敛；对于守恒问题，向 imex_split_planner.py 传入 --conservative 并检查守恒量。

安全

输入验证

• 所有数值输入（dt、rtol、atol、error_norm、stiffness_ratio、commutator_norm 等）都会在函数入口处验证是否为有限数值
• imex_split_planner.py 会根据 [a-zA-Z_][a-zA-Z0-9_ -]* 验证项名称，并限制其长度和数量，防止用户提供的项列表中包含注入载荷
• 逗号分隔的值列表最多允许包含 100,000 个条目，以防止资源耗尽
• 强制执行数值上限：dimension 上限为 10 billion，order 上限为 20，stiffness_ratio 上限为 1e30
• --controller 会根据固定的允许列表（p、pi）进行验证
• --scheme 会根据已知的分裂方案（lie、strang）进行验证

文件访问

• 脚本不会读取外部文件；所有输入均通过 CLI 参数提供
• 脚本仅向 stdout 写入内容（JSON 输出）；除非 Agent 明确使用 Write 工具，否则不会创建文件

工具限制

• Read：用于检查脚本源代码、参考资料和用户配置文件
• Write：用于保存积分器建议或分裂计划；写入范围限定在用户的工作目录中
• Grep/Glob：用于定位相关文件和搜索引用
• 该技能的 allowed-tools 排除 Bash，以防 Agent 在处理用户提供的输入时执行任意命令

安全措施

• 不使用 eval()、exec() 或动态代码生成
• 所有子进程调用均使用显式参数列表（不使用 shell=True）
• 缩小工具范围（不包含 Bash）将 Agent 的操作限制为读写
• 使用项名称前会先进行清理，防止 Shell 元字符注入

局限性

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

参考资料

• 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 - 相场专用分裂

版本历史

• v1.2.2 (2026-06-24)：新增 Verification checklist 和 Common pitfalls & rationalizations 章节，根据脚本的实际输出说明步长验收、PI 控制器的使用、积分器选择和分裂误差检查
• v1.2.0 (2026-06-23)：修复 PI 控制器系数/符号，使其符合标准形式；修复 error_norm scale-collapse 崩溃；更正错误消息和控制器文档，使其与脚本一致
• v1.1.0 (2024-12-24)：完善文档、决策指南和示例
• v1.0.0：初始版本，包含 5 个积分脚本