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
end

LRV / 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
end

Used 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)
end

Every 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
end

Unit 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)
end

Four kinds:

KindDescriptionTypical use
RiverReachOpen-channel river segmentBetween reservoirs with no plant
TunnelPressurised underground conduitHeadrace/tailrace bypass
SpillwayOverflow structure at HRVEmergency/flood release
BypassControlled diversionEnvironmental 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}
end

It 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)   # → MW

This 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 needed

The 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