gtopt::VolumeRight struct
#include <gtopt/volume_right.hpp>

Volume-based water right (derechos de volumen)

Models the accumulated volume entitlement of a right holder from a reservoir. Behaves like a storage element for LP/SDDP purposes: accumulates delivered volumes over time with state variable coupling across phases.

This is purely a rights accounting entity — it is NOT part of the hydrological topology. The physical water delivery is modeled through the existing hydro cascade; this entity tracks whether enough water has been allocated to satisfy the right.

The purpose field indicates the use case: "irrigation" for consumptive agricultural rights, "generation" for non-consumptive hydroelectric rights.

Public variables

OptActive active
Activation status (default: active)
OptTRealFieldSched annual_loss
Annual fractional loss [p.u./year].
std::optional<RightBoundRule> bound_rule
OptTRealFieldSched demand
OptInt direction
OptTRealFieldSched ecost
Shadow cost of accumulated rights [$/hm³].
OptReal efin
Minimum required accumulated volume at end [hm³].
OptReal eini
Initial accumulated volume at start of horizon [hm³].
OptTRealFieldSched emax
Maximum accumulated right volume [hm³].
OptTRealFieldSched emin
Minimum accumulated right volume [hm³].
OptReal energy_scale
LP scaling factor [dimensionless].
OptName energy_scale_mode
"manual" or "auto"
OptReal fail_cost
OptReal flow_conversion_rate
Converts m³/s × hours into hm³ [hm³/(m³/s·h)].
OptTBRealFieldSched fmax
Name name
Human-readable name.
OptReal priority
OptName purpose
OptSingleId reservoir
std::optional<MonthType> reset_month
OptSingleId right_reservoir
OptTBRealFieldSched saving_rate
OptTRealFieldSched soft_emin
Soft minimum volume per stage [hm³].
OptTRealFieldSched soft_emin_cost
Penalty cost for soft_emin violation [$/hm³].
Uid uid
Unique identifier.
OptBool use_state_variable

Default constants

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

Variable documentation

std::optional<RightBoundRule> gtopt::VolumeRight::bound_rule

Volume-dependent bound rule for dynamic extraction adjustment. Serves two purposes:

  1. Per-block: caps extraction rate to min(fmax, rule_value)
  2. At reset_month: provisions eini = rule_value (annual quota) Both evaluated from the referenced reservoir's current volume via a piecewise-linear function. Implements PLP cushion zone logic (Laja/Maule).

OptTRealFieldSched gtopt::VolumeRight::demand

Required volume delivery per stage [hm³]. This is the demand that must be met — unmet demand incurs the fail_cost penalty.

OptInt gtopt::VolumeRight::direction

Direction sign for the right_reservoir balance row: +1 = supply (volume inflow to the balance) -1 = withdrawal (volume extraction) Only meaningful when right_reservoir is set.

OptReal gtopt::VolumeRight::fail_cost

Penalty cost for unmet volume demand [$/hm³]. Analogous to demand_fail_cost for electrical load curtailment. Higher values give this right higher priority in the LP.

OptTBRealFieldSched gtopt::VolumeRight::fmax

Maximum extraction rate from the right [m³/s]. Physical capacity limit on the rate at which the right can be exercised.

OptReal gtopt::VolumeRight::priority

Priority level for allocation ordering [dimensionless]. Used to differentiate between rights when multiple volume rights compete for the same water.

OptName gtopt::VolumeRight::purpose

Purpose of the water right: "irrigation", "generation", "environmental", etc. Metadata only — does not affect LP.

OptSingleId gtopt::VolumeRight::reservoir

Reference to the physical source reservoir. When set, the VolumeRight's input flow is subtracted from the Reservoir's energy balance (consumptive extraction — water exits the reservoir).

std::optional<MonthType> gtopt::VolumeRight::reset_month

Calendar month at which rights are re-provisioned. When the stage's month matches reset_month, eini is set to:

  • evaluate_bound_rule(reservoir_volume) if bound_rule is set (dynamic provisioning based on current reservoir level, PLP: DerRiego = Base + Σ(Factor_i × Zone_Volume_i))
  • emax if no bound_rule (simple full reprovision) This implements seasonal/annual rights accounting (e.g., Laja irrigation rights re-provisioned each April for the hydro year).

OptSingleId gtopt::VolumeRight::right_reservoir

Optional reference to another VolumeRight for volume balance. When set, this VolumeRight's input flow is added to the target VolumeRight's energy balance row with the given direction sign. This enables hierarchical rights structures (e.g., a parent VolumeRight distributing volume among child rights).

OptTBRealFieldSched gtopt::VolumeRight::saving_rate

Maximum saving deposit rate per block [m³/s]. Only meaningful for economy VolumeRights (purpose="economy"): represents the rate at which unused rights are converted into savings. When set, a saving LP variable is created per block. PLP: IVESN/IVERN/IVAPN.

OptBool gtopt::VolumeRight::use_state_variable

Whether to propagate accumulated volume state across phases via StateVariables (SDDP-style coupling — Tilmant's "dummy reservoir").