SeasonalPlanning API Reference
SeasonalPlanning.SeasonalPlanning — Module
SeasonalPlanningSeasonal hydropower production planning using Stochastic Dual Dynamic Programming (SDDP) with a Markov electricity price model.
Modules
- Phase 5:
MarkovPrice— stochastic price model - Phase 6: SDDP algorithm — multi-reservoir backward/forward passes
- Phase 7: Seasonal plan output — weeks 1–3 report
Quick start (SDDP)
using HydroCore, SeasonalPlanning
# Build cascade, inflow scenarios, price model...
result = solve_sddp(cascade, inflow_scenarios, price_model,
SDDPConfig(n_iterations=50, n_forward_scenarios=10))
result.converged # true/false
result.lower_bounds # LB at each iteration
result.upper_bounds # UB at each iteration
result.cut_library # Benders cuts for each (stage, price_state)SeasonalPlanning.BendersCut — Type
BendersCutA single supporting hyperplane for the future value function.
future_value ≤ intercept + gradient ⋅ volume_vectorFields
intercept: β[NOK]gradient: μ[NOK/Mm³], length K (one per reservoir)
SeasonalPlanning.CachedSubproblem — Type
CachedSubproblemA pre-built JuMP model for the single-stage cascade LP subproblem. Call build_cached_subproblem to create, then solve_cached! to solve with updated parameters.
Invariant parts (set once at construction):
- Variables: v, r, q_way, spill, prod, α
- Variable bounds (min/max volume, discharge limits, etc.)
- PQ curve constraints
Updated each solve:
- Water balance RHS (v0 + inflow) via
set_normalized_rhs - Objective price coefficient via
set_objective_coefficient - Benders cut constraints (deleted and re-added)
SeasonalPlanning.CutLibrary — Type
CutLibraryCollection of Benders cuts indexed by (stage, price_state).
cuts[t][p] is a Vector{BendersCut} — the cuts available at stage t when the price state is p.
Fields
n_stages: number of planning stagesn_price_states: number of discrete price statescuts: Vector of Vector of Vector{BendersCut} [t][p]
SeasonalPlanning.InflowModel — Type
InflowModelDiscrete Markov model for system inflow autocorrelation.
Fields
n_states: number of discrete inflow levelsboundaries: Vector{Float64} of length n_states+1 — quantile boundariesstate_means: Matrix{Float64} (nstages × nstates) — mean inflow per statetransition: Matrix{Float64} (nstates × nstates) — transition probabilitiesstate_inflows: Vector{Vector{Vector{Int}}} — [stage][state] → list of scenario indices
SeasonalPlanning.InputFingerprint — Type
InputFingerprintCaptures the mean inflow and price profiles from a planning run. Used to compute drift between consecutive runs.
Fields
mean_inflow:Dict{String, Vector{Float64}}— mean inflow per reservoirmean_price:Vector{Float64}— mean price profile
SeasonalPlanning.MarkovPriceModel — Type
MarkovPriceModelA discretised Markov chain model for electricity spot prices.
The continuous price axis is divided into n_states bins. The transition matrix T has T[i,j] = probability of moving from state i to state j in one time step. Each row of T sums to 1.0.
Fields
| Field | Description |
|---|---|
n_states | Number of price states P |
state_boundaries | P−1 upper bounds separating states (NOK/MWh) |
representative_prices | Mean price within each state (NOK/MWh), length P |
transition_matrix | P × P row-stochastic transition matrix |
State encoding
State 1 = lowest prices (below state_boundaries[1]). State P = highest prices (above state_boundaries[P-1]).
Example
model = synthetic_price_model(n_states=5, mean_price=400.0, half_range=200.0)
state = 3 # "medium" price
next = sample_next(model, state)
price = expected_price(model, state) # NOK/MWhSeasonalPlanning.NearTermCut — Type
NearTermCutA water value cut valid at a specific near-term stage and price state. These are the interface to short-term planning (Kompendium 2, §5.3.6).
SeasonalPlanning.RestartMetadata — Type
RestartMetadataMetadata stored alongside a cut library for warm-start decisions.
Fields
start_date: Date the planning horizon started fromtimestamp: DateTime when the run was performedmode: :full or :warm_startn_iterations: SDDP iterations performedconverged: whether SDDP convergeddays_since_full: days since last full SDDP rundrift_today: input drift for this runcumulative_drift: accumulated drift since last full runfingerprint: InputFingerprint of the input datareservoir_ids: ordered list of reservoir IDs (for gradient alignment)
SeasonalPlanning.SDDPConfig — Type
SDDPConfigParameters for the SDDP algorithm.
Fields
n_iterations: maximum number of forward/backward iterationsn_forward_scenarios: number of scenarios in forward passconvergence_tol: relative gap (UB − LB) / |UB| for LB/UB convergencevol_convergence_tol: max reservoir deviation between iterations (fraction of max_volume). 0.0 = disabled, use LB/UB only. (default 0.05)min_iterations: minimum iterations before convergence check (default 3)resolution: PlanningResolution (default WEEKLY)seed: random seed for reproducibility (0 = no seed)silent: suppress solver output (default true)cut_prune_interval: prune dominated cuts every N iterations (0 = never, default 0)lb_plateau_iters: stop if LB hasn't improved by more thanconvergence_tolfor this many consecutive iterations (0 = disabled, default 0)max_cuts_per_cell: maximum Benders cuts per (stage, price_state) cell (0 = unlimited, default 0)
SeasonalPlanning.SDDPCutEndValue — Type
SDDPCutEndValueA collection of Benders cuts defining the future value function as a function of all reservoir volumes jointly.
α ≤ cut_i.intercept + cut_i.gradient ⋅ v⃗ ∀ iSeasonalPlanning.SDDPResult — Type
SDDPResultResult from the SDDP algorithm.
Fields
cut_library: CutLibrary — the final set of Benders cutslower_bounds: Vector{Float64} — LB at each iterationupper_bounds: Vector{Float64} — UB at each iterationvolume_deviations: Vector{Float64} — max volume deviation per iterationn_iterations: Int — number of iterations performedconverged: Bool — whether convergence criterion was metreservoir_ids: Vector{String} — reservoir ids in order
SeasonalPlanning.SeasonalPlan — Type
SeasonalPlanThe complete seasonal planning report.
Fields
| Field | Description |
|---|---|
n_stages | Number of planning stages |
n_scenarios | Number of forward scenarios simulated |
reservoir_ids | Reservoir IDs in order |
volume_p10 | T × K matrix — 10th percentile volumes [Mm³] |
volume_p50 | T × K matrix — median volumes [Mm³] |
volume_p90 | T × K matrix — 90th percentile volumes [Mm³] |
production_p10 | T-vector — 10th percentile total production [MWh] |
production_p50 | T-vector — median total production [MWh] |
production_p90 | T-vector — 90th percentile total production [MWh] |
mean_revenue | Scalar — mean total revenue [NOK] |
near_term_cuts | Vector{NearTermCut} — water values at near-term stages |
converged | Whether SDDP converged |
SeasonalPlanning.SubproblemResult — Type
SubproblemResultResult from solving a single-stage SDDP subproblem.
SeasonalPlanning._cascade_energy_equiv_mwh — Method
Compute cascade energy equivalent in MWh/Mm³ for water released from a reservoir.
SeasonalPlanning._compute_lower_bound — Method
_compute_lower_bound(...)Solve the stage-1 subproblem with current cuts to get the lower bound. Uses the mean inflow across all scenarios for a deterministic bound.
SeasonalPlanning._compute_representative_prices — Method
_compute_representative_prices(values, states, n_states) → Vector{Float64}Mean observed price within each state. Used internally by fit_markov_price. States with no observations fall back to the global mean.
SeasonalPlanning._expected_cuts — Method
_expected_cuts(lib, stage, price_model, current_price_state)Compute the expected cuts at stage by weighting cuts from all price states by their transition probabilities from current_price_state.
SeasonalPlanning._find_downstream_plants — Method
Find downstream plants that also generate power from the same water.
SeasonalPlanning._load_subproblem_state! — Method
_load_subproblem_state!(cache, price, cuts_by_state, trans_probs)Load cuts, price, and transition probs into the cached model. Call once per (stage, pricestate), then use `solverhsonly!` for each scenario — avoids redundant cut loading.
SeasonalPlanning._run_sdp_with_cascade — Method
Run SDP with cascade contribution: revenue includes all downstream plants.
SeasonalPlanning._solve_rhs_only! — Method
_solve_rhs_only!(cache, inflow_dict, v0_vec) → SubproblemResultSolve with already-loaded cuts/price/transition probs. Only updates water balance RHS (inflow + v0).
SeasonalPlanning._surface_area — Method
Compute reservoir surface area (∂V/∂h) from HV curve at given volume. Returns area in Mm³/m (= km²).
SeasonalPlanning._terminal_expected_cuts — Method
_terminal_expected_cuts(terminal_benders, price_model, current_price_state)Compute expected terminal cuts weighted by transition probabilities. Returns empty vector if no terminal cuts exist.
SeasonalPlanning.add_cut! — Method
add_cut!(lib, stage, price_state, cut)Add a Benders cut to the library at the given (stage, pricestate). If `maxcutspercell > 0` and the cell is full, drops the oldest cut.
SeasonalPlanning.assign_states — Method
assign_states(values, boundaries) → Vector{Int}Step 2 of the Markov price fitting procedure.
Map each price observation in values to a state index 1…P using the boundaries computed in step 1.
Uses binary search (searchsortedfirst) — O(log P) per observation.
Rule
state = k iff boundaries[k-1] < value ≤ boundaries[k]
(with boundaries[0] = -∞ and boundaries[P] = +∞)Equivalently: state = searchsortedfirst(boundaries, value).
This means ties go to the lower state (value equal to a boundary falls in the state below it).
Arguments
values: price observations[NOK/MWh]boundaries: sorted thresholds fromcompute_state_boundaries
Returns
Vector{Int} of the same length as values, each in 1…n_states.
Example
boundaries = [200.0, 300.0, 400.0, 500.0] # 5-state model
assign_states([150.0, 250.0, 350.0, 600.0], boundaries)
# → [1, 2, 3, 5]SeasonalPlanning.auto_seed_from_cascade! — Method
auto_seed_from_cascade!(cut_lib, cascade, inflow_scenarios, price_model; ...)Run a single-reservoir SDP per price state for each non-buffer reservoir, including downstream plant cascade energy contribution. Seeds the SDDP cut library with the resulting cuts.
SeasonalPlanning.build_cached_subproblem — Method
build_cached_subproblem(cascade, res_list, plant_list, way_list;
resolution, silent) → CachedSubproblemBuild the JuMP model once. Variables, bounds, and PQ curve constraints are fixed. Water balance RHS is set to zero (updated before each solve).
SeasonalPlanning.build_operational_scenarios — Method
build_operational_scenarios(
prognosis, weather_years, horizon;
reservoir_ids=nothing
) → Vector{Dict{String, Vector{Float64}}}Construct multi-year inflow scenarios for SDDP from prognosis + weather year statistics.
Arguments
prognosis:Dict{String, Vector{Float64}}— 1-year inflow prognosis. Keys are reservoir IDs, values are inflow vectors[Mm³/stage]of length ≥horizon.resolution.n_stages(one year's worth of stages).weather_years:Vector{Dict{String, Vector{Float64}}}— historical inflow data. Each entry is one weather year. Keys are reservoir IDs, values are inflow vectors[Mm³/stage]of length = stages per year (e.g., 52 for weekly). Values are indexed by calendar week: index 1 = calendar week 1 (early January), index 52 = calendar week 52.horizon:PlanningHorizon— defines start date, resolution, and total number of stages.
Keyword Arguments
reservoir_ids: optionalVector{String}— if provided, only include these reservoirs. Default: all keys from prognosis.
Returns
Vector{Dict{String, Vector{Float64}}} of length length(weather_years). Each scenario has inflow vectors of length horizon.n_stages.
Calendar Alignment
The prognosis fills stages 1 through n_prognosis (one year). For stages beyond the prognosis, weather year data is sampled by calendar week: stage t maps to calendar_week(horizon, t), which indexes into the weather year vector.
Example
horizon = PlanningHorizon(start_date=Date(2026, 3, 22), n_years=5)
scenarios = build_operational_scenarios(prognosis, weather_years, horizon)
length(scenarios) # == length(weather_years)
length(scenarios[1]["R1"]) # == 260 (5 × 52 stages)SeasonalPlanning.build_transition_matrix — Method
build_transition_matrix(state_sequence, n_states) → Matrix{Float64}Step 3 of the Markov price fitting procedure.
Scan state_sequence and count how often state i is followed by state j. Divide each row by its total count to get probabilities.
The result is a row-stochastic matrix: T[i, j] is the probability of transitioning from state i to state j in one time step, so each row sums to 1.
Handling unvisited states
If state i never appears in state_sequence (a degenerate case with insufficient data), its row would be all zeros. We fall back to a uniform distribution over all states for that row, which keeps the model well-defined without silently producing NaNs.
Arguments
state_sequence: labelled sequence of state indices, e.g. fromassign_statesn_states: total number of states P
Returns
Matrix{Float64} of size (n_states, n_states).
Example
seq = [1, 2, 2, 3, 2, 1, 1, 3]
T = build_transition_matrix(seq, 3)
# T[1, :] = probabilities of next state given current state is 1SeasonalPlanning.cascade_greedy_dispatch — Method
cascade_greedy_dispatch(plant_discharges_mm3, segment_prices, plant_list, conv_weekly)Dispatch all plants in a cascade for one week.
Returns Dict{plantid => (revenue, productionmwh)}.
SeasonalPlanning.classify_inflow — Method
classify_inflow(model, inflow_scenarios, res_ids, scen_idx, stage) → IntDetermine the inflow state for a given scenario and stage.
SeasonalPlanning.compute_head_corrections — Method
compute_head_corrections(cascade, mean_volumes, mean_price;
resolution) → Vector{Float64}Compute per-reservoir head correction coefficients for the LP objective.
mean_volumes is a Dict{String, Float64} mapping reservoirid → mean volume across the simulated trajectories. `meanprice` is the average electricity price [NOK/MWh].
Returns a Vector{Float64} of length K (one per reservoir in topological order), to be added to the volume variable's objective coefficient in the LP.
The correction implements equation (5.7) from Kompendium 2:
c_k = price × dt × Σ_plants_at_k [ P(u) / (A_k × H_net) ]where:
- P(u) is the current production MW
- A_k = ∂V/∂h is the reservoir surface area [Mm²] at mean volume
- H_net is the net head [m]
- dt is hours per time step
A positive c_k means storing more water in reservoir k increases production efficiency → the LP is incentivised to keep the reservoir fuller.
SeasonalPlanning.compute_input_drift — Method
compute_input_drift(old, new; weights, stage_offset) → Float64Compute the combined input drift between two fingerprints.
Arguments
old:InputFingerprintfrom the reference run (last full run)new:InputFingerprintfrom today's data
Keyword Arguments
weights:NamedTuple{(:inflow, :price)}— default(inflow=0.5, price=0.5)stage_offset:Int— number of stages to shift when comparing. For a rolling horizon where today's stage 1 was yesterday's stage 2, usestage_offset=1. The comparison aligns by calendar date:old[t + stage_offset]is compared withnew[t]. Default: 0.
Returns
Combined drift as a non-negative Float64.
SeasonalPlanning.compute_mean_price_profile — Method
compute_mean_price_profile(price_scenarios) → Vector{Float64}Compute the mean price profile across scenarios.
Arguments
price_scenarios:Vector{Vector{Float64}}— each entry is one price scenario of length T.
Returns
Mean price vector of length T.
SeasonalPlanning.compute_mean_profile — Method
compute_mean_profile(scenarios, reservoir_ids) → Dict{String, Vector{Float64}}Compute the mean inflow profile across scenarios for each reservoir. Used for input fingerprinting in the drift metric.
Returns
Dict mapping reservoir ID to mean inflow vector (length T, averaged over all scenarios).
SeasonalPlanning.compute_state_boundaries — Method
compute_state_boundaries(values, n_states) → Vector{Float64}Step 1 of the Markov price fitting procedure.
Compute n_states - 1 price thresholds that divide the empirical distribution of values into n_states equal-probability bins.
With n_states = 5 the quantile levels are 0.20, 0.40, 0.60, 0.80, so each bin covers exactly 20 % of historical observations (marginally).
Equal-probability bins are preferred over equal-width bins because they give each price state the same long-run visitation frequency, which means the SDDP backward pass accumulates cuts at the same rate for all states.
Arguments
values: vector of historical price observations[NOK/MWh]n_states: number of discrete states P (typically 3–7)
Returns
Sorted Vector{Float64} of length n_states - 1.
Example
boundaries = compute_state_boundaries(prices, 5)
# → [b1, b2, b3, b4] meaning:
# state 1 : price ≤ b1
# state 2 : b1 < price ≤ b2
# ...
# state 5 : price > b4SeasonalPlanning.expected_price — Method
expected_price(model, state_index) → Float64Representative price [NOK/MWh] for a given state index (1 = lowest). This is the mean of all historical observations assigned to that state, or the evenly-spaced value for a synthetic model.
SeasonalPlanning.fit_inflow_model — Function
fit_inflow_model(inflow_scenarios, n_states; n_stages=52) → InflowModelFit an AR(1) Markov model from historical inflow scenarios.
For each stage, computes total system inflow across all reservoirs, then discretises into n_states quantile bins. Transition probabilities are estimated from consecutive (stage, stage+1) pairs across all scenarios.
The model stores which scenario indices fall into each (stage, state) bin, so the backward pass can sample scenario-consistent inflows conditioned on the current inflow state.
Arguments
inflow_scenarios: Vector{Dict{String, Vector{Float64}}} — raw scenarios (m³/s)n_states: number of discrete inflow levels (default 3)n_stages: number of stages to model (default: min scenario length)
SeasonalPlanning.fit_markov_price — Function
fit_markov_price(values, n_states) → MarkovPriceModelFit a Markov price model from a vector of historical price observations by composing the three steps:
compute_state_boundaries— equal-probability quantile binsassign_states— label each observationbuild_transition_matrix— count and normalise transitions
Also computes representative prices (mean per state) and packages everything into a MarkovPriceModel.
Arguments
values: historical price time series[NOK/MWh]n_states: number of discrete price states (default 5)
Example
# From a vector of weekly average prices
model = fit_markov_price(historical_prices, 5)
# Or from a HydroCore PriceSeries (pass the .series.values field)
model = fit_markov_price(price_series.series.values, 5)SeasonalPlanning.generate_plan — Method
generate_plan(sddp_result, cascade, inflow_scenarios, price_model;
v0, initial_price_state, n_stages,
n_sim_scenarios, near_term_stages,
resolution, seed) → SeasonalPlanGenerate a seasonal planning report from SDDP results.
Arguments
sddp_result: SDDPResult fromsolve_sddpcascade: Cascadeinflow_scenarios: Vector{Dict{String, Vector{Float64}}}price_model: MarkovPriceModel
Keyword Arguments
v0: Dict{String, Float64} — current reservoir volumesinitial_price_state: Int — current price staten_stages: Int — planning horizon (default from cut library)n_sim_scenarios: Int — number of Monte Carlo scenarios (default 100)near_term_stages: Vector{Int} — stages for water value output (default [1,2,3])resolution: PlanningResolution (default WEEKLY)seed: Int — random seed (default 42)
SeasonalPlanning.get_cuts — Method
get_cuts(lib, stage, price_state) → Vector{BendersCut}SeasonalPlanning.greedy_dispatch — Method
greedy_dispatch(weekly_discharge_mm3, segment_prices, plant, conv_weekly;
segment_hours) → (revenue, production_mwh)Allocate a plant's weekly discharge across intra-week segments to maximise revenue. Greedily fills highest-price segments first.
Arguments
weekly_discharge_mm3: total weekly discharge [Mm³/week]segment_prices: Vector{Tuple{Float64,Float64}} — [(hours, price), ...]plant: Plant with PQ curveconv_weekly: m³/s → Mm³/week conversion factor
Returns
(revenue, production_mwh): total revenue [NOK] and total production [MWh]
SeasonalPlanning.load_state — Method
load_state(path) → (CutLibrary, RestartMetadata)Load a previously saved SDDP state from a JSON file.
SeasonalPlanning.n_cuts — Method
n_cuts(lib) → IntTotal number of cuts in the library.
SeasonalPlanning.n_price_states — Method
n_price_states(model) → IntNumber of discrete price states.
SeasonalPlanning.prune_all_dominated_cuts! — Method
prune_all_dominated_cuts!(lib, forward_volumes; tol=1e-6) → IntPrune dominated cuts across all (stage, price_state) cells using the volume points visited during the forward pass.
Arguments
forward_volumes: Vector{Vector{Vector{Float64}}} — forward_volumes[s][t+1] gives the end-of-stage-t volume for scenario stol: slack tolerance
Returns
Total number of cuts removed.
SeasonalPlanning.prune_dominated_cuts! — Method
prune_dominated_cuts!(lib, stage, price_state, volumes; tol=1e-6)Remove dominated cuts at (stage, price_state). A cut is dominated if it is not the tightest (binding) at any of the given volume points.
Arguments
volumes: Vector{Vector{Float64}} — a set of volume points to test binding status (typically the forward-pass visited volumes)tol: slack tolerance — a cut is considered binding if its value is withintolof the minimum across all cuts
Returns
Number of cuts removed.
SeasonalPlanning.sample_conditional_scenario — Method
sample_conditional_scenario(model, stage, inflow_state, rng) → IntSample a scenario index from the conditional distribution given the current inflow state at the given stage.
SeasonalPlanning.sample_next — Function
sample_next(model, current_state, rng) → IntDraw the next price state from the transition row for current_state.
Uses inverse-CDF sampling: draw a uniform U(0,1) and find which bin of the cumulative row probability it falls in. O(P) per call.
Arguments
model:MarkovPriceModelcurrent_state: current state index (1…P)rng:AbstractRNGfor reproducibility (default: global RNG)
Returns
Next state index in 1…P.
SeasonalPlanning.save_state — Method
save_state(path, cut_lib, metadata)Serialise a cut library and metadata to a JSON file.
SeasonalPlanning.seed_cuts_from_sdp! — Method
seed_cuts_from_sdp!(cut_lib, reservoir_ids, wvt_dict; n_grid_samples)Add initial Benders cuts from pre-computed single-reservoir SDP water value tables.
SeasonalPlanning.shift_cuts — Method
shift_cuts(lib::CutLibrary, n_steps::Int) → CutLibraryShift a cut library forward by n_steps stages for a rolling horizon.
Stage t + n_steps in the old library becomes stage t in the new one. The first n_steps stages are dropped, and n_steps empty stages are appended at the end (terminal value = 0, same as a fresh SDDP's last stage).
Returns a new CutLibrary; the original is not modified.
Example
new_lib = shift_cuts(old_lib, 1)
# old stage 2 → new stage 1
# old stage 3 → new stage 2
# ...
# new final stage → empty (no cuts)SeasonalPlanning.simulate_prices — Method
simulate_prices(model, n_steps; initial_state, rng) → (states, prices)Simulate a price path of length n_steps from initial_state using the Markov transition matrix.
Returns a tuple:
states:Vector{Int}of state indices at each stepprices:Vector{Float64}of representative prices[NOK/MWh]at each step
Arguments
model:MarkovPriceModeln_steps: number of steps to simulateinitial_state: starting state (default 1)rng: random number generator (default: global RNG)
Example
rng = MersenneTwister(42)
model = synthetic_price_model()
states, prices = simulate_prices(model, 52; initial_state=3, rng=rng)SeasonalPlanning.solve_cached! — Method
solve_cached!(cache, inflow_dict, price_scalar, cuts_by_state, trans_probs, v0_vec) → SubproblemResultSolve the cached subproblem with multi-cut formulation.
Arguments
cuts_by_state: Dict{Int, Vector{BendersCut}} — cuts per price state at next stagetrans_probs: Vector{Float64} — transition probabilities from current price state to each next state (length P)
SeasonalPlanning.solve_sddp — Function
solve_sddp(cascade, inflow_scenarios, price_model, config;
v0) → SDDPResultRun the SDDP algorithm for multi-reservoir seasonal planning.
Arguments
cascade: Cascade — full system topologyinflow_scenarios: Vector{Dict{String, Vector{Float64}}} — each entry is one historical scenario. Keys are reservoir ids, values are inflow vectors[Mm³/stage]of length T.price_model: MarkovPriceModelconfig: SDDPConfig
Keyword Arguments
v0: Dict{String, Float64} — initial reservoir volumes[Mm³]initial_price_state: Int — starting price state (default 1)n_stages: Int — number of planning stages (default: length of first inflow scenario)initial_cuts: CutLibrary or nothing — warm-start from a previous run's cut library (default: nothing = fresh start)
Returns
SDDPResult with cut library, convergence history, etc.
SeasonalPlanning.solve_subproblem — Method
solve_subproblem(cascade, res_list, plant_list, way_list,
inflow_dict, price_scalar, cuts, v0_vec;
resolution, silent) → SubproblemResultSolve a single-stage (T=1) cascade LP with joint Benders cuts.
This builds the LP from scratch each time. Future optimization: cache the JuMP model and only update RHS values.
SeasonalPlanning.stationary_distribution — Method
stationary_distribution(model) → Vector{Float64}Long-run probability of being in each price state, computed by power iteration on the transpose of the transition matrix:
πᵀ T = πᵀ ⟺ Tᵀ π = πThe vector π satisfies π[i] = fraction of time spent in state i in the long run (i.e. the stationary distribution of the Markov chain).
Converges geometrically; typically < 200 iterations.
Returns
Normalised Vector{Float64} of length n_states summing to 1.
SeasonalPlanning.synthetic_price_model — Method
synthetic_price_model(; n_states, mean_price, half_range, persistence) → MarkovPriceModelBuild a synthetic mean-reverting Markov price model analytically. Useful for tests and Pluto notebook demos where real price data is not yet available.
The n_states representative prices are spaced evenly from mean_price - half_range to mean_price + half_range.
The transition matrix is built using a Gaussian kernel centred on the mean-reverting expected next state:
expected_next(i) = i + (1 - persistence) × (mid − i)where mid = (n_states + 1) / 2 is the centre state. At persistence = 1 the system never changes state (all mass on diagonal). At persistence = 0 it jumps to the middle state with high probability each step.
Arguments
n_states: number of states (default 5)mean_price: centre of the price range[NOK/MWh](default 400.0)half_range: half-width of the price range[NOK/MWh](default 200.0)persistence: how sticky the current state is, ∈ (0, 1) (default 0.6)
Example
model = synthetic_price_model(n_states=5, mean_price=400.0,
half_range=200.0, persistence=0.6)
# → States with representative prices [200, 300, 400, 500, 600] NOK/MWhSeasonalPlanning.to_csv — Method
to_csv(plan::SeasonalPlan, path::String)Export the seasonal plan to CSV files:
{path}_volumes.csv— P10/P50/P90 reservoir volumes{path}_production.csv— P10/P50/P90 production