Time Series and Scenarios

Source: HydroCore/src/timeseries.jl


The role of time series in hydropower planning

Two kinds of time-varying data dominate the planning problem:

  1. Inflow (tilsig): Natural water flowing into each reservoir from precipitation and snowmelt. Stochastic, highly seasonal, correlated across reservoirs.

  2. Electricity price: The spot price at which generation can be sold. Also stochastic, correlated with inflow (wet years → low prices), and seasonal.

Both are needed at every level of the planning hierarchy. At the long-term level they appear as historical scenarios or statistical distributions. At the short-term level they appear as forecasts.


TimeSeries{T} — the generic container

struct TimeSeries{T}
    timestamps::Vector{DateTime}
    values::Vector{T}
    unit::String
end

The type parameter T means the same struct handles:

TimeSeries{Float64}   # continuous measurements: inflow, price, volume
TimeSeries{Bool}      # availability flags: is the plant available?
TimeSeries{Int}       # discrete states: number of units committed
TimeSeries{Vector{Float64}}  # multi-dimensional: price per area per hour

This is Julia's parametric types in action — a single, tested implementation that works for all element types, with full type safety.

Construction

# From explicit timestamps
ts = TimeSeries(
    [DateTime(2020,1,1), DateTime(2020,1,8), DateTime(2020,1,15)],
    [42.3, 38.1, 51.7],
    "m³/s"
)

# From start + step (more convenient)
ts = TimeSeries(DateTime(2020,1,1), Week(1), [42.3, 38.1, 51.7], "m³/s")

Indexing

ts[1]         # → (DateTime("2020-01-01"), 42.3)
length(ts)    # → 3
time_span(ts) # → (DateTime("2020-01-01"), DateTime("2020-01-15"))

for (t, v) in ts   # iterable
    println("$t: $v m³/s")
end

Resampling

Convert from finer to coarser resolution:

hourly = TimeSeries(DateTime(2020,1,1), Hour(1), rand(24), "m³/s")
daily  = resample(hourly, Hour(24))          # sums 24 values → 1
daily_mean = resample(hourly, Hour(24); agg=mean)

Resampling is needed when combining data at different resolutions — for example, aggregating hourly inflow to weekly totals for the seasonal LP.


InflowSeries — inflow tied to a reservoir

struct InflowSeries
    reservoir_id::String
    series::TimeSeries{Float64}   # m³/s
end

The reservoir_id links the series to the physical model. When building a Cascade, you register inflow series:

inflow = InflowSeries(
    reservoir_id = "R_UP",
    timestamps   = [DateTime(2020,1,1), DateTime(2020,1,8)],
    values       = [55.0, 48.0]     # m³/s average over the week
)
add_inflow!(cascade, inflow)

Converting flow to volume

The water balance equation works in volume [Mm³], not flow [m³/s]. Use to_volume to convert:

# Weekly inflow in Mm³:  Q [m³/s] × 604800 [s/week] / 1e6
vol = to_volume(inflow, Week(1))
vol[1][2]   # ≈ 55.0 × 604800 / 1e6 ≈ 33.26 Mm³

This is the inflow term in the reservoir water balance:

v(t+1) = v(t) + inflow_vol(t) - release_vol(t) - spill_vol(t)

PriceSeries — electricity spot prices

struct PriceSeries
    currency::String
    series::TimeSeries{Float64}   # NOK/MWh or EUR/MWh
end

prices = PriceSeries(
    currency   = "NOK",
    timestamps = [DateTime(2020,1,1), DateTime(2020,1,8)],
    values     = [312.5, 287.0]
)

In the objective function of the LP:

Maximise  Σ_t  price(t) × production(t) × Δt

where price(t) comes from the PriceSeries and Δt is the time step duration in hours.


ScenarioBundle — scenarios for SDP

Stochastic Dynamic Programming requires a set of historical or synthetic inflow scenarios to compute expected future values.

struct ScenarioBundle
    name::String
    scenarios::Vector{Pair{String, Dict{String, InflowSeries}}}
end

Each scenario is a Dict from reservoir_id to InflowSeries — one inflow trajectory per reservoir per scenario.

bundle = ScenarioBundle("historical_1960_2020")

# Add one scenario (one historical year)
add_scenario!(bundle, "1990",
    Dict("R_UP" => InflowSeries(reservoir_id="R_UP", ...),
         "R_DN" => InflowSeries(reservoir_id="R_DN", ...))
)

length(bundle)   # → 1 so far

In Phase 1 (water value computation), the SDP will iterate over all scenarios in a ScenarioBundle to build the expected value of future operation.


Why not use DataFrames?

DataFrames.jl is the standard Julia tabular data library. We deliberately avoid it in HydroCore for two reasons:

  1. Minimal dependencies. HydroCore should compile quickly and work anywhere. Adding DataFrames would pull in ~20 transitive dependencies.

  2. Typed columns. DataFrames store columns as Any by default, losing type information. TimeSeries{T} keeps the element type, enabling the compiler to generate efficient specialised code.

A future HydroIO package could handle reading CSV/Parquet/JSON inflow data and producing InflowSeries / ScenarioBundle objects — cleanly separated from the core model.