time-stepping

Files (9)

• CHANGELOG.md
• SKILL.md
• evals.json · evals/
• cfl_coupling.md · references/
• output_checkpoint_guidelines.md · references/
• ramping_strategies.md · references/
• checkpoint_planner.py · scripts/
• output_schedule.py · scripts/
• timestep_planner.py · scripts/

SKILL.md (first lines)

# 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
   ```
2. 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

```bash
# 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 |

From HeshamFS/materials-simulation-skills, Apache-2.0.

More from HeshamFS/materials-simulation-skills