HydroCore API Reference
HydroCore.HydroCore — Module
HydroCoreCore data structures for production planning in hydropower-based systems.
Module structure
resolution.jl— PlanningResolution (time-step config), WEEKLY/DAILY/HOURLYcurves.jl— HVCurve (elevation–volume), PQCurve (power–discharge)nodes.jl— Reservoir, Junction, Sink (topology nodes)edges.jl— Plant, Waterway (topology edges)timeseries.jl— TimeSeries{T}, InflowSeries, PriceSeries, ScenarioBundleconstraints.jl— FlowConstraint, VolumeConstraint, RampConstraint, MinEnvFlowcascade.jl— Cascade (the full system graph)
Typical usage
using HydroCore
# 1. Build curves
hv = HVCurve([0.0, 100.0, 200.0], [400.0, 450.0, 480.0])
pq = PQCurve(reference_head=80.0,
discharges=[0.0, 50.0, 100.0, 150.0],
powers =[0.0, 30.0, 55.0, 72.0])
# 2. Build nodes
res_upper = Reservoir("R1", "Upper Lake", 10.0, 200.0, 120.0, hv)
res_lower = Reservoir("R2", "Lower Pond", 0.0, 30.0, 15.0,
HVCurve([0.0, 30.0], [300.0, 310.0]))
sea = Sink("SEA", "Ocean")
# 3. Build edges
plant = Plant("P1", "Main Station", res_upper, res_lower,
num_units=2, min_discharge=10.0, max_discharge=150.0,
pq_curve=pq)
spill = Waterway("SP1", "Spillway", res_upper, res_lower,
Spillway, 0.0, 500.0)
# 4. Assemble cascade
c = Cascade("ALTA", "Alta System")
add_node!(c, res_upper); add_node!(c, res_lower); add_node!(c, sea)
add_edge!(c, plant); add_edge!(c, spill)
println(c)HydroCore.DAILY — Constant
DAILY :: PlanningResolution365 stages per year, one day (24 h) each. Appropriate for short-term LP and day-ahead market coupling.
HydroCore.HOURLY — Constant
HOURLY :: PlanningResolution8 760 stages per year, one hour each. Used for intra-day dispatch models.
HydroCore.WEEKLY — Constant
WEEKLY :: PlanningResolution52 stages per year, one week (168 h) each. Standard for long-term SDP and seasonal planning.
HydroCore.Cascade — Type
CascadeComplete physical description of a hydropower system.
Fields
| Field | Description |
|---|---|
id | Unique identifier for this system/sub-system |
name | Human-readable name |
nodes | All nodes, keyed by id |
edges | All edges, keyed by id |
constraints | Operational constraints (ConstraintSet) |
inflows | Natural inflow series, keyed by reservoir_id |
Design note
Maps (Dict) are used instead of Vectors so that lookup by id is O(1). The topological order is not stored explicitly — use topological_sort(cascade) when needed (e.g., for sequential water balance computation).
HydroCore.Cascade — Method
Cascade(id, name) → CascadeConstruct an empty cascade. Use add_node!, add_edge!, etc. to populate it.
Note: Cascade itself is immutable, but its Dict fields are mutable collections, so we can add elements after construction. If true immutability is required, use a builder pattern (future work).
HydroCore.ConstraintSet — Type
ConstraintSetAll operational constraints for a cascade, grouped by type.
Passed to the planning layer as a single object.
HydroCore.FlowConstraint — Type
FlowConstraintHard or regulatory bound on the discharge through a single edge (Plant or Waterway).
Fields
| Field | Unit | Description |
|---|---|---|
edge_id | — | ID of the Plant or Waterway being constrained |
min_flow | m³/s | Lower bound on discharge (≥ 0) |
max_flow | m³/s | Upper bound on discharge |
hard | — | true → infeasibility not allowed |
HydroCore.HVCurve — Type
HVCurveMaps stored volume [Mm³] to water surface elevation [m.a.s.l].
Constructed from bathymetric survey data. Interpolation is piecewise-linear.
Example
hv = HVCurve([0.0, 50.0, 100.0, 150.0], [800.0, 840.0, 870.0, 890.0])
elevation(hv, 75.0) # → ~855 mHydroCore.HydroEdge — Type
HydroEdgeAbstract supertype for all edges in the hydro network topology. Subtypes: Plant, Waterway.
HydroCore.HydroNode — Type
HydroNodeAbstract supertype for all nodes in the hydro network topology. Subtypes: Reservoir, Junction, Sink.
HydroCore.InflowSeries — Type
InflowSeriesA TimeSeries{Float64} of natural inflow [m³/s] associated with a reservoir.
Example
inflow = InflowSeries(
reservoir_id = "RES_A",
timestamps = [DateTime(2020,1,1), DateTime(2020,1,8)],
values = [45.2, 38.7]
)HydroCore.Junction — Type
Junction <: HydroNodeA flow-routing node with no storage.
Used to model river confluences, bifurcations, or any point where multiple waterways or plants meet. In any feasible state, the sum of inflows equals the sum of outflows (Kirchhoff's water law).
Fields
| Field | Unit | Description |
|---|---|---|
id | — | Unique string identifier |
name | — | Human-readable name |
elevation | m.a.s.l | Location elevation |
HydroCore.MinEnvFlow — Type
MinEnvFlowMinimum environmental (ecological) flow requirement on a waterway or river reach.
This is a regulatory constraint from the water licence (konsesjonskrav). It ensures a minimum flow in the natural river reach downstream of a diversion, protecting the aquatic ecosystem.
Fields
| Field | Unit | Description |
|---|---|---|
edge_id | — | ID of the Waterway or Plant subject to constraint |
min_flow | m³/s | Minimum required flow at all times |
seasonal | — | Whether min flow varies by season |
profile | — | Optional (weeknumber, minflow) pairs |
Example
# Constant 2 m³/s year-round
MinEnvFlow("bypass_A", min_flow=2.0)
# Seasonal: 5 m³/s in summer (weeks 20-40), 1.5 m³/s otherwise
MinEnvFlow("bypass_A", min_flow=1.5, seasonal=true,
profile=[(20, 5.0), (41, 1.5)])HydroCore.PQCurve — Type
PQCurveMaps turbine discharge Q [m³/s] to generated power P [MW] at a reference net head reference_head [m].
The curve is built from efficiency testing or manufacturer data. At other heads the power can be approximated by scaling:
P(Q, H) ≈ P_ref(Q) × (H / H_ref)which is a first-order correction. A full Hill-chart model can replace this.
Example
pq = PQCurve(
reference_head = 350.0,
discharges = [0.0, 20.0, 40.0, 60.0, 80.0],
powers = [0.0, 12.0, 26.0, 38.0, 48.0]
)
power(pq, 50.0) # at reference head → ~32 MW
power(pq, 50.0, 320.0) # at 320 m head → scaledHydroCore.PlanningHorizon — Type
PlanningHorizonMaps planning stages (1, 2, …, T) to calendar dates. This is the bridge between the SDDP algorithm (which sees abstract stages) and the real-world calendar (which determines inflow seasonality, prognosis alignment, etc.).
Fields
| Field | Description |
|---|---|
start_date | Date — calendar date of stage 1 |
resolution | PlanningResolution — time step |
n_stages | Total number of stages in the horizon |
Example
horizon = PlanningHorizon(Date(2026, 3, 22), WEEKLY, 260) # 5 years
stage_date(horizon, 1) # → Date(2026, 3, 22)
stage_date(horizon, 53) # → Date(2027, 3, 21)
date_stage(horizon, Date(2026, 6, 14)) # → 13
calendar_week(horizon, 1) # → 12 (ISO week of March 22)The SDDP solver never sees PlanningHorizon directly — it receives n_stages and a resolution. The horizon is used by:
- Scenario construction (aligning weather-year data to calendar weeks)
- Warm-start stage shifting (computing shift from date differences)
- Output labelling (stage → date column in CSVs)
HydroCore.PlanningHorizon — Method
PlanningHorizon(; start_date, resolution=WEEKLY, n_years=5)Convenience constructor: compute n_stages from number of years.
PlanningHorizon(start_date=Date(2026, 3, 22), resolution=WEEKLY, n_years=5)
# → 260 stages (5 × 52)HydroCore.PlanningResolution — Type
PlanningResolutionTime-step configuration for planning models.
Fields
| Field | Description |
|---|---|
step | Dates.Period — the duration of one planning stage |
n_stages | Typical number of stages per planning year (e.g. 52) |
label | Human-readable name, e.g. "weekly", "daily" |
Predefined constants
Use WEEKLY, DAILY, or HOURLY for the common cases, or construct your own:
const MY_RES = PlanningResolution(Hour(3), 2920, "3-hourly")Key derived quantities
step_hours(WEEKLY) # → 168.0
step_seconds(DAILY) # → 86400.0
m3s_to_Mm3_per_step(WEEKLY) # → 0.6048 (m³/s → Mm³/week)
stage_index(DateTime(2024,6,1), WEEKLY) # → week number within yearHydroCore.Plant — Type
Plant <: HydroEdgeA hydropower generating station.
Water flows from from (upper reservoir or junction) through the turbines to to (lower reservoir, junction, or sink), producing electricity according to the pq_curve.
Fields
| Field | Unit | Description |
|---|---|---|
id | — | Unique string identifier |
name | — | Human-readable name |
from | — | Upstream node (Reservoir or Junction) |
to | — | Downstream node (Reservoir, Junction, or Sink) |
num_units | — | Number of generating units (turbine-generators) |
min_discharge | m³/s | Minimum discharge when running (technical min.) |
max_discharge | m³/s | Maximum discharge (all units at full load) |
pq_curve | — | Power–discharge curve at reference head |
penstock_loss | m | Fixed head loss in penstock at max discharge |
Notes
- A plant with
num_units = 3can have 0, 1, 2, or 3 units committed. Unit commitment adds integer constraints and is handled in the planning layer. min_dischargeapplies per committed unit; the plant-level minimum ismin_discharge(at least one unit running). Zero discharge means plant off.- Head loss is modelled simply as a constant fraction; more detailed models (Darcy–Weisbach) can be substituted later.
HydroCore.Plant — Method
Plant(id, name, from, to; num_units, min_discharge, max_discharge, pq_curve, penstock_loss=0.0)Keyword-argument convenience constructor. Prefer this form when constructing a Plant directly — it is more readable and self-documenting.
p = Plant("P1", "Station Alpha", r_up, r_dn;
num_units=2, min_discharge=5.0, max_discharge=100.0,
pq_curve=pq, penstock_loss=5.0)HydroCore.PriceSeries — Type
PriceSeriesSpot electricity prices [NOK/MWh or EUR/MWh].
HydroCore.RampConstraint — Type
RampConstraintLimits the rate of change of discharge [m³/s per hour] for a Plant.
Rapid ramping can cause physical damage (pressure surges, erosion) and ecological harm (stranding of aquatic organisms in the downstream reach).
Norwegian water licences often include ramp-rate limits.
Fields
| Field | Unit | Description |
|---|---|---|
plant_id | — | ID of the Plant |
max_ramp_up | m³/(s·h) | Maximum increase in discharge per hour |
max_ramp_dn | m³/(s·h) | Maximum decrease in discharge per hour |
hard | — | true → infeasibility not allowed |
HydroCore.Reservoir — Type
Reservoir <: HydroNodeA water storage element.
Fields
| Field | Unit | Description |
|---|---|---|
id | — | Unique string identifier |
name | — | Human-readable name |
min_volume | Mm³ | Minimum allowed stored volume (LRV) |
max_volume | Mm³ | Maximum allowed stored volume (HRV) |
initial_volume | Mm³ | Starting volume for simulation/planning |
hv_curve | — | Elevation–volume relationship |
Notes
- LRV (Lowest Regulated Level): ecological and structural lower bound.
- HRV (Highest Regulated Level): flood-safety upper bound.
initial_volumemust lie in [minvolume, maxvolume].
HydroCore.ScenarioBundle — Type
ScenarioBundleA named collection of inflow scenarios for a set of reservoirs. Each scenario is a Dict{String, InflowSeries} keyed by reservoir_id.
Used as input to Stochastic Dynamic Programming (Phase 1).
Fields
| Field | Description |
|---|---|
name | Scenario set name, e.g. "historical19602020" |
scenarios | Vector of (scenariolabel, inflowdict) pairs |
HydroCore.Sink — Type
Sink <: HydroNodeTerminal boundary node — water flowing into a Sink leaves the modelled system.
Typically represents the ocean, a large downstream river, or the system boundary. A cascade always has at least one Sink.
Fields
| Field | Unit | Description |
|---|---|---|
id | — | Unique string identifier |
name | — | Human-readable name |
elevation | m.a.s.l | Tail-water elevation |
HydroCore.TimeSeries — Type
TimeSeries{T}An ordered, regularly-spaced (or irregular) time series.
Fields
| Field | Description |
|---|---|
timestamps | Vector of DateTime values (ascending) |
values | Vector of values of type T |
unit | String label for the value unit |
Example
ts = TimeSeries(
DateTime(2020,1,1) .+ Hour.(0:3),
[10.2, 11.4, 9.8, 10.0],
"m³/s"
)
ts[2] # → (DateTime("2020-01-01T01:00:00"), 11.4)
length(ts) # → 4HydroCore.TimeSeries — Method
TimeSeries(start::DateTime, step::Period, values, unit="")Construct a TimeSeries from a start time and a fixed step.
HydroCore.VolumeConstraint — Type
VolumeConstraintBounds on the stored volume in a reservoir.
Can be constant (time_varying = false) or piecewise-constant over time (time_varying = true, with profile providing the bounds per week/day).
A time-varying constraint is common for seasonal flood-control regulations (e.g. "reservoir must be at most 60% full before spring flood season").
Fields
| Field | Unit | Description |
|---|---|---|
reservoir_id | — | ID of the Reservoir |
min_volume | Mm³ | Lower bound (constant or minimum of profile) |
max_volume | Mm³ | Upper bound (constant or maximum of profile) |
time_varying | — | Whether profile is used |
profile | — | Optional Vector of (DateTime, min, max) tuples |
hard | — | true → infeasibility not allowed |
HydroCore.Waterway — Type
Waterway <: HydroEdgeA passive water conduit — no electricity generation.
Examples: tailrace tunnels, bypass channels, river reaches between reservoirs, spillways, environmental flow channels.
Fields
| Field | Unit | Description |
|---|---|---|
id | — | Unique string identifier |
name | — | Human-readable name |
from | — | Upstream node |
to | — | Downstream node |
kind | — | WaterwayKind (RiverReach, Tunnel, Spillway, Bypass) |
min_flow | m³/s | Minimum flow (0 for passive spillways) |
max_flow | m³/s | Maximum flow capacity |
delay_h | h | Water travel time [hours] |
Notes
delay_h > 0introduces a routing lag: water released at time t arrives at the downstream node at time t + delay_h. In weekly models this is often rounded to whole time steps.- Spillways typically have
min_flow = 0and are activated by the reservoir reaching HRV in the optimisation model.
HydroCore.WaterwayKind — Type
WaterwayKindClassifies the physical nature of a waterway, which matters for loss models and visualisation.
RiverReach: open-channel flow, significant routing delay possibleTunnel: pressurised conduit, typically low losses, short delaySpillway: overflow structure, activated only at HRVBypass: controlled diversion around a plant (e.g. environmental flow)
HydroCore.add_edge! — Method
add_edge!(c::Cascade, edge::HydroEdge) → CascadeAdd an edge to the cascade. Validates that the from and to nodes are already registered in the cascade.
HydroCore.add_inflow! — Method
add_inflow!(c::Cascade, inflow::InflowSeries) → CascadeRegister an inflow series for a reservoir.
HydroCore.add_node! — Method
add_node!(c::Cascade, node::HydroNode) → CascadeAdd a node to the cascade. Errors if the id already exists.
HydroCore.bounds_at — Method
bounds_at(vc::VolumeConstraint, t::DateTime) → (Float64, Float64)Return (min_volume, max_volume) active at time t. For time-varying constraints, returns the most recent bound before or at t.
HydroCore.calendar_week — Method
calendar_week(horizon, t) → IntISO week number (1–53) for stage t.
Useful for indexing into seasonal inflow statistics that are stored by calendar week.
h = PlanningHorizon(Date(2026, 3, 22), WEEKLY, 52)
calendar_week(h, 1) # → 12 (ISO week of March 22, 2026)HydroCore.date_stage — Method
date_stage(horizon, d) → IntStage index (1-based) containing date d. Returns the stage whose start date is ≤ d, or errors if d is outside the horizon.
h = PlanningHorizon(Date(2026, 1, 5), WEEKLY, 52)
date_stage(h, Date(2026, 1, 5)) # → 1
date_stage(h, Date(2026, 1, 11)) # → 1 (still within week 1)
date_stage(h, Date(2026, 1, 12)) # → 2HydroCore.discharge_range — Method
discharge_range(curve::PQCurve) → (min_Q, max_Q)HydroCore.downstream — Method
downstream(e::HydroEdge) → HydroNodeHydroCore.downstream_reservoir — Method
downstream_reservoir(plant::Plant) → Union{Reservoir, Nothing}HydroCore.edge_id — Method
edge_id(e::HydroEdge) → StringHydroCore.elevation — Method
elevation(curve::HVCurve, volume::Real) → Float64Return the water surface elevation [m.a.s.l] at the given stored volume [Mm³].
HydroCore.elevation_at — Method
elevation_at(r::Reservoir, volume::Real) → Float64Return water surface elevation [m.a.s.l] at the given stored volume [Mm³].
HydroCore.end_date — Method
end_date(horizon) → DateCalendar date of the last stage.
HydroCore.horizon_years — Method
horizon_years(horizon) → Float64Approximate number of years covered by the horizon.
HydroCore.incoming_edges — Method
incoming_edges(c::Cascade, node::HydroNode) → Vector{HydroEdge}All edges arriving at node.
HydroCore.interp1 — Method
interp1(xs, ys, x) → Float64Piecewise-linear interpolation. xs must be strictly increasing. Values outside the range are clamped to the boundary value.
HydroCore.is_buffer — Method
is_buffer(c::Cascade, reservoir_id::String) → BoolCheck if a reservoir is marked as a buffer (passthrough) reservoir. Buffer reservoirs have very small storage and should have their volumes fixed at min_volume in the LP to avoid extreme shadow prices.
HydroCore.junctions — Method
junctions(c::Cascade) → Vector{Junction}Return all junctions in the cascade.
HydroCore.m3s_to_Mm3_per_step — Method
m3s_to_Mm3_per_step(r::PlanningResolution) → Float64Conversion factor: flow [m³/s] → volume [Mm³] per stage.
Multiply a constant m³/s flow rate by this factor to get the volume [Mm³] that passes in one stage.
m3s_to_Mm3_per_step(WEEKLY) # → 168 × 3600 × 1e-6 = 0.6048
m3s_to_Mm3_per_step(DAILY) # → 24 × 3600 × 1e-6 = 0.0864HydroCore.max_discharge — Method
max_discharge(curve::PQCurve) → Float64Return the maximum discharge [m³/s] within the curve's valid range.
HydroCore.max_power — Method
max_power(plant::Plant) → Float64Installed capacity [MW] at reference head (from PQ curve at max discharge).
HydroCore.min_flow_at — Method
min_flow_at(mef::MinEnvFlow, week::Int) → Float64Return the minimum environmental flow [m³/s] for the given ISO week number.
HydroCore.net_head — Method
net_head(plant::Plant, upper_elev::Real, lower_elev::Real) → Float64Compute net head [m] given upstream and downstream water surface elevations. Subtracts a simple penstock loss scaled linearly with reference head.
HydroCore.node_id — Method
node_id(n::HydroNode) → StringReturn the unique identifier of any node.
HydroCore.node_name — Method
node_name(n::HydroNode) → StringHydroCore.outgoing_edges — Method
outgoing_edges(c::Cascade, node::HydroNode) → Vector{HydroEdge}All edges leaving node.
HydroCore.plants — Method
plants(c::Cascade) → Vector{Plant}HydroCore.power — Method
power(curve::PQCurve, Q::Real, H::Real) → Float64Return generated power [MW] at discharge Q [m³/s] and net head H [m]. Uses a linear head-scaling approximation: P(Q,H) ≈ Pref(Q) × H/Href.
HydroCore.power — Method
power(curve::PQCurve, Q::Real) → Float64Return generated power [MW] at discharge Q [m³/s] using the reference head.
HydroCore.resample — Method
resample(ts::TimeSeries{Float64}, new_step::Period; agg=sum) → TimeSeries{Float64}Aggregate a time series to a coarser resolution. agg is applied to all values within each new time bucket (default: sum). Useful for converting hourly inflow [m³/s] to weekly totals [Mm³].
HydroCore.reservoirs — Method
reservoirs(c::Cascade) → Vector{Reservoir}Return all reservoirs in the cascade.
HydroCore.sinks — Method
sinks(c::Cascade) → Vector{Sink}HydroCore.stage_date — Method
stage_date(horizon, t) → DateCalendar date of stage t (1-based).
h = PlanningHorizon(Date(2026, 1, 5), WEEKLY, 52)
stage_date(h, 1) # → Date(2026, 1, 5)
stage_date(h, 2) # → Date(2026, 1, 12)
stage_date(h, 52) # → Date(2026, 12, 28)HydroCore.stage_index — Method
stage_index(dt::DateTime, r::PlanningResolution) → IntMap a DateTime to a stage index (1-based) within its calendar year, using the resolution's time step.
Stage 1 starts at January 1 00:00:00. Stages are contiguous and non-overlapping. Values are clamped to [1, r.n_stages].
Examples
stage_index(DateTime(2024, 1, 1), WEEKLY) # → 1
stage_index(DateTime(2024, 1, 8), WEEKLY) # → 2
stage_index(DateTime(2024, 12, 28), WEEKLY) # → 52
stage_index(DateTime(2024, 1, 1), DAILY) # → 1
stage_index(DateTime(2024, 3, 15), DAILY) # → 75HydroCore.step_hours — Method
step_hours(r::PlanningResolution) → Float64Duration of one planning stage in hours.
step_hours(WEEKLY) # → 168.0
step_hours(DAILY) # → 24.0
step_hours(HOURLY) # → 1.0HydroCore.step_seconds — Method
step_seconds(r::PlanningResolution) → Float64Duration of one planning stage in seconds.
HydroCore.time_span — Method
time_span(ts::TimeSeries) → (DateTime, DateTime)Return (first timestamp, last timestamp).
HydroCore.to_volume — Method
to_volume(s::InflowSeries, step::Period) → TimeSeries{Float64}Convert inflow [m³/s] to volume [Mm³] per time step by multiplying by the step duration in seconds and dividing by 1e6.
HydroCore.topological_sort — Method
topological_sort(c::Cascade) → Vector{HydroNode}Return nodes in topological order (upstream first). Useful for sequential water balance calculations. Throws an error if the graph contains a cycle.
HydroCore.total_installed_capacity — Method
total_installed_capacity(c::Cascade) → Float64Sum of max_power over all plants [MW].
HydroCore.total_usable_volume — Method
total_usable_volume(c::Cascade) → Float64Sum of usable storage across all reservoirs [Mm³].
HydroCore.upstream — Method
upstream(e::HydroEdge) → HydroNodeHydroCore.upstream_reservoir — Method
upstream_reservoir(plant::Plant) → Union{Reservoir, Nothing}Return the upstream Reservoir for a Plant, or nothing if the upstream node is a Junction.
HydroCore.usable_volume — Method
usable_volume(r::Reservoir) → Float64Return the usable storage capacity [Mm³]: max_volume - min_volume.
HydroCore.volume_range — Method
volume_range(curve::HVCurve) → (min_vol, max_vol)Return the volume range covered by the curve.
HydroCore.waterways — Method
waterways(c::Cascade) → Vector{Waterway}