Plan and control time-step policies for transient simulations — couple CFL and physics-based stability limits with adaptive stepping, ramp initial transients through sharp gradients or phase changes, schedule output intervals and checkpoint cadence, and plan restart strategies for long-running jobs. Use when choosing dt for a new simulation, diagnosing adaptive time-step oscillations, deciding checkpoint frequency to minimize lost work, or setting up output schedules aligned with physical time scales, even if the user only says "my run is too slow" or "how often should I save."
Provide a reliable workflow for choosing, ramping, and monitoring time steps plus output/checkpoint cadence.
| 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 |
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
| 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 |
| Script | Key Outputs |
|---|---|
scripts/timestep_planner.py | dt_limit, dt_recommended, ramp_schedule |
scripts/output_schedule.py | output_times, interval, count |
scripts/checkpoint_planner.py | checkpoint_interval, checkpoints, overhead_fraction |
scripts/timestep_planner.pyscripts/output_schedule.pyscripts/checkpoint_planner.pyUser: I'm running a 10-hour phase-field simulation. How often should I checkpoint?
Agent workflow:
python3 scripts/checkpoint_planner.py --run-time 36000 --checkpoint-cost 120 --max-lost-time 1800 --json
# 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
| 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 |
| Observation | Meaning | Action |
|---|---|---|
| dt stable at target | Good | Continue |
| dt shrinking | Stability issue | Check CFL, reduce target |
| dt oscillating | Borderline stability | Add safety factor |
| Overhead | Acceptability |
|---|---|
| < 1% | Excellent |
| 1-5% | Good |
| 5-10% | Acceptable |
| > 10% | Too frequent, increase interval |
dt-target, dt-limit, safety, t-start, t-end, interval, run-time, checkpoint-cost, max-lost-time) are validated as finite positive numbersramp-steps is validated as a non-negative integer with an upper boundt-end must exceed t-start; checkpoint-cost must be less than run-time)timestep_planner.py, output_schedule.py, checkpoint_planner.py) with explicit argument listseval(), exec(), or dynamic code generationshell=True)references/cfl_coupling.md - Combining multiple stability limitsreferences/ramping_strategies.md - Startup policiesreferences/output_checkpoint_guidelines.md - Cadence rules