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
| Field | Default | Description |
|---|---|---|
drift_threshold | 0.05 | If today's input drift exceeds this, do a full run |
cumulative_limit | 0.20 | If cumulative drift since last full run exceeds this, do a full run |
max_warm_iters | 20 | Maximum SDDP iterations when warm-starting |
full_run_interval | 7 | Force 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 previousCalendar-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 statisticsLow-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 cutsThe 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 driftThe 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, ...]
}
}