Warm-Start API Reference

Configuration

using HydroRunner

cfg = WarmStartConfig(;
    drift_threshold   = 0.05,    # max single-day drift for warm start
    cumulative_limit  = 0.20,    # max accumulated drift before full run
    max_warm_iters    = 20,      # SDDP iterations in warm-start mode
    full_run_interval = 7,       # force full run every N days (0 = never)
    weights           = (inflow=0.5, price=0.5),  # drift metric weights
)

Fields

FieldDefaultDescription
drift_threshold0.05If today's input drift exceeds this, do a full run
cumulative_limit0.20If cumulative drift since last full run exceeds this, do a full run
max_warm_iters20Maximum SDDP iterations when warm-starting
full_run_interval7Force a full run every N calendar days (0 = never)
weights(inflow=0.5, price=0.5)Weights for combining inflow and price drift

Note: stage_shift is computed automatically from the difference between the previous run's start_date and today's start_date.

Main Entry Point

result = run_case_incremental(
    "cases/demo_cascade";
    warm_start_config = WarmStartConfig(),
    start_date = today(),                         # Date
    state_dir = "cases/demo_cascade/state",       # default
    verbose = true,
)

Returns a RunResult with an additional restart_info field:

result.restart_info.mode            # :full or :warm_start
result.restart_info.drift_today     # combined drift metric
result.restart_info.drift_cumul     # cumulative since last full
result.restart_info.n_iterations    # actual iterations used
result.restart_info.days_since_full
result.restart_info.start_date      # Date this run covers
result.restart_info.stage_shift     # stages shifted from previous

Calendar-Aware Planning (HydroCore)

PlanningHorizon

using HydroCore

horizon = PlanningHorizon(;
    start_date = Date(2026, 3, 22),
    resolution = WEEKLY,
    n_stages   = 260,              # 5 years × 52 weeks
)

stage_date(horizon, 1)             # → Date(2026, 3, 22)
stage_date(horizon, 53)            # → Date(2027, 3, 21)
date_stage(horizon, Date(2026, 6, 1))  # → 11
calendar_week(horizon, 1)          # → 12 (ISO week of March 22)

Operational Scenario Construction

using SeasonalPlanning

# 1-year prognosis + weather-year statistics → 5-year scenarios
scenarios = build_operational_scenarios(
    prognosis,           # Dict{String, Vector{Float64}} — 52 weeks
    weather_years,       # Vector{Dict{String, Vector{Float64}}} — N years × 52 weeks
    horizon,             # PlanningHorizon (260 stages)
)
# → Vector{Dict{String, Vector{Float64}}} of length N_weather_years
# Each scenario: 52 weeks prognosis + 208 weeks sampled statistics

Low-Level API (SeasonalPlanning)

Cut Serialisation

using SeasonalPlanning

# Save SDDP state after a run
save_state("path/to/state.json", sddp_result, input_fingerprint;
           start_date=Date(2026, 3, 22))

# Load previous state
lib, metadata = load_state("path/to/state.json")
# lib :: CutLibrary
# metadata :: Dict with :fingerprint, :start_date, :cumulative_drift, etc.

The input_fingerprint is a Dict containing the mean inflow and price profiles used for the run, enabling drift computation on next load.

Stage Shifting

# Shift cut library by n stages (for rolling horizon)
shifted_lib = shift_cuts(lib, n_steps=1)
# Stage 2 → 1, Stage 3 → 2, ..., new final stage has no cuts

The shift amount is computed from the calendar:

n_steps = date_stage(new_horizon, stage_date(old_horizon, 1))
# = how many new-horizon stages the old start date is "past"

Drift Computation

drift = compute_input_drift(old_fingerprint, new_fingerprint;
                             weights=(inflow=0.5, price=0.5),
                             stage_offset=1)  # calendar alignment
# drift :: Float64 — combined relative drift

The stage_offset parameter handles calendar alignment: yesterday's mean inflow at stage 2 is compared to today's at stage 1 (same week).

Warm-Start SDDP

# Standard solve_sddp with initial cuts for warm start
result = solve_sddp(cascade, inflow_scenarios, price_model,
                     SDDPConfig(n_iterations=20);  # fewer iterations
                     v0=v0,
                     initial_cuts=shifted_lib)     # warm start!

State Directory Layout

cases/demo_cascade/
├── topology.yaml
├── config.yaml              # planning.mode = calendar
├── prognosis/               # 1-year inflow forecast
├── weather_years/           # multi-year inflow statistics
├── prices/
├── state/                   # Warm-start persistence
│   ├── latest.json          # Symlink to most recent
│   ├── 2026-03-22.json      # State from each run
│   ├── 2026-03-21.json
│   └── ...
└── output/

Each state file contains:

{
  "start_date": "2026-03-22",
  "timestamp": "2026-03-22T06:01:00",
  "mode": "warm_start",
  "n_iterations": 5,
  "converged": true,
  "days_since_full_run": 3,
  "cumulative_drift": 0.08,
  "drift_today": 0.02,
  "input_fingerprint": {
    "mean_inflow": {"R1": [1.2, 1.1, ...], "R2": [0.8, 0.7, ...]},
    "mean_price": [350.0, 340.0, ...]
  },
  "cut_library": {
    "n_stages": 260,
    "n_price_states": 3,
    "cuts": [[[{"intercept": 1234.5, "gradient": [0.1, 0.2]}], ...], ...]
  },
  "convergence": {
    "lower_bounds": [100.0, 105.0, ...],
    "upper_bounds": [120.0, 112.0, ...]
  }
}