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, WaterValues

Quick 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 sampling

Case 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.json

File 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: Fjord

constraints.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: false

config.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 for

inflows/*.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: week or stage (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
...
  • price column: 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 forebay

Plants 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
# end

To add a new data source, implement:

  • load_cascade(source) → Cascade
  • load_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()'
done

Troubleshooting

  • 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

  1. Copy cases/demo_cascade/ as a template
  2. Edit topology.yaml with your watercourse
  3. Place inflow CSVs in inflows/ (one per weather year)
  4. Place price CSVs in prices/
  5. Adjust config.yaml (horizon, iterations, etc.)
  6. 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.