time-stepping

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Time Stepping

时间步规划

Goal

目标

Provide a reliable workflow for choosing, ramping, and monitoring time steps plus output/checkpoint cadence.

为时间步的选择、渐变和监控，以及输出/检查点节奏提供可靠的工作流。

Requirements

要求

Python 3.10+
No external dependencies (uses stdlib)

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

Inputs to Gather

需要收集的输入

Input	Description	Example
Stability limits	CFL/Fourier/reaction limits	`dt_max = 1e-4`
Target dt	Desired time step	`1e-5`
Total run time	Simulation duration	`10 s`
Output interval	Time between outputs	`0.1 s`
Checkpoint cost	Time to write checkpoint	`120 s`

输入项	描述	示例
稳定性限制	CFL/傅里叶/反应限制	`dt_max = 1e-4`
目标dt值	期望的时间步	`1e-5`
总运行时间	仿真时长	`10 s`
输出间隔	两次输出的时间间隔	`0.1 s`
检查点成本	写入检查点所需时间	`120 s`

Decision Guidance

决策指南

Time Step Selection

时间步选择

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

已知稳定性限制？
├── 是 → 使用min(dt_target, dt_limit × safety)
└── 否 → 从保守值开始，自适应增大

启动阶段需要渐变策略？
├── 是 → 从dt_init开始，经过N步渐变到dt_target
└── 否 → 从一开始就使用dt_target

Ramping Strategy

渐变策略

Problem Type	Ramp Steps	Initial dt
Smooth IC	None needed	Full dt
Sharp gradients	5-10	0.1 × dt
Phase change	10-20	0.01 × dt
Cold start	10-50	0.001 × dt

问题类型	渐变步数	初始dt值
平滑初始条件	无需渐变	完整dt值
尖锐梯度	5-10	0.1 × dt
相变	10-20	0.01 × dt
冷启动	10-50	0.001 × dt

Script Outputs (JSON Fields)

脚本输出（JSON字段）

Script Key Outputs

Script	Key Outputs
`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`

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

is endpoint-inclusive: it includes both

t_start

and

t_end

, so

count = number_of_intervals + 1

(e.g.

t=0..5

0.05

spacing yields 101 frames for 100 intervals).

脚本关键输出

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

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个间隔）。

Workflow

工作流

Get stability limits - Use numerical-stability skill
Plan time stepping - Run
```
scripts/timestep_planner.py
```
Schedule outputs - Run
```
scripts/output_schedule.py
```
Plan checkpoints - Run
```
scripts/checkpoint_planner.py
```
Monitor during run - Adjust dt if limits change

获取稳定性限制 - 使用数值稳定性工具
规划时间步 - 运行
```
scripts/timestep_planner.py
```
规划输出 - 运行
```
scripts/output_schedule.py
```
规划检查点 - 运行
```
scripts/checkpoint_planner.py
```
运行期间监控 - 若限制变化则调整dt值

Conversational Workflow Example

对话式工作流示例

User: I'm running a 10-hour phase-field simulation. How often should I checkpoint?

Agent workflow:

Plan checkpoints based on acceptable lost work:

bash

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

Interpret: Checkpoint every 30 minutes, overhead ~6.7% (Acceptable per the interpretation table), max 30 min lost work on crash.

用户：我正在运行一个10小时的相场仿真，应该多久设置一次检查点？

Agent工作流:

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

bash

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

解读：每30分钟设置一次检查点，开销约6.7%（符合解读表中的可接受范围），崩溃时最多损失30分钟的工作。

Pre-Run Checklist

运行前检查清单

CLI Examples

CLI示例

bash

undefined

bash

undefined

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

undefined

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

undefined

Error Handling

错误处理

Error	Cause	Resolution
`dt-target must be positive`	Invalid time step	Use positive value
`t-end must be > t-start`	Invalid time range	Check time bounds
`checkpoint-cost must be < run-time`	Checkpoint too expensive	Reduce checkpoint size

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

Interpretation Guidance

解读指南

dt Behavior

dt行为

Observation	Meaning	Action
dt stable at target	Good	Continue
dt shrinking	Stability issue	Check CFL, reduce target
dt oscillating	Borderline stability	Add safety factor

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

Checkpoint Overhead

检查点开销

Overhead	Acceptability
< 1%	Excellent
1-5%	Good
5-10%	Acceptable
> 10%	Too frequent, increase interval

开销占比	可接受性
< 1%	优秀
1-5%	良好
5-10%	可接受
> 10%	过于频繁，增大间隔

Verification checklist

验证清单

