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 |
scripts/output_schedule.py |
output_times, interval, count |
scripts/checkpoint_planner.py |
checkpoint_interval, checkpoints, overhead_fraction |
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?
Agent workflow:
- Plan checkpoints based on acceptable lost work:
python3 scripts/checkpoint_planner.py --run-time 36000 --checkpoint-cost 120 --max-lost-time 1800 --json
- Interpret: Checkpoint every 30 minutes, overhead ~0.7%, max 30 min lost work on crash.
Pre-Run Checklist
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 |
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
ramp-steps is validated as a non-negative integer with an upper bound
- 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.1.0 (2024-12-24): Enhanced documentation, decision guidance, examples
- v1.0.0: Initial release with 3 planning scripts
1---2name: time-stepping3description: >4 Plan and control time-step policies for transient simulations — couple5 CFL and physics-based stability limits with adaptive stepping, ramp initial6 transients through sharp gradients or phase changes, schedule output intervals7 and checkpoint cadence, and plan restart strategies for long-running jobs.8 Use when choosing dt for a new simulation, diagnosing adaptive time-step9 oscillations, deciding checkpoint frequency to minimize lost work, or10 setting up output schedules aligned with physical time scales, even if11 the user only says "my run is too slow" or "how often should I save."12allowed-tools: Read, Bash, Write, Grep, Glob13metadata:14 source: https://skillmd.com/skills/zuoguyoupan2023/time-stepping15 author: HeshamFS16 version: "1.1.0"17 security_tier: high18 security_reviewed: true19 tested_with:20 - claude-code21 - gemini-cli22 - vs-code-copilot23 eval_cases: 424 last_reviewed: "2026-03-26"25---2627# Time Stepping2829## Goal3031Provide a reliable workflow for choosing, ramping, and monitoring time steps plus output/checkpoint cadence.3233## Requirements3435- Python 3.10+36- No external dependencies (uses stdlib)3738## Inputs to Gather3940| Input | Description | Example |41|-------|-------------|---------|42| Stability limits | CFL/Fourier/reaction limits | `dt_max = 1e-4` |43| Target dt | Desired time step | `1e-5` |44| Total run time | Simulation duration | `10 s` |45| Output interval | Time between outputs | `0.1 s` |46| Checkpoint cost | Time to write checkpoint | `120 s` |4748## Decision Guidance4950### Time Step Selection5152```53Is stability limit known?54├── YES → Use min(dt_target, dt_limit × safety)55└── NO → Start conservative, increase adaptively5657Need ramping for startup?58├── YES → Start at dt_init, ramp to dt_target over N steps59└── NO → Use dt_target from start60```6162### Ramping Strategy6364| Problem Type | Ramp Steps | Initial dt |65|--------------|------------|------------|66| Smooth IC | None needed | Full dt |67| Sharp gradients | 5-10 | 0.1 × dt |68| Phase change | 10-20 | 0.01 × dt |69| Cold start | 10-50 | 0.001 × dt |7071## Script Outputs (JSON Fields)7273| Script | Key Outputs |74|--------|-------------|75| `scripts/timestep_planner.py` | `dt_limit`, `dt_recommended`, `ramp_schedule` |76| `scripts/output_schedule.py` | `output_times`, `interval`, `count` |77| `scripts/checkpoint_planner.py` | `checkpoint_interval`, `checkpoints`, `overhead_fraction` |7879## Workflow80811. **Get stability limits** - Use numerical-stability skill822. **Plan time stepping** - Run `scripts/timestep_planner.py`833. **Schedule outputs** - Run `scripts/output_schedule.py`844. **Plan checkpoints** - Run `scripts/checkpoint_planner.py`855. **Monitor during run** - Adjust dt if limits change8687## Conversational Workflow Example8889**User**: I'm running a 10-hour phase-field simulation. How often should I checkpoint?9091**Agent workflow**:921. Plan checkpoints based on acceptable lost work:93 ```bash94 python3 scripts/checkpoint_planner.py --run-time 36000 --checkpoint-cost 120 --max-lost-time 1800 --json95 ```962. Interpret: Checkpoint every 30 minutes, overhead ~0.7%, max 30 min lost work on crash.9798## Pre-Run Checklist99100- [ ] Confirm dt limits from stability analysis101- [ ] Define ramping strategy for transient startup102- [ ] Choose output interval consistent with physics time scales103- [ ] Plan checkpoints based on restart risk104- [ ] Re-evaluate dt after parameter changes105106## CLI Examples107108```bash109# Plan time stepping with ramping110python3 scripts/timestep_planner.py --dt-target 1e-4 --dt-limit 2e-4 --safety 0.8 --ramp-steps 10 --json111112# Schedule output times113python3 scripts/output_schedule.py --t-start 0 --t-end 10 --interval 0.1 --json114115# Plan checkpoints for long run116python3 scripts/checkpoint_planner.py --run-time 36000 --checkpoint-cost 120 --max-lost-time 1800 --json117```118119## Error Handling120121| Error | Cause | Resolution |122|-------|-------|------------|123| `dt-target must be positive` | Invalid time step | Use positive value |124| `t-end must be > t-start` | Invalid time range | Check time bounds |125| `checkpoint-cost must be < run-time` | Checkpoint too expensive | Reduce checkpoint size |126127## Interpretation Guidance128129### dt Behavior130131| Observation | Meaning | Action |132|-------------|---------|--------|133| dt stable at target | Good | Continue |134| dt shrinking | Stability issue | Check CFL, reduce target |135| dt oscillating | Borderline stability | Add safety factor |136137### Checkpoint Overhead138139| Overhead | Acceptability |140|----------|---------------|141| < 1% | Excellent |142| 1-5% | Good |143| 5-10% | Acceptable |144| > 10% | Too frequent, increase interval |145146## Security147148### Input Validation149- 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 numbers150- `ramp-steps` is validated as a non-negative integer with an upper bound151- Time range consistency is enforced (`t-end` must exceed `t-start`; `checkpoint-cost` must be less than `run-time`)152153### File Access154- Scripts read no external files; all inputs are provided via CLI arguments155- Scripts write only to stdout (JSON output); no files are created unless the agent explicitly uses the Write tool156157### Tool Restrictions158- **Read**: Used to inspect script source, references, and user configuration files159- **Bash**: Used to execute the three Python planning scripts (`timestep_planner.py`, `output_schedule.py`, `checkpoint_planner.py`) with explicit argument lists160- **Write**: Used to save generated time-step plans or checkpoint schedules; writes are scoped to the user's working directory161- **Grep/Glob**: Used to locate relevant files and search references162163### Safety Measures164- No `eval()`, `exec()`, or dynamic code generation165- All subprocess calls use explicit argument lists (no `shell=True`)166- Scripts use only Python standard library; no pickle loading or deserialization of untrusted data167- All output is deterministic JSON with no shell-interpretable content168169## Limitations170171- **Not adaptive control**: Plans static schedules, not runtime adaptation172- **Assumes constant physics**: If parameters change, re-plan173174## References175176- `references/cfl_coupling.md` - Combining multiple stability limits177- `references/ramping_strategies.md` - Startup policies178- `references/output_checkpoint_guidelines.md` - Cadence rules179180## Version History181182- **v1.1.0** (2024-12-24): Enhanced documentation, decision guidance, examples183- **v1.0.0**: Initial release with 3 planning scripts