differentiation-schemes

微分格式

目标

提供可靠的工作流，用于选择微分格式、生成模板，并评估模拟离散化的精度。

要求

• Python 3.10+
• NumPy（用于模板计算）
• 无需繁重的依赖项

需要收集的输入

输入	描述	示例
导数阶数	一阶、二阶等	1 或 2
目标精度	截断误差的阶数	2 或 4
网格类型	均匀、非均匀	uniform
边界类型	周期、Dirichlet、Neumann	periodic
光滑性	光滑或不连续	smooth

选择指导

格式选择流程图

Is the field smooth?
├── YES → Is domain periodic?
│   ├── YES → Use central differences or spectral
│   └── NO → Use central interior + one-sided at boundaries
└── NO → Are there shocks/discontinuities?
    ├── YES → Use upwind, TVD, or WENO
    └── NO → Use central with limiters

快速参考

情况	推荐格式
光滑、周期	中心差分、谱方法
光滑、有界	中心差分 + 单边边界条件
对流占主导	上风格式
激波／前沿	TVD、WENO
需要高精度	紧致格式（Padé）、谱方法

脚本输出（JSON 字段）

脚本	主要输出
scripts/stencil_generator.py	offsets、coefficients、order、accuracy、scheme
scripts/scheme_selector.py	recommended、alternatives、notes
scripts/truncation_error.py	error_scale、order、reduction_if_halved

工作流

1. 确定需求 - 导数阶数、精度、光滑性
2. 选择格式 - 运行 scripts/scheme_selector.py
3. 生成模板 - 运行 scripts/stencil_generator.py
4. 估算误差 - 运行 scripts/truncation_error.py
5. 验证 - 使用制造解或网格加密进行测试

对话式工作流示例

用户：我需要在均匀网格上为扩散方程离散化二阶导数，要求达到四阶精度。

Agent 工作流：

1. 选择合适的格式（未说明边界类型；如果计算域有界而非周期，则添加 --boundary 以显示单边格式／虚拟单元指导，或询问用户）：

   python3 scripts/scheme_selector.py --smooth --order 2 --accuracy 4 --json
   

2. 生成模板：

   python3 scripts/stencil_generator.py --order 2 --accuracy 4 --scheme central --json
   

3. 结果：5 点模板，系数为 [-1/12, 4/3, -5/2, 4/3, -1/12] / dx²。

离散化前检查清单

• 确认导数阶数和目标精度
• 选择适用于光滑性和边界条件的格式
• 生成并检查边界处的模板
• 根据物理尺度估算截断误差
• 通过网格加密研究进行验证

CLI 示例

# Select scheme for smooth periodic problem
python3 scripts/scheme_selector.py --smooth --periodic --order 1 --accuracy 4 --json

# Generate central difference stencil for first derivative
python3 scripts/stencil_generator.py --order 1 --accuracy 2 --scheme central --json

# Generate 4th-order second derivative stencil
python3 scripts/stencil_generator.py --order 2 --accuracy 4 --scheme central --json

# Estimate truncation error
python3 scripts/truncation_error.py --dx 0.01 --accuracy 2 --scale 1.0 --json

错误处理

错误	原因	解决方法
order must be positive	导数阶数无效	使用 1、2、3……（最大为 6）
order must be <= 6	导数阶数过大	使用 1–6
accuracy must be even for central	中心格式要求精度为偶数，但指定了奇数精度	使用 2、4、6……
scheme must be central, forward, or backward	--scheme 值无效	使用 central、forward 或 backward

结果解读指南

模板属性

属性	含义
对称偏移	中心格式（无方向偏置）
非对称偏移	单边格式或上风格式
点数更多	精度更高，但模板更宽

截断误差缩放

精度阶数	误差缩放	加密因子
二阶	O(dx²)	网格加密 2× → 误差降低 4×
四阶	O(dx⁴)	网格加密 2× → 误差降低 16×
六阶	O(dx⁶)	网格加密 2× → 误差降低 64×

常用模板

导数	精度	点数	系数（× 1/dx 或 1/dx²）
一阶	2	3	[-1/2, 0, 1/2]
一阶	4	5	[1/12, -2/3, 0, 2/3, -1/12]
二阶	2	3	[1, -2, 1]
二阶	4	5	[-1/12, 4/3, -5/2, 4/3, -1/12]

验证清单

在信任生成的模板或接受方案建议之前，请为以下每一项记录具体证据：

