WaterValues API Reference
WaterValues.WaterValues — Module
WaterValuesSingle-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 aliasExports
VolumeGrid,grid_stepPeriodicInflows,WeeklyInflows(alias),mean_inflowextract_periodic_inflows,extract_weekly_inflows(alias)SDPParameters,run_sdp,solve_sdpWaterValueTable,n_weeks,lookup,lookup_vf,mean_water_values
WaterValues.PeriodicInflows — Type
PeriodicInflowsAll 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 yearn: 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
SDPParametersConfiguration 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(defaultWEEKLY)
WaterValues.VolumeGrid — Type
VolumeGridA 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_minvalues[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
WaterValueTableStores the result of the backward-induction SDP for a single reservoir.
Fields
grid:VolumeGrid— the discretised reservoir volumeswv: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.InflowSerieswith values in m³/sresolution:PlanningResolution(defaultWEEKLY)
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 elementsWaterValues.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) → Float64Uniform spacing between grid points (Mm³).
WaterValues.interp_vf — Method
interp_vf(vf, grid, v) → Float64Linear interpolation of a value-function vector at volume v.
WaterValues.lookup — Method
lookup(wvt::WaterValueTable; stage, volume) → Float64Return 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-compatWaterValues.lookup_vf — Method
lookup_vf(wvt::WaterValueTable; stage, volume) → Float64Return 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) → Float64Mean 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) → IntAlias for wvt.n_stages, kept for code written before Phase 0.5.
WaterValues.run_sdp — Method
run_sdp(grid, periodic_inflows, pq_curve, params) → WaterValueTableRun backward induction SDP for a single reservoir and return a WaterValueTable.
Arguments
grid:VolumeGrid— reservoir discretisationperiodic_inflows:Vector{PeriodicInflows}(length = n_stages)pq_curve:HydroCore.PQCurve— power-discharge relationshipparams: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)
→ WaterValueTableHigh-level entry point: compute water values for a single-reservoir, single-plant system.
Arguments
reservoir:HydroCore.Reservoirplant:HydroCore.Plantperiodic_inflows:Vector{PeriodicInflows}— one per stage of the yearprice: flat electricity price[NOK/MWh]resolution:PlanningResolution(defaultWEEKLY)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³