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 limitsreferences/ramping_strategies.md - Startup policiesreferences/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: 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."4---56# Time Stepping78## Goal910Provide a reliable workflow for choosing, ramping, and monitoring time steps plus output/checkpoint cadence.1112## Requirements1314- Python 3.10+15- No external dependencies (uses stdlib)1617## Inputs to Gather1819| Input | Description | Example |20|-------|-------------|---------|21| Stability limits | CFL/Fourier/reaction limits | `dt_max = 1e-4` |22| Target dt | Desired time step | `1e-5` |23| Total run time | Simulation duration | `10 s` |24| Output interval | Time between outputs | `0.1 s` |25| Checkpoint cost | Time to write checkpoint | `120 s` |2627## Decision Guidance2829### Time Step Selection3031```32Is stability limit known?33├── YES → Use min(dt_target, dt_limit × safety)34└── NO → Start conservative, increase adaptively3536Need ramping for startup?37├── YES → Start at dt_init, ramp to dt_target over N steps38└── NO → Use dt_target from start39```4041### Ramping Strategy4243| Problem Type | Ramp Steps | Initial dt |44|--------------|------------|------------|45| Smooth IC | None needed | Full dt |46| Sharp gradients | 5-10 | 0.1 × dt |47| Phase change | 10-20 | 0.01 × dt |48| Cold start | 10-50 | 0.001 × dt |4950## Script Outputs (JSON Fields)5152| Script | Key Outputs |53|--------|-------------|54| `scripts/timestep_planner.py` | `dt_limit`, `dt_recommended`, `ramp_schedule` |55| `scripts/output_schedule.py` | `output_times`, `interval`, `count` |56| `scripts/checkpoint_planner.py` | `checkpoint_interval`, `checkpoints`, `overhead_fraction` |5758## Workflow59601. **Get stability limits** - Use numerical-stability skill612. **Plan time stepping** - Run `scripts/timestep_planner.py`623. **Schedule outputs** - Run `scripts/output_schedule.py`634. **Plan checkpoints** - Run `scripts/checkpoint_planner.py`645. **Monitor during run** - Adjust dt if limits change6566## Conversational Workflow Example6768**User**: I'm running a 10-hour phase-field simulation. How often should I checkpoint?6970**Agent workflow**:711. Plan checkpoints based on acceptable lost work:72 ```bash73 python3 scripts/checkpoint_planner.py --run-time 36000 --checkpoint-cost 120 --max-lost-time 1800 --json74 ```752. Interpret: Checkpoint every 30 minutes, overhead ~0.7%, max 30 min lost work on crash.7677## Pre-Run Checklist7879- [ ] Confirm dt limits from stability analysis80- [ ] Define ramping strategy for transient startup81- [ ] Choose output interval consistent with physics time scales82- [ ] Plan checkpoints based on restart risk83- [ ] Re-evaluate dt after parameter changes8485## CLI Examples8687```bash88# Plan time stepping with ramping89python3 scripts/timestep_planner.py --dt-target 1e-4 --dt-limit 2e-4 --safety 0.8 --ramp-steps 10 --json9091# Schedule output times92python3 scripts/output_schedule.py --t-start 0 --t-end 10 --interval 0.1 --json9394# Plan checkpoints for long run95python3 scripts/checkpoint_planner.py --run-time 36000 --checkpoint-cost 120 --max-lost-time 1800 --json96```9798## Error Handling99100| Error | Cause | Resolution |101|-------|-------|------------|102| `dt-target must be positive` | Invalid time step | Use positive value |103| `t-end must be > t-start` | Invalid time range | Check time bounds |104| `checkpoint-cost must be < run-time` | Checkpoint too expensive | Reduce checkpoint size |105106## Interpretation Guidance107108### dt Behavior109110| Observation | Meaning | Action |111|-------------|---------|--------|112| dt stable at target | Good | Continue |113| dt shrinking | Stability issue | Check CFL, reduce target |114| dt oscillating | Borderline stability | Add safety factor |115116### Checkpoint Overhead117118| Overhead | Acceptability |119|----------|---------------|120| < 1% | Excellent |121| 1-5% | Good |122| 5-10% | Acceptable |123| > 10% | Too frequent, increase interval |124125## Security126127### Input Validation128- 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 numbers129- `ramp-steps` is validated as a non-negative integer with an upper bound130- Time range consistency is enforced (`t-end` must exceed `t-start`; `checkpoint-cost` must be less than `run-time`)131132### File Access133- Scripts read no external files; all inputs are provided via CLI arguments134- Scripts write only to stdout (JSON output); no files are created unless the agent explicitly uses the Write tool135136### Tool Restrictions137- **Read**: Used to inspect script source, references, and user configuration files138- **Bash**: Used to execute the three Python planning scripts (`timestep_planner.py`, `output_schedule.py`, `checkpoint_planner.py`) with explicit argument lists139- **Write**: Used to save generated time-step plans or checkpoint schedules; writes are scoped to the user's working directory140- **Grep/Glob**: Used to locate relevant files and search references141142### Safety Measures143- No `eval()`, `exec()`, or dynamic code generation144- All subprocess calls use explicit argument lists (no `shell=True`)145- Scripts use only Python standard library; no pickle loading or deserialization of untrusted data146- All output is deterministic JSON with no shell-interpretable content147148## Limitations149150- **Not adaptive control**: Plans static schedules, not runtime adaptation151- **Assumes constant physics**: If parameters change, re-plan152153## References154155- `references/cfl_coupling.md` - Combining multiple stability limits156- `references/ramping_strategies.md` - Startup policies157- `references/output_checkpoint_guidelines.md` - Cadence rules158159## Version History160161- **v1.1.0** (2024-12-24): Enhanced documentation, decision guidance, examples162- **v1.0.0**: Initial release with 3 planning scripts
zuoguyoupan2023