Recorded
```
dt_recommended
```
and
```
dt_limit
```
from
```
timestep_planner.py
```
and confirmed
```
dt_recommended <= dt_limit
```
with no "Recommended dt exceeds stability limit" note in the
```
notes
```
field.
Captured the actual
```
dt_limit
```
value from the stability analysis (numerical-stability skill: CFL/Fourier/reaction limit) that was fed to
```
--dt-limit
```
, rather than guessing — and re-ran the planner after any parameter change.
Confirmed
```
safety <= 1.0
```
was applied (a margin below the limit), and logged the
```
notes
```
array (e.g. "Recommended dt reduced by stability limit", min/max clamps) so the binding constraint is known.
Recorded the
```
output_schedule.py
```
```
count
```
and verified it is endpoint-inclusive (
```
count = intervals + 1
```
, both
```
t_start
```
and
```
t_end
```
present), so frame counts and post-processing indices are not off-by-one.
Recorded the checkpoint
```
interval
```
,
```
method
```
(
```
daly
```
vs
```
cap
```
), and
```
overhead_fraction
```
from
```
checkpoint_planner.py
```
, and confirmed
```
overhead_fraction <= 0.10
```
(no
```
warnings
```
entry) against the overhead acceptability table.
Confirmed every script exited 0 (not exit 2 / stderr
```
ValueError
```
) and that quoted dt/interval/checkpoint values come from the JSON
```
results
```
, not from a run that printed a validation error.

记录
```
timestep_planner.py
```
输出的
```
dt_recommended
```
和
```
dt_limit
```
，并确认
```
dt_recommended <= dt_limit
```
，且
```
notes
```
字段中没有“推荐dt超过稳定性限制”的提示。
获取输入到
```
--dt-limit
```
的、来自稳定性分析（数值稳定性工具：CFL/傅里叶/反应限制）的实际
```
dt_limit
```
值，而非猜测——参数变更后重新运行规划器。
确认已应用
```
safety <= 1.0
```
（低于限制的余量），并记录
```
notes
```
数组（例如“推荐dt因稳定性限制降低”、最小/最大值限制），以便明确约束条件。
记录
```
output_schedule.py
```
的
```
count
```
值，并验证它包含端点（
```
count = 间隔数 + 1
```
，同时包含
```
t_start
```
和
```
t_end
```
），确保帧计数和后处理索引没有差一错误。

记录

checkpoint_planner.py

输出的检查点

interval

、

method

（

daly

cap

）和

overhead_fraction

，并对照开销可接受表确认

overhead_fraction <= 0.10

（无

warnings

条目）。

确认所有脚本均以状态码0退出（而非状态码2/标准错误输出
```
ValueError
```
），且引用的dt/间隔/检查点值来自JSON
```
results
```
，而非输出验证错误的运行实例。

Common pitfalls & rationalizations

常见误区与合理化建议

Tempting shortcut	Why it's wrong / what to do
"Implicit scheme, so any dt is fine — skip `--dt-limit` ."	Unconditional stability is not accuracy; a large dt still ruins temporal error and resolves no transient. Still pass a physics-based `dt-target` and re-check the recommended dt against time scales.
"Set `--safety` above 1.0 to take bigger steps."	`safety` is a margin at or below the limit; `safety > 1.0` would return a dt above the stability limit, so the planner rejects it (exit 2). Lower `dt-limit` expectations or use a finer mesh instead.
"It ran without crashing, so the dt is valid."	Run completion is not correctness. Verify `dt_recommended <= dt_limit` , read the `notes` array, and re-plan whenever `v_max` , `D` , `dx` , or the scheme changes — the limit moves with them.
"The output `count` looks one too many — drop the last frame."	`count` is endpoint-inclusive by design ( `intervals + 1` ); both `t_start` and `t_end` are real outputs. Trimming it silently loses the final state.
"Checkpoint every step to never lose work."	That drives `overhead_fraction` past 10% (the planner emits a `warnings` entry) and dominates runtime. Use `--max-lost-time` (cap) or `--mtbf` (Daly) so overhead stays in the Acceptable band.
"Reuse last week's dt/checkpoint plan; the model is basically the same."	Stability and optimal checkpoint interval depend on current `dx` , velocity/diffusivity, `checkpoint-cost` , and MTBF. Re-run the three scripts with current values rather than copying stale numbers.

