HydroCore API Reference

HydroCore.HydroCore — Module
HydroCore

Core data structures for production planning in hydropower-based systems.

Module structure

  • resolution.jl — PlanningResolution (time-step config), WEEKLY/DAILY/HOURLY
  • curves.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, ScenarioBundle
  • constraints.jl — FlowConstraint, VolumeConstraint, RampConstraint, MinEnvFlow
  • cascade.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 :: PlanningResolution

365 stages per year, one day (24 h) each. Appropriate for short-term LP and day-ahead market coupling.

HydroCore.HOURLY — Constant
HOURLY :: PlanningResolution

8 760 stages per year, one hour each. Used for intra-day dispatch models.

HydroCore.WEEKLY — Constant
WEEKLY :: PlanningResolution

52 stages per year, one week (168 h) each. Standard for long-term SDP and seasonal planning.

HydroCore.Cascade — Type
Cascade

Complete physical description of a hydropower system.

Fields

FieldDescription
idUnique identifier for this system/sub-system
nameHuman-readable name
nodesAll nodes, keyed by id
edgesAll edges, keyed by id
constraintsOperational constraints (ConstraintSet)
inflowsNatural 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) → Cascade

Construct 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
ConstraintSet

All operational constraints for a cascade, grouped by type.

Passed to the planning layer as a single object.

HydroCore.FlowConstraint — Type
FlowConstraint

Hard or regulatory bound on the discharge through a single edge (Plant or Waterway).

Fields

FieldUnitDescription
edge_id—ID of the Plant or Waterway being constrained
min_flowm³/sLower bound on discharge (≥ 0)
max_flowm³/sUpper bound on discharge
hard—true → infeasibility not allowed
HydroCore.HVCurve — Type
HVCurve

Maps 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 m
HydroCore.HydroEdge — Type
HydroEdge

Abstract supertype for all edges in the hydro network topology. Subtypes: Plant, Waterway.

HydroCore.HydroNode — Type
HydroNode

Abstract supertype for all nodes in the hydro network topology. Subtypes: Reservoir, Junction, Sink.

HydroCore.InflowSeries — Type
InflowSeries

A 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 <: HydroNode

A 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

FieldUnitDescription
id—Unique string identifier
name—Human-readable name
elevationm.a.s.lLocation elevation
HydroCore.MinEnvFlow — Type
MinEnvFlow

Minimum 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

FieldUnitDescription
edge_id—ID of the Waterway or Plant subject to constraint
min_flowm³/sMinimum 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
PQCurve

Maps 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 → scaled
HydroCore.PlanningHorizon — Type
PlanningHorizon

Maps 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

FieldDescription
start_dateDate — calendar date of stage 1
resolutionPlanningResolution — time step
n_stagesTotal 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
PlanningResolution

Time-step configuration for planning models.

Fields

FieldDescription
stepDates.Period — the duration of one planning stage
n_stagesTypical number of stages per planning year (e.g. 52)
labelHuman-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 year
HydroCore.Plant — Type
Plant <: HydroEdge

A 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

FieldUnitDescription
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_dischargem³/sMinimum discharge when running (technical min.)
max_dischargem³/sMaximum discharge (all units at full load)
pq_curve—Power–discharge curve at reference head
penstock_lossmFixed head loss in penstock at max discharge

Notes

  • A plant with num_units = 3 can have 0, 1, 2, or 3 units committed. Unit commitment adds integer constraints and is handled in the planning layer.
  • min_discharge applies per committed unit; the plant-level minimum is min_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.RampConstraint — Type
RampConstraint

Limits 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

FieldUnitDescription
plant_id—ID of the Plant
max_ramp_upm³/(s·h)Maximum increase in discharge per hour
max_ramp_dnm³/(s·h)Maximum decrease in discharge per hour
hard—true → infeasibility not allowed
HydroCore.Reservoir — Type
Reservoir <: HydroNode

A water storage element.

Fields

FieldUnitDescription
id—Unique string identifier
name—Human-readable name
min_volumeMm³Minimum allowed stored volume (LRV)
max_volumeMm³Maximum allowed stored volume (HRV)
initial_volumeMm³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_volume must lie in [minvolume, maxvolume].
HydroCore.ScenarioBundle — Type
ScenarioBundle

