WaterValues API Reference

WaterValues.WaterValues — Module
WaterValues

Single-reservoir Stochastic Dynamic Programming for hydropower water value computation. Time resolution is configurable via PlanningResolution.

What this package does

Given:

  • A reservoir (volume bounds, HV curve)
  • A plant (PQ curve, max discharge)
  • Historical inflow observations (any time resolution)
  • A flat electricity price

It computes a water value table: WV(stage, volume) → NOK/Mm³

The water value is the shadow price of water in the reservoir — the marginal revenue gain from having one more Mm³ of water in storage at a given stage. This is the key output of long-term hydropower planning (Kompendium 1, Ch. 6).

Usage

using HydroCore, WaterValues

hv    = HVCurve([0.0, 100.0], [400.0, 450.0])
pq    = PQCurve(reference_head=50.0,
                discharges=[0.0, 50.0, 100.0],
                powers    =[0.0, 30.0,  55.0])
res   = Reservoir("R1", "MyLake", 0.0, 100.0, 50.0, hv)
plant = Plant("P1", "MyPlant", res, Sink("SEA","Ocean");
              num_units=1, min_discharge=0.0, max_discharge=100.0, pq_curve=pq)

# Build inflow scenarios from InflowSeries (weekly, default)
inflows = extract_periodic_inflows(my_series, WEEKLY)   # 52 PeriodicInflows

# Or build synthetic inflows directly
inflows = [PeriodicInflows(w, rand(30) .* 5.0 .+ 1.0) for w in 1:52]

# Run SDP (weekly resolution, default)
wvt = solve_sdp(res, plant, inflows; price=400.0, n_grid=20, n_cycles=8)

# Look up a water value
wv  = lookup(wvt; stage=25, volume=60.0)    # NOK/Mm³
wv2 = lookup(wvt; week=25,  volume=60.0)    # backward-compat alias

Exports

  • VolumeGrid, grid_step
  • PeriodicInflows, WeeklyInflows (alias), mean_inflow
  • extract_periodic_inflows, extract_weekly_inflows (alias)
  • SDPParameters, run_sdp, solve_sdp
  • WaterValueTable, n_weeks, lookup, lookup_vf, mean_water_values
WaterValues.PeriodicInflows — Type
PeriodicInflows

All historical inflow observations for a specific stage of the planning year (e.g. week 15 of 52, or day 105 of 365), drawn from an InflowSeries.

Each value is one equally-likely inflow scenario (Mm³ per stage).

The stage index and the number of stages per year depend on the PlanningResolution used when building the scenarios.

Fields

  • stage : stage index within the planning year (1 … n_stages)
  • values : historical observations [Mm³/stage], one per scenario year
  • n : number of scenarios

Backward-compatibility alias

WeeklyInflows is a type alias for PeriodicInflows kept for code written before Phase 0.5. Prefer PeriodicInflows in new code.

WaterValues.SDPParameters — Type
SDPParameters

Configuration for the backward-induction SDP.

Fields

  • n_cycles : number of full-year iterations (default 10)
  • terminal_wv : starting water value estimate [NOK/Mm³]
  • price : assumed flat electricity price [NOK/MWh]
  • r_max : maximum turbine discharge [Mm³/stage]
  • tol : convergence tolerance [NOK] (default 1.0)
  • resolution : PlanningResolution (default WEEKLY)
WaterValues.VolumeGrid — Type
VolumeGrid

A uniform discretisation of reservoir storage between v_min and v_max.

Fields

  • v_min : lower bound (Mm³)
  • v_max : upper bound (Mm³)
  • n : number of grid points (including endpoints)
  • values : the grid values as a sorted Vector{Float64}

Notes

  • values[1] == v_min
  • values[end] == v_max
  • Uniform spacing: Δv = (v_max - v_min) / (n - 1)
WaterValues.VolumeGrid — Method
VolumeGrid(reservoir; n=30)

Convenience constructor from a HydroCore.Reservoir.

WaterValues.WaterValueTable — Type
WaterValueTable

Stores the result of the backward-induction SDP for a single reservoir.

Fields

  • grid : VolumeGrid — the discretised reservoir volumes
  • wv : Matrix{Float64} (nstages × nv) — water values [NOK/Mm³]
  • vf : Matrix{Float64} (nstages × nv) — value function [NOK]
  • n_stages : number of planning stages (52 for weekly, 365 for daily, …)