诱人的捷径	错误原因/正确做法
“隐式格式，所以任何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` 设计为包含端点（ `间隔数 + 1` ）； `t_start` 和 `t_end` 都是有效的输出。静默修剪会丢失最终状态。
“每一步都设置检查点，绝不损失工作。”	这会使 `overhead_fraction` 超过10%（规划器会输出 `warnings` 条目），并主导运行时间。使用 `--max-lost-time` （上限）或 `--mtbf` （Daly方法），使开销保持在可接受范围内。
“复用上周的dt/检查点规划；模型基本相同。”	稳定性和最优检查点间隔取决于当前的 `dx` 、速度/扩散率、 `checkpoint-cost` 和MTBF。使用当前参数重新运行三个脚本，而非复制陈旧数值。

Security

安全性

Input Validation

输入验证

All numeric parameters (
```
dt-target
```
,
```
dt-limit
```
,
```
safety
```
,
```
t-start
```
,
```
t-end
```
,
```
interval
```
,
```
run-time
```
,
```
checkpoint-cost
```
,
```
max-lost-time
```
) are validated as finite positive numbers (non-finite values such as
```
inf
```
/
```
nan
```
are rejected)
```
safety
```
is bounded to
```
<= 1.0
```
(a safety factor is a stability margin at or below the limit; values above 1.0 are rejected)
```
ramp-steps
```
and
```
preview-steps
```
are validated as non-negative integers with an upper bound of 1,000,000; only the previewed slice of the ramp is materialized to bound memory use
Time range consistency is enforced (
```
t-end
```
must exceed
```
t-start
```
;
```
checkpoint-cost
```
must be less than
```
run-time
```
)

所有数值参数（
```
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；仅实例化渐变的预览片段以限制内存使用
强制时间范围一致性（
```
t-end
```
必须大于
```
t-start
```
；
```
checkpoint-cost
```
必须小于
```
run-time
```
）

File Access

文件访问

Scripts read no external files; all inputs are provided via CLI arguments
Scripts write only to stdout (JSON output); no files are created unless the agent explicitly uses the Write tool

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

Tool Restrictions

工具限制

Read: Used to inspect script source, references, and user configuration files
Bash: Used to execute the three Python planning scripts (
```
timestep_planner.py
```
,
```
output_schedule.py
```
,
```
checkpoint_planner.py
```
) with explicit argument lists
Write: Used to save generated time-step plans or checkpoint schedules; writes are scoped to the user's working directory
Grep/Glob: Used to locate relevant files and search references

读取：用于检查脚本源码、参考资料和用户配置文件
Bash：用于执行三个Python规划脚本（
```
timestep_planner.py
```
、
```
output_schedule.py
```
、
```
checkpoint_planner.py
```
），并传入明确的参数列表
写入：用于保存生成的时间步规划或检查点计划；写入范围限定在用户的工作目录
Grep/Glob：用于定位相关文件并搜索参考资料

Safety Measures

安全措施

No
```
eval()
```
,
```
exec()
```
, or dynamic code generation
All subprocess calls use explicit argument lists (no
```
shell=True
```
)
Scripts use only Python standard library; no pickle loading or deserialization of untrusted data
All output is deterministic JSON with no shell-interpretable content

不使用
```
eval()
```
、
```
exec()
```
或动态代码生成
所有子进程调用使用明确的参数列表（不使用
```
shell=True
```
）
脚本仅使用Python标准库；不加载pickle或反序列化不可信数据
所有输出为确定性JSON，无可被Shell解析的内容

Limitations

局限性

Not adaptive control: Plans static schedules, not runtime adaptation
Assumes constant physics: If parameters change, re-plan

非自适应控制：规划静态计划，而非运行时自适应调整
假设物理参数恒定：若参数变更，需重新规划

References

参考文献

```
references/cfl_coupling.md
```
- Combining multiple stability limits
```
references/ramping_strategies.md
```
- Startup policies

references/output_checkpoint_guidelines.md

- Cadence rules

```
references/cfl_coupling.md
```
- 组合多种稳定性限制
```
references/ramping_strategies.md
```
- 启动策略

references/output_checkpoint_guidelines.md

- 节奏规则

Version History

版本历史

v1.2.2 (2026-06-24): Added Verification checklist and Common pitfalls & rationalizations sections grounded in the three planning scripts' actual outputs
v1.2.0 (2026-06-23): Corrected overhead/frame-count docs and evals, removed output-time float drift, hardened input validation (checkpoint-cost < run-time, safety <= 1.0, bounded ramp/preview steps, finite checks)
v1.1.0 (2024-12-24): Enhanced documentation, decision guidance, examples
v1.0.0: Initial release with 3 planning scripts

v1.2.2 (2026-06-24)：新增验证清单和常见误区与合理化建议章节，内容基于三个规划脚本的实际输出
v1.2.0 (2026-06-23)：修正开销/帧计数文档和评估逻辑，消除输出时间浮点漂移，强化输入验证（检查点成本<运行时间、safety<=1.0、渐变/预览步数上限、有限值检查）
v1.1.0 (2024-12-24)：增强文档、决策指南和示例
v1.0.0：初始版本，包含3个规划脚本