Physical Topology: Nodes and Edges
Source:
HydroCore/src/nodes.jl,HydroCore/src/edges.jl,HydroCore/src/cascade.jl
The graph model
A hydropower system is naturally a directed graph:
- Nodes are places where water accumulates or is routed
- Edges are elements that move water from one node to another
[Reservoir A]──(Plant 1)──►[Reservoir B]──(Plant 2)──►[Sink]
│ │
(Spillway A) (Spillway B)
│ │
└──────────────────────────┘This is a standard data structure choice in power systems modelling. It means:
- Topology is explicit and queryable
- Adding new system configurations requires no new code — just new data
- Algorithms (LP formulation, water balance) can walk the graph generically
Nodes
Reservoir
The central element. Stores water between time steps.
struct Reservoir <: HydroNode
id::String
name::String
min_volume::Float64 # Mm³ (LRV - Lowest Regulated Level)
max_volume::Float64 # Mm³ (HRV - Highest Regulated Level)
initial_volume::Float64 # Mm³ (starting point for simulation)
hv_curve::HVCurve # volume → water surface elevation
endLRV / HRV: Norwegian hydropower reservoirs are regulated between two levels set by the water licence (konsesjon). The LRV protects the intake and ecological minimum. The HRV is the flood-safety ceiling.
The HV curve (head-volume) is the reservoir's bathymetry: how does the water surface elevation change as volume increases? This matters for computing net head across a plant.
Junction
A routing point with no storage. Water flowing in must immediately flow out.
struct Junction <: HydroNode
id::String
name::String
elevation::Float64 # m.a.s.l
endUsed for: river confluences, bifurcation points, shared tailrace tunnels.
In any feasible solution, the flow balance at a Junction is:
Σ(inflows) = Σ(outflows) (Kirchhoff's water law)Sink
A terminal node — water flowing in is gone from the model.
struct Sink <: HydroNode
id::String
name::String
elevation::Float64 # m.a.s.l (ocean = 0)
endEvery cascade has at least one Sink (the ocean, or the system boundary).
Edges
Plant
A hydropower generating station. Water flows in from the upstream node and out to the downstream node, and electricity is produced according to the PQCurve.
struct Plant <: HydroEdge
id::String
name::String
from::HydroNode # upstream (usually Reservoir)
to::HydroNode # downstream (Reservoir, Junction, or Sink)
num_units::Int # number of turbine-generator sets
min_discharge::Float64 # m³/s per unit, when running
max_discharge::Float64 # m³/s all units at full load
pq_curve::PQCurve
penstock_loss::Float64 # m head loss in penstock at full load
endUnit commitment: A plant with num_units = 3 can run 0, 1, 2, or 3 units. Running fewer units is sometimes necessary because each unit has a minimum discharge (below which vibration damages the turbine). The LP layer treats this as a continuous relaxation; the MIP layer adds binary on/off variables.
Penstock loss: The penstock (high-pressure pipe from reservoir to turbine) incurs friction losses. At the planning stage this is often modelled as a fixed deduction from gross head.
Waterway
A passive conduit. No electricity production.
struct Waterway <: HydroEdge
id::String
name::String
from::HydroNode
to::HydroNode
kind::WaterwayKind # RiverReach | Tunnel | Spillway | Bypass
min_flow::Float64 # m³/s
max_flow::Float64 # m³/s
delay_h::Float64 # hours (water travel time)
endFour kinds:
| Kind | Description | Typical use |
|---|---|---|
RiverReach | Open-channel river segment | Between reservoirs with no plant |
Tunnel | Pressurised underground conduit | Headrace/tailrace bypass |
Spillway | Overflow structure at HRV | Emergency/flood release |
Bypass | Controlled diversion | Environmental flow channel |
Routing delay: For weekly/seasonal models the delay is usually negligible. For hourly short-term models a delay of hours matters and must be tracked explicitly.
The Cascade
The Cascade struct is the single source of truth for the system topology.
struct Cascade
id::String
name::String
nodes::Dict{String, HydroNode} # all nodes, keyed by id
edges::Dict{String, HydroEdge} # all edges, keyed by id
constraints::ConstraintSet
inflows::Dict{String, InflowSeries}
endIt is not a class with methods. Instead, Julia's multiple dispatch means you call free functions on a Cascade:
reservoirs(c) # → Vector{Reservoir}
plants(c) # → Vector{Plant}
outgoing_edges(c, reservoir) # → Vector{HydroEdge}
topological_sort(c) # → nodes in upstream-first order
total_installed_capacity(c) # → MWThis is idiomatic Julia: functions are open for extension, whereas methods on a class are closed. A new package can add energy_content(c::Cascade) without modifying HydroCore.
Design decisions
Why Dict over Vector?
Nodes and edges are looked up by id constantly (by the optimisation layer, by constraints, by inflow registration). Dict{String, HydroNode} gives O(1) lookup. A Vector would require linear search or a separate index.
Why store direct node references in edges?
Plant.from holds the actual HydroNode object (not a String id). This means:
plant.from.id # works directly
plant.from isa Reservoir # dispatch works
upstream_reservoir(plant) # no cascade lookup neededThe alternative (storing only ids, looking up in Cascade) would require passing the Cascade everywhere. The current design is simpler for read-only queries.
Why immutable structs?
Julia performs best with immutable structs (struct, not mutable struct):
- Can be stack-allocated
- Compiler can optimise more aggressively
- No accidental mutation bugs
The state of the system (current reservoir volumes, current discharge) is a decision variable in the optimisation model — it does not live in the structs.
Example: building a two-reservoir cascade
using HydroCore
# Curves
hv_up = HVCurve([0.0, 300.0], [700.0, 800.0])
hv_dn = HVCurve([0.0, 80.0], [400.0, 410.0])
pq = PQCurve(reference_head=380.0,
discharges=[0.0, 60.0, 120.0],
powers =[0.0, 45.0, 82.0])
# Nodes
upper = Reservoir("R_UP", "Upper Reservoir", 20.0, 300.0, 200.0, hv_up)
lower = Reservoir("R_DN", "Lower Reservoir", 5.0, 80.0, 40.0, hv_dn)
sea = Sink("SEA", "Ocean")
# Edges
plant = Plant("P1", "Power Station", upper, lower,
num_units=2, min_discharge=8.0, max_discharge=120.0,
pq_curve=pq)
spill = Waterway("SP1", "Spillway", lower, sea, Spillway, 0.0, 800.0)
# Assemble
c = Cascade("DEMO", "Demo System")
add_node!(c, upper); add_node!(c, lower); add_node!(c, sea)
add_edge!(c, plant); add_edge!(c, spill)
println(c)
# Cascade: Demo System (DEMO)
# Nodes:
# 2 reservoir(s): R_UP, R_DN
# 0 junction(s)
# 1 sink(s)
# Edges:
# 1 plant(s): P1
# 1 waterway(s)
# Installed capacity : 82.0 MW
# Usable storage : 355.0 Mm³
# Inflow series : 0 reservoir(s) covered