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 …
Files included with this skill beyond the listing page.
skill mdSKILL.md10,680 B
docsSUMMARY.md240 B
History
First recorded snapshot · 0 installs
SKILL.md
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)
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
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
outputschedule.pycount is endpoint-inclusive: it includes both tstart and tend, so count = numberof_intervals + 1 (e.g. t=0..5 at 0.05 spacing yields 101 frames for 100 intervals).
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
Conversational Workflow Example
User: I'm running a 10-hour phase-field simulation. How often should I checkpoint?
Interpret: Checkpoint every 30 minutes, overhead ~6.7% (Acceptable per the interpretation table), max 30 min lost work on crash.
Pre-Run Checklist
Confirm dt limits from stability analysis
Define ramping strategy for transient startup
Choose output interval consistent with physics time scales
Plan checkpoints based on restart risk
Re-evaluate dt after parameter changes
CLI Examples
# 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 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
Interpretation Guidance
dt Behavior
Observation
Meaning
Action
dt stable at target
Good
Continue
dt shrinking
Stability issue
Check CFL, reduce target
dt oscillating
Borderline stability
Add safety factor
Checkpoint Overhead
Overhead
Acceptability
< 1%
Excellent
1-5%
Good
5-10%
Acceptable
> 10%
Too frequent, increase interval
Verification checklist
Recorded dtrecommended and dtlimit from timestepplanner.py and confirmed dtrecommended <= 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 outputschedule.pycount and verified it is endpoint-inclusive (count = intervals + 1, both tstart 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 overheadfraction from checkpointplanner.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.
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 dtrecommended <= dtlimit, 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 tstart and tend 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.
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)
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
Tool Restrictions
Read: Used to inspect script source, references, and user configuration files
Bash: Used to execute the three Python planning scripts (timestepplanner.py, outputschedule.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
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
Limitations
Not adaptive control: Plans static schedules, not runtime adaptation
Assumes constant physics: If parameters change, re-plan
v1.2.2 (2026-06-24): Added Verification checklist and Common pitfalls & rationalizations sections grounded in the three planning scripts' actual outputs
