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:
Inflow (tilsig): Natural water flowing into each reservoir from precipitation and snowmelt. Stochastic, highly seasonal, correlated across reservoirs.
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
endThe 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 hourThis 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")
endResampling
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
endThe 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) × Δtwhere 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}}}
endEach 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 farIn 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:
Minimal dependencies.
HydroCoreshould compile quickly and work anywhere. AddingDataFrameswould pull in ~20 transitive dependencies.Typed columns. DataFrames store columns as
Anyby 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.