Time Stepping

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

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 |

Script Outputs (JSON Fields)

| 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 |

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 at 0.05 spacing yields 101 frames for 100 intervals).

Workflow

1. Get stability limits - Use numerical-stability skill
2. Plan time stepping - Run scripts/timestep_planner.py
3. Schedule outputs - Run scripts/output_schedule.py
4. Plan checkpoints - Run scripts/checkpoint_planner.py
5. 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?

Agent workflow:

1. Plan checkpoints based on acceptable lost work:

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

1. 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 10% | Too frequent, increase interval |

Verification checklist

• [ ] Recorded dt_recommended and dt_limit from timestep_planner.py and confirmed dt_recommended 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. |

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 (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

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

References

• references/cfl_coupling.md - Combining multiple stability limits
• references/ramping_strategies.md - Startup policies
• references/output_checkpoint_guidelines.md - Cadence rules

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: HeshamFS
• Source: HeshamFS/materials-simulation-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.