PlanningResolution — Time-Step Configuration

All planning packages accept a PlanningResolution parameter rather than hardcoding a time step. This makes it trivial to switch between weekly, daily, or hourly models by changing a single configuration value.


The problem it solves

Before Phase 0.5, the SDP code contained:

const HOURS_PER_WEEK = 168.0
r_max_Mm3w = max_discharge * HOURS_PER_WEEK * 3600.0 * 1e-6

This is fragile — the constant 168 must be updated in multiple places to switch resolution, and it is easy to miss one.

After Phase 0.5:

r_max = max_discharge * m3s_to_Mm3_per_step(resolution)

The resolution object carries all time-step arithmetic in one place.


The struct

struct PlanningResolution
    step::Period      # Dates.Week(1), Day(1), Hour(1), …
    n_stages::Int     # typical stages per planning year
    label::String     # "weekly", "daily", "hourly", …
end

Predefined constants

WEEKLY  = PlanningResolution(Week(1),  52,   "weekly")
DAILY   = PlanningResolution(Day(1),   365,  "daily")
HOURLY  = PlanningResolution(Hour(1),  8760, "hourly")

Import them from HydroCore:

using HydroCore: WEEKLY, DAILY, HOURLY

Key derived functions

FunctionReturnsExample
step_hours(r)Float64 — hours per stagestep_hours(WEEKLY) → 168.0
step_seconds(r)Float64 — seconds per stagestep_seconds(DAILY) → 86400.0
m3s_to_Mm3_per_step(r)conversion factor m³/s → Mm³/stagem3s_to_Mm3_per_step(WEEKLY) → 0.6048
stage_index(dt, r)stage number (1-based) within yearstage_index(DateTime(2024,3,15), DAILY) → 75

How resolution flows through the packages

WaterValues (SDP)

# Build inflow scenarios at chosen resolution
inflows = extract_periodic_inflows(series, DAILY)   # 365 PeriodicInflows

# Run SDP at daily resolution (365 stages)
wvt = solve_sdp(reservoir, plant, inflows;
                price=400.0, resolution=DAILY)

# Lookup uses stage= (new) or week= (backward compat)
wv = lookup(wvt; stage=75, volume=60.0)

SeasonalPlanning / SDDP (Phase 6)

The MarkovPriceModel is fitted from a price series at the same resolution as the planning model — weekly transitions for a weekly model, daily transitions for a daily model. The struct is the same; only the transition matrix differs.

WeeklyScheduling / LP (Phase 2)

schedule(reservoir, plant, inflow, price, end_value;
         resolution=DAILY)   # daily stages, 24-hour energy

PeriodicInflows — renamed from WeeklyInflows

WeeklyInflows was renamed to PeriodicInflows to reflect that the same struct works at any resolution. The week field was renamed to stage.

Backward compatibility:

const WeeklyInflows = PeriodicInflows   # type alias
extract_weekly_inflows(s) = extract_periodic_inflows(s, WEEKLY)  # function alias
lookup(wvt; week=10, volume=v)   # week= keyword still accepted

Old code written for Phase 1 continues to work without changes.


Resolution and the spot market

The Nord Pool day-ahead market clears daily — one price per hour for the next 24 hours. A daily resolution planning model (DAILY) aligns naturally with this:

  • Each stage = one day
  • expected_price(price_model, state) gives the representative day-ahead price for that Markov state
  • Production decisions are made once per day

Weekly resolution is faster and sufficient for long-term SDP (Phase 1), but daily is the correct granularity for seasonal planning (Phase 6–7) that will inform day-ahead bidding.