HydroRunner API Reference

HydroRunner.HydroRunner — Module
HydroRunner

Configuration-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 forecasts
  • cuts.csv — Benders cuts for short-term coupling
  • summary.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/orkla
HydroRunner.CaseData — Type
CaseData

All data needed to run the seasonal planner, loaded from a CaseSource.

Fields

  • name : case name (from topology.yaml)
  • cascade : Cascade with all nodes, edges, constraints
  • inflow_scenarios : Vector of Dict{String, Vector{Float64}} — inflows per reservoir per scenario [m³/s]
  • price_scenarios : Vector{Vector{Float64}} — price per stage per scenario
  • config : Dict{Symbol, Any} — all config.yaml settings
  • source : the CaseSource this was loaded from
HydroRunner.CaseSource — Type
CaseSource

Abstract type for loading hydropower case data. Implementations must define:

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

Reads 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
RestartInfo

Metadata about a warm-start or full run, attached to RunResult.

Fields

  • mode : :full or :warm_start
  • drift_today : combined input drift for this run
  • drift_cumul : cumulative drift since last full run
  • n_iterations : SDDP iterations actually performed
  • days_since_full : days since last full SDDP run
  • start_date : planning start date for this run
  • stage_shift : stages shifted from previous run's cut library
  • reason : human-readable reason for the mode choice
HydroRunner.RunResult — Type
RunResult

Output of run_case().

Fields

  • case_data : the input CaseData
  • price_model : fitted MarkovPriceModel
  • sddp_result : SDDPResult from solve_sddp
  • plan : SeasonalPlan with P10/P50/P90 forecasts
  • elapsed_s : total wall-clock time in seconds
HydroRunner.WarmStartConfig — Type
WarmStartConfig

Parameters controlling the warm-start / incremental replanning logic.

Fields

FieldDefaultDescription
drift_threshold0.05Max single-run drift for warm start
cumulative_limit0.20Max accumulated drift before forced full run
max_warm_iters20SDDP iterations when warm-starting
full_run_interval7Force 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) → Float64

Compute 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.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) → CaseData

Load 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 :svg
  • dpi : resolution for PNG (default: 200)
  • width : figure width in pixels (default: 1200)
  • height : figure height in pixels (default: 500)

Generated Plots

  1. volume_forecast_<reservoir_id>.{png,svg} — one per reservoir
  2. production_forecast.{png,svg} — aggregate production fan chart
  3. overview.{png,svg} — combined multi-panel overview
HydroRunner.run_case — Method
run_case(path::String; verbose=true) → RunResult
run_case(case::CaseData; verbose=true) → RunResult

Run the full seasonal planning pipeline for a case directory.

Steps

  1. Load case data (if path given)
  2. Fit Markov price model from price scenarios
  3. Resolve initial volumes (config overrides → reservoir defaults)
  4. Run SDDP
  5. 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) → RunResult

Run 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) → String

Write 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)