WeeklyScheduling API Reference
WeeklyScheduling.WeeklyScheduling — Module
WeeklySchedulingSingle-reservoir, single-plant LP production scheduling.
Uses JuMP + HiGHS (open-source LP solver). Time resolution is configurable via PlanningResolution from HydroCore — the same model works at weekly, daily, or hourly granularity.
What this package does
Given a planning horizon of T stages, it solves:
max Σ_t price[t] × production[t] × Δt + end_value(v[T])subject to water balance, storage bounds, discharge limits, and a piecewise-linear PQ curve (concave LP approximation).
The end-value function is the boundary condition connecting this short-term LP to the long-term water values from WaterValues.
Quick start
using HydroCore, WaterValues, WeeklyScheduling
# 1. Build system (see HydroCore docs)
res = Reservoir(...)
plant = Plant(...)
# 2. Compute water value table (see WaterValues docs)
inflows = extract_periodic_inflows(series, WEEKLY)
wvt = solve_sdp(res, plant, inflows; price=400.0)
# 3. Schedule
inflow = fill(3.0, 52) # 3 Mm³/week constant
price = fill(400.0, 52) # 400 NOK/MWh constant
ev = WaterValueEndValue(wvt, 1)
result = optimize_schedule(res, plant, inflow, price, ev; resolution=WEEKLY)
println(result)
# → ScheduleResult: 52 stages, status=OPTIMAL, revenue=X MNOK, end_value=Y MNOKExports
EndValueFunction,WaterValueEndValue,ZeroEndValueadd_end_value_cuts!ScheduleResultoptimize_schedule
WeeklyScheduling.CascadeScheduleResult — Type
CascadeScheduleResultResult from the multi-reservoir cascade LP.
Reservoir columns follow the topological order returned by topological_sort(cascade) (upstream-first). Plant columns follow the order returned by plants(cascade).
Fields
| Field | Size | Unit | Description |
|---|---|---|---|
volume | T × K | Mm³ | End-of-stage volume per reservoir |
discharge | T × J | Mm³/stage | Turbine release per plant |
spill | T × K | Mm³/stage | Residual spill leaving system |
production | T | MWh/stage | Total production across all plants |
shadow_price | T × K | NOK/Mm³ | Dual of water balance (water value) |
revenue_NOK | scalar | NOK | Total operating revenue |
end_value_NOK | scalar | NOK | Total end-value across all reservoirs |
total_value_NOK | scalar | NOK | revenue_NOK + end_value_NOK |
reservoir_ids | K | — | Reservoir ids (column labels) |
plant_ids | J | — | Plant ids (column labels) |
status | Symbol | — | :OPTIMAL, :INFEASIBLE, :OTHER |
WeeklyScheduling.EndValueFunction — Type
EndValueFunctionAbstract type for end-of-horizon value functions. Concrete subtypes must implement add_end_value_cuts!(model, v_last, evf).
WeeklyScheduling.ScheduleResult — Type
ScheduleResultThe optimal schedule returned by the LP model.
All vectors have length T (number of planning stages).
Fields
| Field | Unit | Description |
|---|---|---|
volume | Mm³ | End-of-stage reservoir volume |
discharge | Mm³/stage | Turbine release per stage |
spill | Mm³/stage | Spillage (excess beyond v_max) |
production | MWh/stage | Energy produced per stage |
price | NOK/MWh | Input price vector (copy) |
revenue_NOK | NOK | Total revenue from production |
end_value_NOK | NOK | Value of water left at end of horizon |
total_value_NOK | NOK | revenue_NOK + end_value_NOK |
status | Symbol | :OPTIMAL, :INFEASIBLE, :OTHER |
Notes
dischargeis in Mm³/stage. Divide bym3s_to_Mm3_per_step(resolution)to convert to m³/s.productionis computed assum(prod_MW[t] * step_hours)per stage.
WeeklyScheduling.WaterValueEndValue — Type
WaterValueEndValueEnd-value function backed by a WaterValueTable from Phase 1 SDP.
Fields
table:WaterValueTablestage: which stage (row) of the table to use (e.g. the week after the planning horizon ends). Defaults to stage 1 (wrap-around).
WeeklyScheduling.ZeroEndValue — Type
ZeroEndValueEnd-of-horizon value = 0. Equivalent to draining all water by the end. Useful as a baseline or when no water value table is available.
WeeklyScheduling._add_cascade_end_value! — Method
_add_cascade_end_value!(model, v_last, evf, suffix) → VariableRefAdd an end-value variable end_val_<suffix> to model, bounded above by the piecewise-linear cuts from evf. Returns the variable reference.
WeeklyScheduling._cascade_zero_result — Method
_cascade_zero_result(T, K, J, res_ids, plant_ids) → CascadeScheduleResultReturn an all-zeros infeasible result of the correct shape.
WeeklyScheduling.add_end_value_cuts! — Function
add_end_value_cuts!(model, v_last, evf)Add the end-value variable and its upper-bound cuts to the JuMP model.
v_last: the JuMP variable for the reservoir volume at the last stageevf: theEndValueFunction
After this call, model[:end_val] holds the end-value variable, which is bounded above by the piecewise-linear approximation of evf.
WeeklyScheduling.optimize_cascade — Function
optimize_cascade(cascade, inflows, price, end_value_fns;
resolution, v0, silent) → CascadeScheduleResultSolve the multi-reservoir cascade LP scheduling problem.
Arguments
cascade:HydroCore.Cascade— full system topologyinflows:Dict{String, Vector{Float64}}— natural inflow per reservoir[Mm³/stage], keyed by reservoir id. Reservoirs with no entry receive zero natural inflow.price:Vector{Float64}— electricity price[NOK/MWh], length Tend_value_fns:Dict{String, EndValueFunction}— per-reservoir end-of-horizon value function, keyed by reservoir id. Reservoirs with no entry useZeroEndValue.resolution:PlanningResolution(defaultWEEKLY)v0:Dict{String, Float64}— initial reservoir volumes[Mm³]. Reservoirs with no entry usereservoir.initial_volume.silent: suppress solver output (defaulttrue)
Returns
CascadeScheduleResult with per-reservoir volumes, per-plant discharges, spill, production, shadow prices (water values), and revenue.
Shadow prices
result.shadow_price[t, k] is the dual variable of the water balance constraint for reservoir k at stage t. For a maximisation LP, this is the marginal value of one extra Mm³ of natural inflow — i.e. the local water value [NOK/Mm³]. These are the β⃗ components used in SDDP Benders cuts.
Notes
- Only
Reservoirnodes appear in results.JunctionandSinknodes are handled transparently via the water balance routing. - Head is fixed at the PQ-curve reference head (variable head correction is a known limitation; see docs/04-short-term-planning/02-cascade-lp.md).
WeeklyScheduling.optimize_schedule — Method
optimize_schedule(reservoir, plant, inflow, price, end_value_fn;
resolution, v0, silent) → ScheduleResultSolve the single-reservoir, single-plant LP scheduling problem.
Arguments
reservoir:HydroCore.Reservoirplant:HydroCore.Plant(PQ curve + max discharge)inflow:Vector{Float64}— inflow[Mm³/stage], length Tprice:Vector{Float64}— electricity price[NOK/MWh], length Tend_value_fn:EndValueFunction(e.g.WaterValueEndValueorZeroEndValue)resolution:PlanningResolution(defaultWEEKLY)v0: initial reservoir volume[Mm³](default:reservoir.initial_volume)silent: suppress solver output (defaulttrue)
Returns
ScheduleResult with volume, discharge, production, spill, revenue per stage.
Example
inflow = fill(3.0, 52) # 3 Mm³/week constant
price = fill(400.0, 52) # 400 NOK/MWh constant
ev = WaterValueEndValue(wvt, 1)
result = optimize_schedule(reservoir, plant, inflow, price, ev;
resolution=WEEKLY, v0=75.0)
sum(result.production) # total MWh over horizon