SeasonalPlanning API Reference

SeasonalPlanning.SeasonalPlanning — Module
SeasonalPlanning

Seasonal 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
BendersCut

A single supporting hyperplane for the future value function.

future_value ≤ intercept + gradient ⋅ volume_vector

Fields

  • intercept : β [NOK]
  • gradient : μ [NOK/Mm³], length K (one per reservoir)
SeasonalPlanning.CachedSubproblem — Type
CachedSubproblem

A 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
CutLibrary

Collection 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 stages
  • n_price_states : number of discrete price states
  • cuts : Vector of Vector of Vector{BendersCut} [t][p]
SeasonalPlanning.InflowModel — Type
InflowModel

Discrete Markov model for system inflow autocorrelation.

Fields

  • n_states : number of discrete inflow levels
  • boundaries : Vector{Float64} of length n_states+1 — quantile boundaries
  • state_means : Matrix{Float64} (nstages × nstates) — mean inflow per state
  • transition : Matrix{Float64} (nstates × nstates) — transition probabilities
  • state_inflows : Vector{Vector{Vector{Int}}} — [stage][state] → list of scenario indices
SeasonalPlanning.InputFingerprint — Type
InputFingerprint

Captures 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 reservoir
  • mean_price : Vector{Float64} — mean price profile
SeasonalPlanning.MarkovPriceModel — Type
MarkovPriceModel

A 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

FieldDescription
n_statesNumber of price states P
state_boundariesP−1 upper bounds separating states (NOK/MWh)
representative_pricesMean price within each state (NOK/MWh), length P
transition_matrixP × 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/MWh
SeasonalPlanning.NearTermCut — Type
NearTermCut

A 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
RestartMetadata

Metadata stored alongside a cut library for warm-start decisions.

Fields

  • start_date : Date the planning horizon started from
  • timestamp : DateTime when the run was performed
  • mode : :full or :warm_start
  • n_iterations : SDDP iterations performed
  • converged : whether SDDP converged
  • days_since_full : days since last full SDDP run
  • drift_today : input drift for this run
  • cumulative_drift : accumulated drift since last full run
  • fingerprint : InputFingerprint of the input data
  • reservoir_ids : ordered list of reservoir IDs (for gradient alignment)
SeasonalPlanning.SDDPConfig — Type
SDDPConfig

Parameters for the SDDP algorithm.

Fields

  • n_iterations : maximum number of forward/backward iterations
  • n_forward_scenarios : number of scenarios in forward pass
  • convergence_tol : relative gap (UB − LB) / |UB| for LB/UB convergence
  • vol_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 than convergence_tol for 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
SDDPCutEndValue

A collection of Benders cuts defining the future value function as a function of all reservoir volumes jointly.

α ≤ cut_i.intercept + cut_i.gradient ⋅ v⃗    ∀ i
SeasonalPlanning.SDDPResult — Type
SDDPResult

Result from the SDDP algorithm.

Fields

  • cut_library : CutLibrary — the final set of Benders cuts
  • lower_bounds : Vector{Float64} — LB at each iteration
  • upper_bounds : Vector{Float64} — UB at each iteration
  • volume_deviations : Vector{Float64} — max volume deviation per iteration
  • n_iterations : Int — number of iterations performed
  • converged : Bool — whether convergence criterion was met
  • reservoir_ids : Vector{String} — reservoir ids in order
SeasonalPlanning.SeasonalPlan — Type
SeasonalPlan

The complete seasonal planning report.

Fields

FieldDescription
n_stagesNumber of planning stages
n_scenariosNumber of forward scenarios simulated
reservoir_idsReservoir IDs in order
volume_p10T × K matrix — 10th percentile volumes [Mm³]
volume_p50T × K matrix — median volumes [Mm³]
volume_p90T × K matrix — 90th percentile volumes [Mm³]
production_p10T-vector — 10th percentile total production [MWh]
production_p50T-vector — median total production [MWh]
production_p90T-vector — 90th percentile total production [MWh]
mean_revenueScalar — mean total revenue [NOK]
near_term_cutsVector{NearTermCut} — water values at near-term stages
convergedWhether SDDP converged
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._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._solve_rhs_only! — Method
_solve_rhs_only!(cache, inflow_dict, v0_vec) → SubproblemResult

Solve with already-loaded cuts/price/transition probs. Only updates water balance RHS (inflow + v0).

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 from compute_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) → CachedSubproblem

Build 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 : optional Vector{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. from assign_states
  • n_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 1
SeasonalPlanning.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) → Int

Determine 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) → Float64

Compute the combined input drift between two fingerprints.

Arguments

  • old : InputFingerprint from the reference run (last full run)
  • new : InputFingerprint from 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, use stage_offset=1. The comparison aligns by calendar date: old[t + stage_offset] is compared with new[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 > b4
SeasonalPlanning.expected_price — Method
expected_price(model, state_index) → Float64

Representative 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) → InflowModel

Fit 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) → MarkovPriceModel

Fit a Markov price model from a vector of historical price observations by composing the three steps:

  1. compute_state_boundaries — equal-probability quantile bins
  2. assign_states — label each observation
  3. build_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) → SeasonalPlan

Generate a seasonal planning report from SDDP results.

Arguments

  • sddp_result : SDDPResult from solve_sddp
  • cascade : Cascade
  • inflow_scenarios : Vector{Dict{String, Vector{Float64}}}
  • price_model : MarkovPriceModel

Keyword Arguments

  • v0 : Dict{String, Float64} — current reservoir volumes
  • initial_price_state : Int — current price state
  • n_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.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 curve
  • conv_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.prune_all_dominated_cuts! — Method
prune_all_dominated_cuts!(lib, forward_volumes; tol=1e-6) → Int

Prune 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 s
  • tol : 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 within tol of the minimum across all cuts

Returns

Number of cuts removed.

SeasonalPlanning.sample_conditional_scenario — Method
sample_conditional_scenario(model, stage, inflow_state, rng) → Int

Sample 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) → Int

Draw 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 : MarkovPriceModel
  • current_state : current state index (1…P)
  • rng : AbstractRNG for reproducibility (default: global RNG)

Returns

Next state index in 1…P.

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

Shift 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 step
  • prices : Vector{Float64} of representative prices [NOK/MWh] at each step

Arguments

  • model : MarkovPriceModel
  • n_steps : number of steps to simulate
  • initial_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) → SubproblemResult

Solve the cached subproblem with multi-cut formulation.

Arguments

  • cuts_by_state : Dict{Int, Vector{BendersCut}} — cuts per price state at next stage
  • trans_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) → SDDPResult

Run the SDDP algorithm for multi-reservoir seasonal planning.

Arguments

  • cascade : Cascade — full system topology
  • inflow_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 : MarkovPriceModel
  • config : 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) → SubproblemResult

Solve 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) → MarkovPriceModel

Build 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/MWh
SeasonalPlanning.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