HydroRunner — Case-Based Seasonal Planning
Overview
HydroRunner is the configuration-driven runner layer on top of the hydropower library packages. It reads a case directory containing YAML topology files and CSV data files, runs the seasonal planning pipeline (SDDP → Monte Carlo forecast), and writes structured output.
┌──────────────┐ ┌────────────┐ ┌──────────────┐
│ Case files │ ──► │ HydroRunner│ ──► │ Output CSV/ │
│ YAML + CSV │ │ pipeline │ │ JSON files │
└──────────────┘ └────────────┘ └──────────────┘
│
uses: HydroCore, SeasonalPlanning,
WeeklyScheduling, WaterValuesQuick Start
From Julia
using HydroRunner
# Full segment strategy (default — segments in both SDDP passes)
result = run_case("cases/dokka")
# Nested decomposition (scalar LP + greedy dispatch)
result = run_case_nested("cases/dokka")
# Write output files
outdir = write_output(result)From Command Line
# Full segment strategy
julia --project=HydroRunner HydroRunner/bin/run_case.jl cases/dokka
# Multi-threaded (SDDP backward pass parallelised)
julia -t4 --project=HydroRunner HydroRunner/bin/run_case.jl cases/dokka
julia -tauto --project=HydroRunner HydroRunner/bin/run_case.jl cases/dokka
# Nested decomposition
julia --project=HydroRunner HydroRunner/bin/run_case.jl cases/dokka --nested-decomp
# Options
# --no-charts Skip chart generation
# --charts-dir DIR Custom chart output directory
# --vol-convergence Volume-stability convergence
# --head-correction Iterative head correction
# --inflow-ar1 AR(1) conditional inflow samplingCase Directory Structure
cases/my_watercourse/
├── topology.yaml # Physical system: reservoirs, plants, waterways
├── constraints.yaml # Operational constraints (optional)
├── config.yaml # Run parameters: SDDP config, horizons, seeds
├── terminal_values.yaml # Terminal water value cuts (optional)
├── inflows/
│ ├── 1984.csv # One CSV per weather year / scenario
│ ├── 1985.csv
│ └── ...
├── prices/
│ ├── 1984.csv # One CSV per price scenario
│ └── ...
├── prices_segmented/ # Intra-week segments (optional, enables dispatch)
│ ├── 1984.csv # 42×4h segments per week
│ └── ...
└── output/ # Created by runner
├── volume_M802.png
├── production_plants.png
├── revenue.png
├── seasonal_plan.csv
└── summary.jsonFile Format Reference
topology.yaml
Describes the physical cascade: reservoirs, plants, waterways, and sinks.
name: My Watercourse
reservoirs:
- id: R_upper # Unique string ID
name: Mountain Lake # Human-readable name
min_volume: 0.0 # Mm³
max_volume: 200.0 # Mm³
initial_volume: 100.0 # Mm³ (optional, defaults to midpoint)
hv_curve: # Height-Volume curve
volumes: [0, 50, 100, 150, 200] # Mm³
elevations: [600, 625, 650, 675, 700] # m.a.s.l.
plants:
- id: Plant_A
name: Mountain Station
from: R_upper # Upstream node ID
to: R_lower # Downstream node ID
num_units: 2 # Number of generating units (default: 1)
min_discharge: 0.0 # m³/s (default: 0)
max_discharge: 100.0 # m³/s
penstock_loss: 2.0 # m head loss at max discharge (default: 0)
pq_curve: # Power-Discharge curve
reference_head: 450.0 # m (head at which PQ was measured)
discharges: [0, 25, 50, 75, 100] # m³/s
powers: [0, 16, 30, 42, 52] # MW
waterways:
- id: Spillway_upper
name: Mountain Spillway
from: R_upper
to: R_lower
type: spillway # spillway | river_reach | tunnel | bypass
min_flow: 0.0 # m³/s (default: 0)
max_flow: 500.0 # m³/s
delay_h: 0.0 # Water travel time in hours (default: 0)
junctions: # Optional: flow merging points
- id: J1
name: Confluence
sinks:
- id: SEA
name: Fjordconstraints.yaml (optional)
flow_constraints:
- edge_id: Plant_A # Plant or waterway ID
min_flow: 5.0 # m³/s
max_flow: 90.0 # m³/s
volume_constraints:
- reservoir_id: R_upper
min_volume: 20.0 # Mm³ — flood reserve / ecological floor
max_volume: 190.0 # Mm³
start_date: "2020-05-01" # When this constraint is active
end_date: "2020-09-30"
ramp_constraints:
- plant_id: Plant_A
max_ramp_up: 10.0 # m³/s per hour
max_ramp_dn: 8.0 # m³/s per hour
min_env_flows:
- edge_id: Spillway_upper
min_flow: 2.0 # m³/s minimum environmental flow
seasonal: falseconfig.yaml
resolution: weekly # weekly | daily | hourly
n_stages: 52 # Planning horizon (number of time steps)
# SDDP algorithm parameters
n_iterations: 50 # Max SDDP iterations
n_forward_scenarios: 20 # Forward scenarios per iteration
convergence_tol: 0.03 # Relative gap for convergence
seed: 42 # Random seed for reproducibility
# Price model
price_model:
type: markov # Currently only 'markov' supported
n_states: 3 # Number of discrete price states
# Initial conditions
initial_volumes: # Override reservoir defaults (optional)
R_upper: 100.0
R_lower: 15.0
initial_price_state: 2 # Starting Markov price state (1-indexed)
# Output parameters
n_sim_scenarios: 100 # Monte Carlo scenarios for P10/P50/P90
near_term_stages: [1, 2, 3] # Stages to extract Benders cuts forinflows/*.csv
Each CSV file is one inflow scenario (weather year). The runner loads all CSV files in the directory alphabetically — each becomes one scenario in the SDDP draw-with-replacement sampling.
week,R_upper,R_lower
1,12.3,4.5
2,11.8,4.2
3,15.1,5.0
...- First column:
weekorstage(integer, 1-based) - Remaining columns: reservoir IDs matching
topology.yaml - Values: inflow in m³/s (mean flow over the time step)
prices/*.csv
Each CSV file is one price scenario. All scenarios are concatenated to fit the Markov price model.
week,price
1,450.0
2,420.0
3,380.0
...pricecolumn: electricity price in NOK/MWh
prices_segmented/*.csv (optional)
Intra-week price segments enabling dispatch optimisation. Each file is one scenario with 42 segments × 4 hours per week (168 hours total).
week,segment,hours,price
1,1,4,13.98
1,2,4,35.69
1,3,4,54.00
...When present, the SDDP builds a segmented LP with per-segment discharge and production variables. The backward pass uses average segment profiles per Markov state. If absent, a simple weekly LP with scalar prices is used.
topology.yaml — additional features
Reservoirs can be marked as buffers:
reservoirs:
- id: M800
reservoir_type: buffer # Volume fixed at min_volume in LP
max_volume: 0.5 # Small passthrough forebayPlants can have an energy_equivalent field:
plants:
- id: P802
energy_equivalent: 1.1 # MWh/m³ (informational)Output Files
seasonal_plan.csv
stage,R_upper_vol_p10,R_upper_vol_p50,R_upper_vol_p90,R_lower_vol_p10,...,production_p10,production_p50,production_p90
1,85.2,95.1,102.3,12.1,...,3500,4200,5100
2,78.4,90.3,98.7,11.5,...,3200,3900,4800
...cuts.csv
Benders cuts at near-term stages for coupling to short-term planning:
stage,price_state,intercept,grad_R_upper,grad_R_lower
1,1,125000.5,450.2,320.1
1,2,148000.3,480.5,340.8
...The cut represents: future_value ≤ intercept + grad_R_upper × v_upper + grad_R_lower × v_lower
summary.json
{
"case_name": "Demo Cascade",
"n_reservoirs": 2,
"sddp": {
"n_iterations": 15,
"converged": true,
"n_cuts": 450
},
"plan": {
"mean_revenue_MNOK": 12.35
},
"elapsed_seconds": 45.2
}Architecture: CaseSource Abstraction
The CaseSource abstract type separates data loading from computation:
abstract type CaseSource end
# Current implementation: files on disk
struct DirectorySource <: CaseSource
path::String
end
# Future: database backend
# struct DatabaseSource <: CaseSource
# connection::DBConnection
# case_id::Int
# endTo add a new data source, implement:
load_cascade(source)→Cascadeload_inflows(source)→Vector{Dict{String, Vector{Float64}}}load_prices(source)→Vector{Vector{Float64}}load_config(source)→Dict{Symbol, Any}
The runner (run_case) only depends on CaseData, not on how it was loaded.
Setting Up on Another Computer
# 1. Clone the repository
git clone <repo-url> hydropower
cd hydropower/exploration
# 2. Install Julia 1.10+ (https://julialang.org/downloads/)
# 3. Instantiate all packages (downloads dependencies)
for pkg in HydroCore WaterValues WeeklyScheduling SeasonalPlanning HydroSimulation HydroRunner; do
julia --project=$pkg -e 'using Pkg; Pkg.instantiate()'
done
# 4. Run the demo case
julia --project=HydroRunner bin/run_seasonal.jl cases/demo_cascade
# 5. Run all tests
for pkg in HydroCore WaterValues WeeklyScheduling HydroSimulation SeasonalPlanning HydroRunner; do
echo "Testing $pkg..."
julia --project=$pkg -e 'using Pkg; Pkg.test()'
doneTroubleshooting
Package resolution errors: Dev dependencies need sequential activation. If
Pkg.instantiate()fails for HydroRunner, try:using Pkg Pkg.activate("HydroRunner") Pkg.develop(path="HydroCore") Pkg.develop(path="WaterValues") Pkg.develop(path="WeeklyScheduling") Pkg.develop(path="SeasonalPlanning") Pkg.develop(path="HydroSimulation")Precompilation slow on first run: Normal for Julia. Subsequent runs use cached compilation.
Creating Your Own Case
- Copy
cases/demo_cascade/as a template - Edit
topology.yamlwith your watercourse - Place inflow CSVs in
inflows/(one per weather year) - Place price CSVs in
prices/ - Adjust
config.yaml(horizon, iterations, etc.) - Run:
julia --project=HydroRunner bin/run_seasonal.jl cases/my_watercourse
Known Limitations
- No head correction: PQ curves evaluated at reference head, not actual reservoir level. Head varies ~7% for Dokka — expected 1-3% revenue impact.
- No unit commitment: LP relaxation only (no on/off decisions).
- No discount rate: Future revenue undiscounted. ProdRisk uses 7.8% annual.
- Nested decomposition: the scalar backward LP cannot capture dispatch flexibility in cut shadow prices, causing over-conservation.
- LB convergence: without SDP seeding, the lower bound converges slowly (21M vs UB 160M after 12 iterations). The simulation policy is good but the theoretical convergence guarantee is weak.
- SDP seeding: single-reservoir SDP overestimates for multi-reservoir cascades with binding constraints, causing invalid cuts. Currently disabled.