gtopt::Reservoir struct
#include <gtopt/reservoir.hpp>

Water reservoir in a hydro cascade system.

The reservoir accumulates and releases water between time blocks. The volume balance per block is:

V[t+1] = V[t] × (1 − annual_loss/8760 × duration)
       + flow_conversion_rate × (inflows − outflows) × duration

where inflows/outflows include waterway flows, turbine discharges, natural inflows (Flow), and seepage (ReservoirSeepage).

Public functions

auto energy_scale_mode_enum() const -> EnergyScaleMode noexcept: Parse energy_scale_mode string to enum (auto_scale if unset).

Public variables

OptActive active: Activation status (default: active)
OptTRealFieldSched annual_loss: Annual fractional evaporation/seepage loss [p.u./year].
OptTRealFieldSched capacity: Total usable storage capacity [hm³].
OptBool daily_cycle
Array<ReservoirDischargeLimit> discharge_limit
OptTRealFieldSched ecost: Shadow cost of stored water (water value) [$/hm³].
OptReal efin: Minimum required stored volume at end of horizon [hm³]. Sets a >= constraint vol_end >= efin in the last stage of the last phase (not an equality).
OptReal eini: Initial stored volume at start of horizon [hm³]. Sets an equality constraint vol_start = eini in the first stage of the first phase only.
OptTRealFieldSched emax: Maximum allowed stored volume [hm³].
OptTRealFieldSched emin: Minimum allowed stored volume [hm³].
OptReal energy_scale
OptName energy_scale_mode
OptReal flow_conversion_rate
OptReal fmax: Maximum net flow into the reservoir junction [m³/s].
OptReal fmin: Minimum net flow into the reservoir junction [m³/s].
SingleId junction: ID of the associated hydraulic junction.
Name name: Human-readable name.
Array<ReservoirProductionFactor> production_factor
Array<ReservoirSeepage> seepage
OptTRealFieldSched soft_emin: Soft minimum volume per stage [hm³]. Creates a penalized constraint: efin + slack >= soft_emin, where the slack variable has a penalty cost (soft_emin_cost) in the objective. Unlike emin (a hard variable bound), this allows the volume to drop below the threshold at a cost. Corresponds to PLP's plpminembh.dat "holgura" (slack) constraint.
OptTRealFieldSched soft_emin_cost
OptReal spillway_capacity: Maximum uncontrolled spill capacity [m³/s].
OptReal spillway_cost: Penalty cost per unit of spilled water [$/hm³].
Uid uid: Unique identifier.
OptBool use_state_variable

Default physical constants

static constexpr Real default_spillway_capacity: [m³/s]
static constexpr Real default_fmin: [m³/s]
static constexpr Real default_fmax: [m³/s]
static constexpr Real default_energy_scale: [dimensionless]
static constexpr Real default_flow_conversion_rate: [hm³/(m³/s·h)]

Variable documentation

OptBool gtopt::Reservoir::daily_cycle

Enable PLP-style daily cycle operation (see Battery::daily_cycle). Default for reservoirs is false (disabled); can be enabled explicitly for small reservoirs that operate on a daily cycle.

Array<ReservoirDischargeLimit> gtopt::Reservoir::discharge_limit

Inline discharge limit definitions for this reservoir. Each entry needs only waterway and segments; reservoir is set automatically.

OptReal gtopt::Reservoir::energy_scale

Energy scale factor: LP variable = physical_energy / energy_scale [dimensionless]. When set, overrides auto-scaling regardless of energy_scale_mode.

OptName gtopt::Reservoir::energy_scale_mode

How to determine energy_scale: "manual" (use explicit field, default 1.0) or "auto" (compute max(1, emax/1000) like PLP). Default: "auto".

OptReal gtopt::Reservoir::flow_conversion_rate

Converts m³/s × hours into hm³ [hm³/(m³/s·h)]

Array<ReservoirProductionFactor> gtopt::Reservoir::production_factor

Inline production factor definitions for this reservoir. Each entry needs only turbine and segments; reservoir is set automatically.

Array<ReservoirSeepage> gtopt::Reservoir::seepage

Inline seepage definitions for this reservoir. Each entry needs only waterway (and optionally slope/constant/segments); reservoir is set automatically from this reservoir's uid.

OptTRealFieldSched gtopt::Reservoir::soft_emin_cost

Penalty cost per unit of soft_emin violation [$/hm³]. Applied to the slack variable that relaxes the soft_emin constraint. Must be > 0 for the constraint to be active.

OptBool gtopt::Reservoir::use_state_variable

Whether to propagate volume state across stage/phase boundaries via StateVariables (SDDP-style coupling). When true (the default for reservoirs), the final volume of one phase is carried over as the initial volume of the next. When false, an efin==eini constraint is added to close each phase independently.