Operational Deployment Patterns
Daily Batch Planning
The primary pattern: run the seasonal planner once per day, early morning, before the day-ahead market closes.
06:00 Receive updated inflow prognosis + price forecast
06:01 run_case_incremental("cases/system_x"; start_date=today())
→ Computes drift vs. previous run
→ Shifts cuts forward by 1 stage (rolling horizon)
→ Warm-starts if drift is small, full run otherwise
→ Saves state to cases/system_x/state/2026-03-22.json
06:02 Results available for day-ahead biddingTypical configuration:
WarmStartConfig(
drift_threshold = 0.05,
cumulative_limit = 0.20,
max_warm_iters = 20,
full_run_interval = 7, # full run every Monday
)Expected performance:
- Full run: 20–60 seconds (depending on system size)
- Warm start: 2–10 seconds (3–5 SDDP iterations)
The 5-Year Rolling Horizon
Each day, the planning horizon is:
Today ──────── 1 year ────────── 5 years
│ │ │
├─ Prognosis ──┤ │
│ ├── Weather year ────┤
│ │ statistics │
Stage 1 Stage 52 Stage 260When the horizon rolls forward by 1 week:
- Stage 1 (last week) → discarded
- Stages 2–260 → become stages 1–259
- New stage 260 → no cuts (terminal value = 0)
The new stage 260 has zero end value, which is fine because:
- It's 5 years out — discounting makes it nearly irrelevant
- Multi-year reservoirs have slow dynamics — a single missing end stage barely affects the near-term solution
- The SDDP iterations quickly fill in reasonable cuts for it
Weekly Full-Run Cycle
A recommended weekly pattern:
| Day | Mode | Notes |
|---|---|---|
| Monday | Full run | Fresh start, clears accumulated drift |
| Tuesday | Warm start | Small forecast update |
| Wednesday | Warm start | Cumulative drift monitored |
| Thursday | Warm start | |
| Friday | Warm start | |
| Saturday | — | No run (or automated warm start) |
| Sunday | — |
The full_run_interval = 7 setting automates this: after 7 days of warm starts, a full run is forced.
Monitoring Cumulative Drift
The restart_info in each RunResult provides drift telemetry:
result = run_case_incremental("cases/system_x"; start_date=today())
@info "Run complete" mode=result.restart_info.mode \
drift=result.restart_info.drift_today \
cumulative=result.restart_info.drift_cumul \
days_since_full=result.restart_info.days_since_full \
stage_shift=result.restart_info.stage_shiftSuggested monitoring alerts:
- Warning when
drift_cumul > 0.15— approaching full-run threshold - Alert when a full run is triggered by cumulative drift — indicates the forecast is drifting more than expected
- Dashboard: plot daily drift values and cumulative drift over time to spot seasonal patterns (e.g., spring flood → large inflow changes)
When to Force Full Runs
Beyond the automatic full_run_interval, force a full run when:
- System topology changes — new plant, reservoir maintenance, etc. The cut library is invalidated (different number of reservoirs changes gradient vector dimension)
- Price model re-estimation — currently the Markov price model is kept fixed between full runs. A new price model requires fresh cuts.
- Regulatory constraint changes — new min/max volume or flow limits
- After extended outage — if the planner hasn't run for several days, cumulative drift is unknown; a full run is safest
State Management
Retention Policy
State files accumulate in <case>/state/. Suggested retention:
- Keep last 30 days of state files
- Keep all "full run" states indefinitely (for audit trail)
- Archive older states to cold storage if needed
State Recovery
If the latest state file is corrupted or missing, the planner automatically falls back to a full run. This is by design — the warm start is an optimisation, not a requirement.
# The run_case_incremental function handles this gracefully:
# - Missing state file → full run
# - Corrupted state → full run with warning
# - Topology mismatch (different reservoirs) → full runMulti-System Operations
For organisations managing multiple hydropower systems:
for system in ["system_a", "system_b", "system_c"]
result = run_case_incremental("cases/$system";
start_date = today(),
warm_start_config = WarmStartConfig(full_run_interval=7))
write_output(result)
@info "$system" mode=result.restart_info.mode elapsed=result.elapsed_s
endEach system maintains its own state directory and drift tracking. Systems with more variable inflow (e.g., run-of-river) may need tighter drift_threshold than large-reservoir systems with slow volume changes.