Indexing convention

  • Row index = stage (1 = first stage of planning year)
  • Column index = volume grid index (1 = v_min)

Backward-compatibility note

The field n_stages was previously called n_weeks. The accessor n_weeks(wvt) still works.

Why NOK/Mm³?

Callers can convert to NOK/MWh by multiplying by the energy yield (MWh/Mm³) of the specific plant.

WaterValues.extract_periodic_inflows — Function
extract_periodic_inflows(series, resolution) → Vector{PeriodicInflows}

Extract one PeriodicInflows per stage of the planning year from an InflowSeries, using resolution to determine the stage boundaries.

The inflow series is expected to have values in m³/s. Each observation is converted to Mm³/stage using m3s_to_Mm3_per_step(resolution).

Arguments

  • series : HydroCore.InflowSeries with values in m³/s
  • resolution : PlanningResolution (default WEEKLY)

Returns

Vector{PeriodicInflows} of length resolution.n_stages.

Example

weekly  = extract_periodic_inflows(my_series, WEEKLY)   # 52 elements
daily   = extract_periodic_inflows(my_series, DAILY)    # 365 elements
WaterValues.extract_weekly_inflows — Method
extract_weekly_inflows(series) → Vector{PeriodicInflows}

Backward-compatible wrapper for extract_periodic_inflows(series, WEEKLY). Prefer extract_periodic_inflows in new code.

WaterValues.grid_step — Method
grid_step(g::VolumeGrid) → Float64

Uniform spacing between grid points (Mm³).

WaterValues.interp_vf — Method
interp_vf(vf, grid, v) → Float64

Linear interpolation of a value-function vector at volume v.

WaterValues.lookup — Method
lookup(wvt::WaterValueTable; stage, volume) → Float64

Return the water value [NOK/Mm³] for a given stage (1…n_stages) and volume (Mm³).

Volume is linearly interpolated between the nearest grid points. Volumes outside [vmin, vmax] are clamped to the boundary values.

The keyword week is accepted as a backward-compatible alias for stage.

Example

wv = lookup(wvt; stage=30, volume=85.0)   # NOK/Mm³
wv = lookup(wvt; week=30,  volume=85.0)   # same, backward-compat
WaterValues.lookup_vf — Method
lookup_vf(wvt::WaterValueTable; stage, volume) → Float64

Return the value function V_t(v) [NOK] for a given stage and volume. Accepts week as a backward-compatible alias for stage.

WaterValues.mean_inflow — Method
mean_inflow(w::PeriodicInflows) → Float64

Mean inflow across all scenarios (Mm³/stage).

WaterValues.mean_water_values — Method
mean_water_values(wvt::WaterValueTable) → Vector{Float64}

Mean water value per stage (averaged across all volume grid points). Useful for a quick sanity check: values should be highest in dry seasons.

WaterValues.n_weeks — Method
n_weeks(wvt::WaterValueTable) → Int

Alias for wvt.n_stages, kept for code written before Phase 0.5.

WaterValues.run_sdp — Method
run_sdp(grid, periodic_inflows, pq_curve, params) → WaterValueTable

Run backward induction SDP for a single reservoir and return a WaterValueTable.

Arguments

  • grid : VolumeGrid — reservoir discretisation
  • periodic_inflows : Vector{PeriodicInflows} (length = n_stages)
  • pq_curve : HydroCore.PQCurve — power-discharge relationship
  • params : SDPParameters

The number of stages is inferred from length(periodic_inflows).

WaterValues.solve_sdp — Method
solve_sdp(reservoir, plant, periodic_inflows; price, resolution, n_grid, n_cycles, tol)
    → WaterValueTable

High-level entry point: compute water values for a single-reservoir, single-plant system.

Arguments

  • reservoir : HydroCore.Reservoir
  • plant : HydroCore.Plant
  • periodic_inflows : Vector{PeriodicInflows} — one per stage of the year
  • price : flat electricity price [NOK/MWh]
  • resolution : PlanningResolution (default WEEKLY)
  • n_grid : volume grid points (default 30)
  • n_cycles : SDP iteration cycles (default 10)
  • tol : convergence tolerance [NOK] (default 1.0)

Example

inflows = extract_periodic_inflows(series, WEEKLY)   # 52 stages
wvt     = solve_sdp(reservoir, plant, inflows; price=400.0)
wv      = lookup(wvt; stage=25, volume=80.0)          # NOK/Mm³