HydroSimulation API Reference

HydroSimulation.HydroSimulation — Module
HydroSimulation

Monte Carlo simulation of single-reservoir hydropower operation using a water value table as the operating policy.

What this package does

Given a converged WaterValueTable from Phase 1 SDP, simulate many years of reservoir operation by:

  1. At each stage t, drawing a random inflow from the historical scenario pool
  2. Using the SDP value function to find the optimal release (greedy dispatch)
  3. Advancing the reservoir volume and recording production/revenue

Running this across N scenario years gives P10/P50/P90 trajectories for reservoir levels and production — the primary validation tool for water values.

Usage

using HydroCore, WaterValues, HydroSimulation

# Assume wvt, reservoir, plant already built (see WaterValues docs)
inflows = extract_periodic_inflows(my_series, WEEKLY)   # 52 PeriodicInflows
prices  = fill(400.0, 52)                               # NOK/MWh per stage

# Run 100 Monte Carlo years
result = monte_carlo(wvt, reservoir, plant, inflows, prices;
                     n_scenarios=100, seed=42)

println(result)
# SimulationResult: 100 scenarios × 52 stages (weekly), mean revenue=X MNOK/yr

# P10/P50/P90 reservoir level trajectories
v10 = volume_p10(result)   # Vector{Float64}, length 52
v50 = volume_p50(result)
v90 = volume_p90(result)

Exports

  • YearResult, SimulationResult
  • simulate_year, monte_carlo
  • volume_p10, volume_p50, volume_p90
  • production_p10, production_p50, production_p90
  • mean_annual_revenue, annual_production
  • spill_fraction, shortage_fraction
HydroSimulation.SimulationResult — Type
SimulationResult

Aggregated result from many Monte Carlo years.

Fields

  • volume : Matrix{Float64} (n_scenarios × T) — reservoir volume
  • production : Matrix{Float64} (n_scenarios × T) — energy [MWh/stage]
  • revenues : Vector{Float64} (n_scenarios) — annual revenue [NOK]
  • n_scenarios : number of simulated years
  • n_stages : number of planning stages per year
  • resolution : PlanningResolution used
HydroSimulation.YearResult — Type
YearResult

Result of simulating one year of reservoir operation.

Fields

  • volume : end-of-stage reservoir volume [Mm³], length T
  • discharge : turbine release [Mm³/stage], length T
  • spill : spillage [Mm³/stage], length T
  • production : energy [MWh/stage], length T
  • price : input price [NOK/MWh], length T
  • revenue_NOK : total revenue [NOK]
  • status : :OK or error symbol
HydroSimulation.monte_carlo — Method
monte_carlo(wvt, reservoir, plant, inflow_scenarios, prices;
            n_scenarios, resolution, v0, seed) → SimulationResult

Run Monte Carlo simulation: draw n_scenarios independent years of operation using the SDP water value policy.

Arguments

  • wvt : WaterValueTable
  • reservoir : HydroCore.Reservoir
  • plant : HydroCore.Plant
  • inflow_scenarios : Vector{PeriodicInflows} — scenario pool per stage
  • prices : Vector{Float64} — representative price per stage
  • n_scenarios : number of Monte Carlo draws (default 50)
  • resolution : PlanningResolution (default WEEKLY)
  • v0 : initial volume [Mm³] (default reservoir.initial_volume)
  • seed : random seed for reproducibility (default 0 = no seed)

Returns

SimulationResult with P10/P50/P90 trajectories.

HydroSimulation.shortage_fraction — Method
shortage_fraction(r::SimulationResult, v_min_threshold) → Float64

Fraction of stage-years where volume fell below v_min_threshold [Mm³].

HydroSimulation.simulate_year — Method
simulate_year(wvt, reservoir, plant, inflow_scenarios, prices; resolution, rng)
    → YearResult

Simulate one year of reservoir operation using the SDP water value table as operating policy.

Arguments

  • wvt : WaterValueTable from Phase 1 SDP
  • reservoir : HydroCore.Reservoir
  • plant : HydroCore.Plant
  • inflow_scenarios : Vector{PeriodicInflows} — one per stage
  • prices : Vector{Float64} — price per stage [NOK/MWh]
  • resolution : PlanningResolution (default WEEKLY)
  • v0 : initial volume [Mm³] (default reservoir.initial_volume)
  • rng : AbstractRNG for reproducible draws (default global RNG)

Returns

YearResult with volume, production, spill, and revenue per stage.

HydroSimulation.spill_fraction — Method
spill_fraction(vol_mat, reservoir) → Float64

Fraction of stage-years where the reservoir hit maximum volume (spill risk).

HydroSimulation.volume_p10 — Method
volume_p10(r::SimulationResult) → Vector{Float64}

10th-percentile reservoir volume trajectory across all simulated years.

HydroSimulation.volume_p90 — Method
volume_p90(r::SimulationResult) → Vector{Float64}

90th-percentile reservoir volume trajectory.