WeeklyScheduling API Reference

WeeklyScheduling.WeeklyScheduling — Module
WeeklyScheduling

Single-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 MNOK

Exports

  • EndValueFunction, WaterValueEndValue, ZeroEndValue
  • add_end_value_cuts!
  • ScheduleResult
  • optimize_schedule
WeeklyScheduling.CascadeScheduleResult — Type
CascadeScheduleResult

Result 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

FieldSizeUnitDescription
volumeT × KMm³End-of-stage volume per reservoir
dischargeT × JMm³/stageTurbine release per plant
spillT × KMm³/stageResidual spill leaving system
productionTMWh/stageTotal production across all plants
shadow_priceT × KNOK/Mm³Dual of water balance (water value)
revenue_NOKscalarNOKTotal operating revenue
end_value_NOKscalarNOKTotal end-value across all reservoirs
total_value_NOKscalarNOKrevenue_NOK + end_value_NOK
reservoir_idsK—Reservoir ids (column labels)
plant_idsJ—Plant ids (column labels)
statusSymbol—:OPTIMAL, :INFEASIBLE, :OTHER
WeeklyScheduling.EndValueFunction — Type
EndValueFunction

Abstract type for end-of-horizon value functions. Concrete subtypes must implement add_end_value_cuts!(model, v_last, evf).

WeeklyScheduling.ScheduleResult — Type
ScheduleResult

The optimal schedule returned by the LP model.

All vectors have length T (number of planning stages).

Fields

FieldUnitDescription
volumeMm³End-of-stage reservoir volume
dischargeMm³/stageTurbine release per stage
spillMm³/stageSpillage (excess beyond v_max)
productionMWh/stageEnergy produced per stage
priceNOK/MWhInput price vector (copy)
revenue_NOKNOKTotal revenue from production
end_value_NOKNOKValue of water left at end of horizon
total_value_NOKNOKrevenue_NOK + end_value_NOK
statusSymbol:OPTIMAL, :INFEASIBLE, :OTHER

Notes

  • discharge is in Mm³/stage. Divide by m3s_to_Mm3_per_step(resolution) to convert to m³/s.
  • production is computed as sum(prod_MW[t] * step_hours) per stage.
WeeklyScheduling.WaterValueEndValue — Type
WaterValueEndValue

End-value function backed by a WaterValueTable from Phase 1 SDP.

Fields

  • table : WaterValueTable
  • stage : 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
ZeroEndValue

End-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) → VariableRef

Add an end-value variable end_val_<suffix> to model, bounded above by the piecewise-linear cuts from evf. Returns the variable reference.

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 stage
  • evf : the EndValueFunction

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) → CascadeScheduleResult

Solve the multi-reservoir cascade LP scheduling problem.

Arguments

  • cascade : HydroCore.Cascade — full system topology
  • inflows : 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 T
  • end_value_fns : Dict{String, EndValueFunction} — per-reservoir end-of-horizon value function, keyed by reservoir id. Reservoirs with no entry use ZeroEndValue.
  • resolution : PlanningResolution (default WEEKLY)
  • v0 : Dict{String, Float64} — initial reservoir volumes [Mm³]. Reservoirs with no entry use reservoir.initial_volume.
  • silent : suppress solver output (default true)

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 Reservoir nodes appear in results. Junction and Sink nodes 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) → ScheduleResult

Solve the single-reservoir, single-plant LP scheduling problem.

Arguments

  • reservoir : HydroCore.Reservoir
  • plant : HydroCore.Plant (PQ curve + max discharge)
  • inflow : Vector{Float64} — inflow [Mm³/stage], length T
  • price : Vector{Float64} — electricity price [NOK/MWh], length T
  • end_value_fn : EndValueFunction (e.g. WaterValueEndValue or ZeroEndValue)
  • resolution : PlanningResolution (default WEEKLY)
  • v0 : initial reservoir volume [Mm³] (default: reservoir.initial_volume)
  • silent : suppress solver output (default true)

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