A 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

FieldDescription
nameScenario set name, e.g. "historical19602020"
scenariosVector of (scenariolabel, inflowdict) pairs
HydroCore.Sink — Type
Sink <: HydroNode

Terminal 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

FieldUnitDescription
id—Unique string identifier
name—Human-readable name
elevationm.a.s.lTail-water elevation
HydroCore.TimeSeries — Type
TimeSeries{T}

An ordered, regularly-spaced (or irregular) time series.

Fields

FieldDescription
timestampsVector of DateTime values (ascending)
valuesVector of values of type T
unitString 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)         # → 4
HydroCore.TimeSeries — Method
TimeSeries(start::DateTime, step::Period, values, unit="")

Construct a TimeSeries from a start time and a fixed step.

HydroCore.VolumeConstraint — Type
VolumeConstraint

Bounds 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

FieldUnitDescription
reservoir_id—ID of the Reservoir
min_volumeMm³Lower bound (constant or minimum of profile)
max_volumeMm³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 <: HydroEdge

A passive water conduit — no electricity generation.

Examples: tailrace tunnels, bypass channels, river reaches between reservoirs, spillways, environmental flow channels.

Fields

FieldUnitDescription
id—Unique string identifier
name—Human-readable name
from—Upstream node
to—Downstream node
kind—WaterwayKind (RiverReach, Tunnel, Spillway, Bypass)
min_flowm³/sMinimum flow (0 for passive spillways)
max_flowm³/sMaximum flow capacity
delay_hhWater travel time [hours]

Notes

  • delay_h > 0 introduces 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 = 0 and are activated by the reservoir reaching HRV in the optimisation model.
HydroCore.WaterwayKind — Type
WaterwayKind

Classifies the physical nature of a waterway, which matters for loss models and visualisation.

  • RiverReach : open-channel flow, significant routing delay possible
  • Tunnel : pressurised conduit, typically low losses, short delay
  • Spillway : overflow structure, activated only at HRV
  • Bypass : controlled diversion around a plant (e.g. environmental flow)
HydroCore.add_edge! — Method
add_edge!(c::Cascade, edge::HydroEdge) → Cascade

Add 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) → Cascade

Register an inflow series for a reservoir.

HydroCore.add_node! — Method
add_node!(c::Cascade, node::HydroNode) → Cascade

Add 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) → Int

ISO 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) → Int

Stage 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))  # → 2
HydroCore.elevation — Method
elevation(curve::HVCurve, volume::Real) → Float64

Return the water surface elevation [m.a.s.l] at the given stored volume [Mm³].

HydroCore.elevation_at — Method
elevation_at(r::Reservoir, volume::Real) → Float64

Return water surface elevation [m.a.s.l] at the given stored volume [Mm³].

HydroCore.horizon_years — Method
horizon_years(horizon) → Float64

Approximate 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) → Float64

Piecewise-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) → Bool

Check 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) → Float64

Conversion 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.0864
HydroCore.max_discharge — Method
max_discharge(curve::PQCurve) → Float64

Return the maximum discharge [m³/s] within the curve's valid range.

HydroCore.max_power — Method
max_power(plant::Plant) → Float64

Installed capacity [MW] at reference head (from PQ curve at max discharge).

HydroCore.min_flow_at — Method
min_flow_at(mef::MinEnvFlow, week::Int) → Float64

Return 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) → Float64

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

Return the unique identifier of any node.

HydroCore.outgoing_edges — Method
outgoing_edges(c::Cascade, node::HydroNode) → Vector{HydroEdge}

All edges leaving node.

HydroCore.power — Method
power(curve::PQCurve, Q::Real, H::Real) → Float64

Return 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) → Float64

Return 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.stage_date — Method
stage_date(horizon, t) → Date

Calendar 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) → Int

Map 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)    # → 75
HydroCore.step_hours — Method
step_hours(r::PlanningResolution) → Float64

Duration of one planning stage in hours.

step_hours(WEEKLY)  # → 168.0
step_hours(DAILY)   # →  24.0
step_hours(HOURLY)  # →   1.0
HydroCore.step_seconds — Method
step_seconds(r::PlanningResolution) → Float64

Duration 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.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) → Float64

Return 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.