time-stepping

时间步进

目标

提供可靠的工作流，用于选择、递增和监控时间步，以及输出／检查点的频率。

要求

• Python 3.10+
• 无外部依赖（使用标准库）

需要收集的输入

输入	描述	示例
稳定性限制	CFL／Fourier／反应限制	dt_max = 1e-4
目标 dt	期望的时间步	1e-5
总运行时间	模拟时长	10 s
输出间隔	两次输出之间的时间	0.1 s
检查点开销	写入检查点所需时间	120 s

决策指南

时间步选择

Is stability limit known?
├── YES → Use min(dt_target, dt_limit × safety)
└── NO → Start conservative, increase adaptively

Need ramping for startup?
├── YES → Start at dt_init, ramp to dt_target over N steps
└── NO → Use dt_target from start

递增策略

问题类型	递增步数	初始 dt
平滑 IC	无需递增	完整 dt
陡峭梯度	5-10	0.1 × dt
相变	10-20	0.01 × dt
冷启动	10-50	0.001 × dt

脚本输出（JSON 字段）

脚本	关键输出
scripts/timestep_planner.py	dt_limit、dt_recommended、ramp_schedule、notes
scripts/output_schedule.py	output_times、interval、count
scripts/checkpoint_planner.py	checkpoint_interval、checkpoints、overhead_fraction、warnings

output_schedule.py 中的 count 包含端点：它同时包括 t_start 和 t_end，因此 count = 区间数 + 1（例如，t=0..5 按 0.05 的间隔输出，会得到 101 帧，即 100 个区间）。

工作流

1. 获取稳定性限制 - 使用数值稳定性技能
2. 规划时间步进 - 运行 scripts/timestep_planner.py
3. 安排输出 - 运行 scripts/output_schedule.py
4. 规划检查点 - 运行 scripts/checkpoint_planner.py
5. 运行期间监控 - 如果限制发生变化，则调整 dt

对话工作流示例

用户：我正在运行一个持续 10 小时的相场模拟。应该多久设置一次检查点？

Agent 工作流：

1. 根据可接受的工作损失规划检查点：

   python3 scripts/checkpoint_planner.py --run-time 36000 --checkpoint-cost 120 --max-lost-time 1800 --json
   

2. 解读：每 30 分钟设置一次检查点，开销约为 6.7%（根据解读表，这是可接受的），崩溃时最多损失 30 分钟的工作。

运行前检查清单

• 确认稳定性分析得出的 dt 限制
• 为瞬态启动制定递增策略
• 选择与物理时间尺度一致的输出间隔
• 根据重启风险规划检查点
• 参数变更后重新评估 dt

CLI 示例

# Plan time stepping with ramping
python3 scripts/timestep_planner.py --dt-target 1e-4 --dt-limit 2e-4 --safety 0.8 --ramp-steps 10 --json

# Schedule output times
python3 scripts/output_schedule.py --t-start 0 --t-end 10 --interval 0.1 --json

# Plan checkpoints for long run
python3 scripts/checkpoint_planner.py --run-time 36000 --checkpoint-cost 120 --max-lost-time 1800 --json

错误处理

错误	原因	解决方法
dt-target must be positive	时间步无效	使用正值
t-end must be > t-start	时间范围无效	检查时间边界
checkpoint-cost must be < run-time	检查点开销过高	减小检查点大小

解读指南

dt 行为

观察结果	含义	操作
dt 稳定在目标值	良好	继续
dt 缩小	稳定性问题	检查 CFL，降低目标值
dt 振荡	稳定性处于临界状态	增加安全系数

检查点开销

开销	可接受程度
< 1%	极佳
1-5%	良好
5-10%	可接受
> 10%	过于频繁，应增大间隔

验证清单

• 记录 timestep_planner.py 返回的 dt_recommended 和 dt_limit，并确认 dt_recommended <= dt_limit，且 notes 字段中没有“Recommended dt exceeds stability limit”提示。
• 从稳定性分析（数值稳定性技能：CFL/Fourier/反应限制）中获取实际的 dt_limit 值，并确认传给了 --dt-limit，而非凭猜测填写；任何参数发生变化后，都重新运行规划器。
• 确认已应用 safety <= 1.0（即留出不超过限制值的余量），并记录 notes 数组（例如“Recommended dt reduced by stability limit”、最小/最大值钳制），以便确定起约束作用的条件。
• 记录 output_schedule.py 的 count，并确认其包含端点（count = intervals + 1，且包含 t_start 和 t_end），以免帧数和后处理索引出现差一错误。
• 记录 checkpoint_planner.py 返回的检查点 interval、method（daly 或 cap）和 overhead_fraction，并对照开销可接受性表确认 overhead_fraction <= 0.10（warnings 中没有条目）。
• 确认每个脚本都以退出码 0 结束（不是退出码 2 / stderr 中出现 ValueError），且引用的 dt/间隔/检查点值来自 JSON results，而非来自打印了验证错误的运行结果。

