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 bidding

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

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

  1. It's 5 years out — discounting makes it nearly irrelevant
  2. Multi-year reservoirs have slow dynamics — a single missing end stage barely affects the near-term solution
  3. The SDDP iterations quickly fill in reasonable cuts for it

Weekly Full-Run Cycle

A recommended weekly pattern:

DayModeNotes
MondayFull runFresh start, clears accumulated drift
TuesdayWarm startSmall forecast update
WednesdayWarm startCumulative drift monitored
ThursdayWarm start
FridayWarm 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_shift

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

  1. System topology changes — new plant, reservoir maintenance, etc. The cut library is invalidated (different number of reservoirs changes gradient vector dimension)
  2. Price model re-estimation — currently the Markov price model is kept fixed between full runs. A new price model requires fresh cuts.
  3. Regulatory constraint changes — new min/max volume or flow limits
  4. 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 run

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

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