• 运行了 stencil_generator.py --json，并确认 results.accuracy 与请求的阶数一致，且 len(results.offsets) 等于预期的模板宽度（例如，4 阶中心二阶导数有 5 个点）；对于 central 方案，还确认了偏移量关于 0 对称。
• 根据 references/stencil_catalog.md 对返回的 coefficients 进行了合理性检查：确认它们的和约等于 0（一致性：该算子会将常数消去），并确认至少一个标准情形能复现目录中的已知模板（例如，2 阶 d²/dx² 对应 [1, -2, 1]/dx²）。
• 对于 central 方案，确认了 --accuracy 为偶数（奇数会以状态码 2 退出，并提示 accuracy must be even for central）；记录了实际退出码，而不是假定已达到请求的阶数。
• 记录了 truncation_error.py 给出的 error_scale、order 和 reduction_if_halved，并确认 reduction_if_halved == 2**accuracy；随后根据 references/error_guidance.md，将 error_scale 与最小物理特征尺寸（dx/L_feature）进行比较，确认网格确实能解析相关物理现象。
• 在至少 3 个网格上进行了独立的网格细化／制造解研究（这些脚本不会执行此操作），并确认观测阶数 p_obs = log(e_h/e_{h/2})/log(2) 与形式精度 accuracy 的偏差在约 10% 以内，然后再引用该阶数。
• 对于有界（非周期）区域，根据 references/boundary_handling.md，确认已明确生成／选择边界模板（--scheme forward|backward 或 --boundary 指南），因为仅有内部模板并不能确定边界处的方案阶数。
• 对于非光滑场（激波／前沿），确认 scheme_selector.py 没有推荐高阶中心 FD，而是选择了限制器／WENO／迎风方案。

常见陷阱与自我辩解

看似诱人的捷径	为什么错／应该怎么做
“模板生成器返回了系数，所以这个格式就是我要求的阶数。”	accuracy 字段只是回显你的请求，并未经过测量。请通过网格加密研究验证实际达到的阶数，并确认系数与目录中的模板一致且总和约为 0。
“我在中心格式上要求 4 阶，却用了 --accuracy 3，它会自动向上取整。”	不会——中心格式会因 accuracy must be even for central 而拒绝奇数精度（退出码 2）。请传入偶数精度；奇数请求会报错，不会静默升级。
“这里的精度阶数越高，误差总是越低。”	truncation_error.py 报告的是渐近标度（scale * dx**accuracy）；对于粗网格或未充分解析的特征，更高阶项不一定占主导，而在非常细的网格上，舍入误差（O(ε/dx^p)）可能占上风。请将 error_scale 与特征尺寸进行比较，不要假设误差会单调改善。
“两个网格的结果非常接近，所以已经收敛了。”	两个网格无法估算观测阶数，也无法确认是否处于渐近范围。请使用 >=3 个网格并计算 p_obs，然后再声称达到了形式阶数（参见 references/error_guidance.md）。
“内部模板是 4 阶的，所以我的整个求解都是 4 阶的。”	生成器只生成内部模板；边界闭合通常会限制全局阶数。请明确生成单边／幽灵单元模板，并验证边界不会降低观测阶数（references/boundary_handling.md）。
“场中有激波，但宽中心模板更准确，所以应该用它。”	在间断处，高阶中心 FD 会产生振荡（Gibbs 现象）。对于 --discontinuous，scheme_selector.py 会建议使用带限制器的 FV、WENO 或迎风格式；请遵循建议，而不是一味追求形式阶数。
“自定义 --offsets 能让我构造任意模板。”	偏移量必须互不相同、长度不超过上限（51），且数量必须大于导数阶数，否则脚本会以退出码 2 退出。即使运行有效，也不保证精度符合预期——请验证系数和观测阶数。

安全性

输入验证

• --order（导数阶数）会验证为正整数，并设有上限（order <= 6）
• --accuracy 会验证为正整数（<= 8），中心格式还要求其为偶数
• --scheme 会依据固定允许列表进行验证（central、forward、backward）
• --offsets（自定义模板）设有长度上限（最多 51），会解析为互不相同的整数，且数量必须大于导数阶数
• --dx 和 --scale 会验证为有限的非负数（--dx 必须严格大于 0）
• 不会将用户提供的字符串插入代码路径或 shell 命令

文件访问

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

工具限制

• Read：用于检查脚本源代码、参考资料和用户配置文件
• Bash：用于通过明确的参数列表执行三个 Python 脚本（stencil_generator.py、scheme_selector.py、truncation_error.py）
• Write：用于保存生成的模板系数或格式建议；写入范围限定为用户的工作目录
• Grep/Glob：用于定位相关文件和搜索参考资料

安全措施

• 不使用 eval()、exec() 或动态代码生成
• 所有子进程调用均使用明确的参数列表（不使用 shell=True）
• 模板计算只使用规模小且有界的数组（导数阶数上限为 6，精度上限为 8，自定义偏移列表上限为 51 个点）
• 所有输出均为确定性的 JSON，不包含可由 shell 解释的内容

局限性

• 边界处理：Stencil 生成器提供内部 stencil；边界需要特殊处理
• 非均匀网格：标准 stencil 假设间距均匀
• 谱方法：Stencil 生成器未涵盖

参考资料

• references/stencil_catalog.md - 常用 stencil
• references/boundary_handling.md - 单边格式
• references/scheme_selection.md - FD/FV/谱方法对比
• references/error_guidance.md - 截断误差的缩放规律

版本历史

• v1.2.2（2026-06-24）：新增验证清单（基于证据，与脚本 JSON 输出和参考资料相关联）以及常见陷阱与合理化说辞表。
• v1.2.0（2026-06-23）：强制验证精度为偶数且阶数不超过上限；修正文档中的安全性、错误处理和输出说明，使其与脚本一致；修复 CLI/eval 示例；加强输入验证
• v1.1.0（2024-12-24）：完善文档、决策指南和示例
• v1.0.0：首次发布，包含 3 个微分脚本