常见误区与错误认知

看似省事的做法	错误原因 / 正确做法
“这是隐式方案，所以 dt 怎么设都行——跳过 --dt-limit。”	无条件稳定不等于准确；过大的 dt 仍会造成时间误差，也无法解析瞬态过程。仍应传入基于物理条件的 dt-target，并根据时间尺度重新检查推荐的 dt。
“把 --safety 设为大于 1.0，就能迈出更大的步长。”	safety 是小于或等于限制值的余量；safety > 1.0 会导致返回的 dt 超出稳定性限制，因此规划器会拒绝该值（退出码 2）。应调低对 dt-limit 的预期，或改用更精细的网格。
“程序运行时没有崩溃，所以 dt 就有效。”	运行完成不代表结果正确。请验证 dt_recommended <= dt_limit，查看 notes 数组，并在 v_max、D、dx 或方案发生变化时重新规划——这些变化都会影响限制值。
“输出的 count 看起来多了一个——删掉最后一帧。”	按设计，count 包含端点（intervals + 1）；t_start 和 t_end 都是实际输出。删掉最后一帧会在不知不觉中丢失最终状态。
“每一步都保存检查点，这样就永远不会丢失工作。”	这样会使 overhead_fraction 超过 10%（规划器会生成 warnings 条目），且开销会占据运行时间的主要部分。请使用 --max-lost-time（cap）或 --mtbf（Daly），让开销保持在可接受范围内。
“沿用上周的 dt/检查点方案；模型基本没变。”	稳定性和最优检查点间隔取决于当前的 dx、速度/扩散率、checkpoint-cost 和 MTBF。请使用当前值重新运行三个脚本，而不是照搬过时的数值。

安全

输入验证

• 所有数值参数（dt-target、dt-limit、safety、t-start、t-end、interval、run-time、checkpoint-cost、max-lost-time）都会验证是否为有限正数（拒绝 inf/nan 等非有限值）
• safety 的上限为 <= 1.0（安全系数是小于或等于限制值的稳定性余量；大于 1.0 的值会被拒绝）
• ramp-steps 和 preview-steps 会验证是否为不小于零的整数，上限为 1,000,000；仅实例化 ramp 中预览的部分，以限制内存使用
• 强制检查时间范围的一致性（t-end 必须大于 t-start；checkpoint-cost 必须小于 run-time）

文件访问

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

工具限制

• Read：用于检查脚本源代码、参考资料和用户配置文件
• Bash：用于通过显式参数列表执行三个 Python 规划脚本（timestep_planner.py、output_schedule.py、checkpoint_planner.py）
• Write：用于保存生成的时间步计划或检查点计划；写入范围限定在用户的工作目录内
• Grep/Glob：用于定位相关文件和搜索引用

安全措施

• 不使用 eval()、exec() 或动态代码生成
• 所有子进程调用都使用显式参数列表（不使用 shell=True）
• 脚本仅使用 Python 标准库；不加载 pickle，也不反序列化不可信数据
• 所有输出均为确定性 JSON，不包含可由 shell 解释的内容

限制

• 不支持自适应控制：规划静态计划，不进行运行时自适应
• 假设物理条件恒定：如果参数发生变化，请重新规划

参考资料

• references/cfl_coupling.md - 组合多个稳定性限制
• references/ramping_strategies.md - 启动策略
• references/output_checkpoint_guidelines.md - 时间间隔规则

版本历史

• v1.2.2（2026-06-24）：新增验证清单和常见陷阱及合理化解释章节，内容基于三个规划脚本的实际输出
• v1.2.0（2026-06-23）：修正开销/帧数文档和评估，消除输出时间浮点漂移，强化输入验证（检查点成本 < 运行时间、安全系数 <= 1.0、限制爬升/预览步数、有限值检查）
• v1.1.0（2024-12-24）：完善文档、决策指南和示例
• v1.0.0：初始版本，包含 3 个规划脚本