HydroRunner API Reference
HydroRunner.HydroRunner — Module
HydroRunnerConfiguration-driven runner for the hydropower seasonal planning system.
Reads a "case directory" containing:
topology.yaml— physical cascade description (reservoirs, plants, waterways)constraints.yaml— operational constraints (optional)config.yaml— run parameters (SDDP settings, resolution, horizons)inflows/— CSV files with inflow scenarios (m³/s per reservoir per week)prices/— CSV files with price scenarios (NOK/MWh per week)
Produces output in output/ subdirectory:
seasonal_plan.csv— volume and production P10/P50/P90 forecastscuts.csv— Benders cuts for short-term couplingsummary.json— run metadata and convergence info
Design
The CaseSource abstraction separates data loading from computation. DirectorySource reads from YAML/CSV files today; a future DatabaseSource can read the same logical data from SQL or APIs.
Quick Start
using HydroRunner
result = run_case("cases/orkla")Or from the command line:
julia --project=HydroRunner bin/run_seasonal.jl cases/orklaHydroRunner._WATERWAY_KINDS — Constant
Map YAML waterway type string to WaterwayKind enum.
HydroRunner.CaseData — Type
CaseDataAll data needed to run the seasonal planner, loaded from a CaseSource.
Fields
name: case name (from topology.yaml)cascade:Cascadewith all nodes, edges, constraintsinflow_scenarios: Vector of Dict{String, Vector{Float64}} — inflows per reservoir per scenario [m³/s]price_scenarios: Vector{Vector{Float64}} — price per stage per scenarioconfig: Dict{Symbol, Any} — all config.yaml settingssource: theCaseSourcethis was loaded from
HydroRunner.CaseSource — Type
CaseSourceAbstract type for loading hydropower case data. Implementations must define:
load_cascade(source) → Cascadeload_inflows(source) → Vector{Dict{String, Vector{Float64}}}load_prices(source) → Vector{Vector{Float64}}load_config(source) → Dict{Symbol, Any}output_dir(source) → String
HydroRunner.DirectorySource — Type
DirectorySourceReads case data from a directory with the standard layout:
case_dir/
topology.yaml
constraints.yaml (optional)
config.yaml
inflows/
*.csv
prices/
*.csv
output/ (created by writer)HydroRunner.RestartInfo — Type
RestartInfoMetadata about a warm-start or full run, attached to RunResult.
Fields
mode::fullor:warm_startdrift_today: combined input drift for this rundrift_cumul: cumulative drift since last full runn_iterations: SDDP iterations actually performeddays_since_full: days since last full SDDP runstart_date: planning start date for this runstage_shift: stages shifted from previous run's cut libraryreason: human-readable reason for the mode choice
HydroRunner.RunResult — Type
RunResultOutput of run_case().
Fields
case_data: the inputCaseDataprice_model: fittedMarkovPriceModelsddp_result:SDDPResultfrom solve_sddpplan:SeasonalPlanwith P10/P50/P90 forecastselapsed_s: total wall-clock time in seconds
HydroRunner.WarmStartConfig — Type
WarmStartConfigParameters controlling the warm-start / incremental replanning logic.
Fields
| Field | Default | Description |
|---|---|---|
drift_threshold | 0.05 | Max single-run drift for warm start |
cumulative_limit | 0.20 | Max accumulated drift before forced full run |
max_warm_iters | 20 | SDDP iterations when warm-starting |
full_run_interval | 7 | Force full run every N days (0 = never) |
weights | (inflow=0.5, price=0.5) | Drift metric weights |
HydroRunner._cascade_energy_equivalent — Method
_cascade_energy_equivalent(cascade, reservoir_id) → Float64Compute the total energy equivalent (MWh/Mm³) for water released from a reservoir, accounting for all downstream plants in the cascade.
HydroRunner._compute_energy_terminal_cuts — Method
_compute_energy_terminal_cuts(cascade, price_model, resolution; scale=1.15)Compute terminal water value cuts from cascade energy equivalent. Creates piecewise-linear cuts (11 breakpoints) per price state.
HydroRunner._compute_state_segment_profiles — Method
_compute_state_segment_profiles(segmented_prices, price_model)Compute average intra-week segment profile per Markov price state.
For each state, averages the 42-segment price profiles across all scenario-weeks assigned to that state. Used in the backward pass so that Benders cuts capture the value of intra-week dispatch.
HydroRunner._fit_price_model — Method
Fit a Markov price model from the price scenarios.
Concatenates all price scenarios into one long series and fits.
HydroRunner._load_inflows — Method
_load_inflows(source, cascade) → Vector{Dict{String, Vector{Float64}}}Each CSV file in inflows/ becomes one scenario. Columns: week (or stage) + one column per reservoir ID. Values are in m³/s.
HydroRunner._load_prices — Method
_load_prices(source) → Vector{Vector{Float64}}Each CSV file in prices/ becomes one price scenario. Columns: week (or stage) + price. Values are NOK/MWh.
HydroRunner._load_segmented_prices — Method
_load_segmented_prices(source) → Vector{Vector{Vector{Tuple{Float64,Float64}}}}Load intra-week price segments from prices_segmented/ directory. Each CSV has columns: week, segment, hours, price. Returns [scenario][week][(hours, price)] or empty if directory absent.
HydroRunner._load_terminal_values — Method
_load_terminal_values(source, cascade) → Dict{Int, Vector{Tuple{Float64, Vector{Float64}}}}Load terminal water value cuts from terminal_values.yaml. Returns Dict mapping price_state (1-indexed) => [(intercept, gradient)].
HydroRunner._make_x_axis — Method
Generate x-axis values, label, and tick marks appropriate for the resolution and number of stages.
HydroRunner._resolve_initial_volumes — Method
Resolve initial volumes: config overrides take priority, then fall back to each reservoir's initial_volume.
HydroRunner.generate_plan_nested — Method
generate_plan_nested(sddp_result, cascade, inflow_scenarios, price_model; ...)Like generate_plan but uses nested decomposition:
- Simple LP for volume/discharge decisions (fast, uses SDDP cuts)
- Greedy dispatch for revenue computation (captures segment value)
HydroRunner.load_case — Method
load_case(path::String) → CaseData
load_case(source::CaseSource) → CaseDataLoad a complete case from a directory (or other source).
case = load_case("cases/orkla")HydroRunner.plot_results — Method
plot_results(result::RunResult; kwargs...) → Vector{String}Generate all standard plots and save to disk. Returns a vector of file paths for the generated figures.
Keyword Arguments
output_dir: directory for output files (default: case output dir)format::png(default) or:svgdpi: resolution for PNG (default: 200)width: figure width in pixels (default: 1200)height: figure height in pixels (default: 500)
Generated Plots
volume_forecast_<reservoir_id>.{png,svg}— one per reservoirproduction_forecast.{png,svg}— aggregate production fan chartoverview.{png,svg}— combined multi-panel overview
HydroRunner.run_case — Method
run_case(path::String; verbose=true) → RunResult
run_case(case::CaseData; verbose=true) → RunResultRun the full seasonal planning pipeline for a case directory.
Steps
- Load case data (if path given)
- Fit Markov price model from price scenarios
- Resolve initial volumes (config overrides → reservoir defaults)
- Run SDDP
- Generate seasonal plan with Monte Carlo forward simulation
result = run_case("cases/demo_cascade")
println("Revenue forecast: ", result.plan.mean_revenue / 1e6, " MNOK")HydroRunner.run_case_incremental — Method
run_case_incremental(path; start_date, warm_start_config, state_dir, verbose)
run_case_incremental(case; start_date, warm_start_config, state_dir, verbose)Run the seasonal planning pipeline with warm-start support.
If a previous state file exists in state_dir and the input drift is below threshold, reuses the previous cut library (shifted forward) and runs only a few SDDP iterations. Otherwise performs a full run.
Returns
(RunResult, RestartInfo) — the result and metadata about the restart decision.
HydroRunner.run_case_nested — Method
run_case_nested(path; verbose=true) → RunResult
run_case_nested(case; verbose=true) → RunResultRun with nested decomposition: fast weekly LP for SDDP cuts, greedy intra-week dispatch for simulation revenue.
- Outer SDDP: simple (non-segmented) LP with scalar mean price. Fast (~0.17ms/solve). Generates Benders cuts on weekly volumes.
- Simulation: uses SDDP cuts for volume decisions, then dispatches each plant's weekly discharge greedily across price segments.
This is ~10× faster than the full-segment approach while capturing most of the intra-week dispatch value in the simulation revenue.
HydroRunner.write_output — Method
write_output(result::RunResult) → StringWrite all output files to the case's output directory. Returns the output directory path.
result = run_case("cases/demo_cascade")
outdir = write_output(result)
println("Output written to: ", outdir)