gtopt::VolumeRightLP class
#include <gtopt/volume_right_lp.hpp>

LP representation of a volume-based water right.

Extends StorageLP to provide storage-like LP behaviour for water rights accounting. The "energy" balance tracks accumulated right volume (hm³), not physical water.

State variable coupling via SDDP propagates accumulated right volumes across phases, following Tilmant et al. (2008).

Base classes

template<typename Object Object>
class StorageLP<ObjectLP<VolumeRight>>

Public types

using object_type = VolumeRight
Type of the wrapped object.
using StorageBase = StorageLP<ObjectLP<VolumeRight>>

Public static variables

static constexpr LPClassName ClassName

Constructors, destructors, conversion operators

VolumeRightLP(const VolumeRight& pvol, const InputContext& ic) explicit

Public functions

auto add_to_lp(std::string_view cname, SystemContextT& sc, const ScenarioLP& scenario, const StageLP& stage, LinearProblem& lp, const double flow_conversion_rate, const BIndexHolder<ColIndex>& finp_cols, const double finp_efficiency, const BIndexHolder<ColIndex>& fout_cols, const double fout_efficiency, const double stage_capacity, const std::optional<ColIndex> capacity_col = {}, const std::optional<Real> drain_cost = {}, const std::optional<Real> drain_capacity = {}, const StorageOptions opts = {}) -> bool
auto add_to_lp(SystemContext& sc, const ScenarioLP& scenario, const StageLP& stage, LinearProblem& lp) -> bool
auto add_to_output(OutputContext& out) const -> bool
auto add_to_output(OutputContext& out, std::string_view cname) const -> bool
auto class_name(this const Self& self) -> constexpr auto noexcept
auto drain_cols_at(const ScenarioLP& scenario, const StageLP& stage) const -> constexpr const auto&
auto efin_col_at(const ScenarioLP& scenario, const StageLP& stage) const -> constexpr auto
auto eini_col_at(const ScenarioLP& scenario, const StageLP& stage) const -> ColIndex
auto energy_cols_at(const ScenarioLP& scenario, const StageLP& stage) const -> constexpr const auto&
auto energy_rows_at(const ScenarioLP& scenario, const StageLP& stage) const -> constexpr const auto&
auto energy_scale() const -> constexpr double noexcept
auto extraction_cols_at(const ScenarioLP& scenario, const StageLP& stage) const -> const auto&
auto flow_conversion_rate() const -> constexpr auto noexcept
auto flow_scale() const -> constexpr double noexcept
auto id() const -> constexpr auto noexcept
auto id(this const Self& self) -> constexpr auto noexcept
Gets the object's identifier (explicit object syntax)
auto is_active(const StageLP& stage) const -> constexpr bool
Checks if object is active in given stage.
template<typename Self Self, typename SystemContext SystemContext, typename... Args>
auto lp_col_label(this const Self& self, SystemContext& sc, const ScenarioLP& scenario, const StageLP& stage, Args && ... args) -> constexpr auto
template<typename Self Self, typename SystemContext SystemContext, typename... Args>
auto lp_col_label(this const Self& self, SystemContext& sc, const ScenarioLP& scenario, const StageLP& stage, const BlockLP& block, Args && ... args) -> constexpr auto
template<typename Self Self, typename SystemContext SystemContext, typename... Args>
auto lp_label(this const Self& self, SystemContext& sc, const ScenarioLP& scenario, const StageLP& stage, Args && ... args) -> constexpr auto
template<typename Self Self, typename SystemContext SystemContext, typename... Args>
auto lp_label(this const Self& self, SystemContext& sc, const ScenarioLP& scenario, const StageLP& stage, const BlockLP& block, Args && ... args) -> constexpr auto
template<typename Self Self, typename SystemContext SystemContext, typename... Args>
auto lp_label(this const Self& self, SystemContext& sc, const StageLP& stage, Args && ... args) -> constexpr auto
auto object() && -> constexpr VolumeRight&& noexcept
auto object() & -> constexpr VolumeRight& noexcept
Gets the wrapped object.
auto object() const && -> constexpr const VolumeRight&& noexcept
auto object() const & -> constexpr const VolumeRight& noexcept
auto physical_col_value(std::span<const double> col_values, ColIndex col) const -> constexpr double noexcept
auto physical_efin(const LinearInterface& li, const ScenarioLP& scenario, const StageLP& stage, double default_efin) const -> double
auto physical_efin(const SystemLPT& sys, const ScenarioLP& scenario, const StageLP& stage, double default_efin) const -> double
Overload accepting a SystemLP (extracts LinearInterface internally).
auto physical_eini(const LinearInterface& li, const ScenarioLP& scenario, const StageLP& stage, double default_eini) const -> double
auto physical_eini(const SystemLPT& sys, const ScenarioLP& scenario, const StageLP& stage, double default_eini, const SIdT& sid) const -> double
auto saving_cols_at(const ScenarioLP& scenario, const StageLP& stage) const -> const auto&
auto set_id(Uid uid, Name name) -> constexpr auto& noexcept
Sets the object's identifier.
auto short_name(this const Self& self) -> constexpr auto noexcept
auto soft_emin_col_at(const ScenarioLP& scenario, const StageLP& stage) const -> std::optional<ColIndex>
template<typename Self Self, typename SystemContext SystemContext, typename... Args>
auto state_col_label(this const Self& self, SystemContext& sc, const ScenarioLP& scenario, const StageLP& stage, Args && ... args) -> constexpr auto
Generates a label for a variable in the optimization problem.
template<typename Self Self, typename SystemContext SystemContext, typename... Args>
auto state_col_label(this const Self& self, SystemContext& sc, const ScenarioLP& scenario, const StageLP& stage, const BlockLP& block, Args && ... args) -> constexpr auto
auto storage(this auto&& self) -> constexpr auto&& noexcept
template<typename Self Self, typename ScenarioLP ScenarioLP, typename StageLP StageLP>
auto sv_key(this const Self& self, const ScenarioLP& scenario, const StageLP& stage, std::string_view col_name) -> constexpr auto noexcept
Generates a state variable key for the object.
template<typename Self Self, typename StageLP StageLP>
auto sv_key(this const Self& self, const StageLP& stage, std::string_view col_name) -> constexpr auto noexcept
auto to_physical(double lp_value) const -> constexpr double noexcept
Convert an LP-unit energy/volume value to physical units.
auto uid() const -> constexpr auto noexcept
auto update_lp(SystemLP& sys, const ScenarioLP& scenario, const StageLP& stage) -> int
auto volume_right(this auto&& self) -> constexpr auto&& noexcept

Parameter accessors for user constraint resolution

auto param_fmax(StageUid s, BlockUid b) const -> auto
auto param_saving_rate(StageUid s, BlockUid b) const -> auto
auto param_demand(StageUid s) const -> auto
auto param_fail_cost() const -> auto

Parameter accessors for user constraint resolution

auto param_emin(StageUid s) const -> auto
auto param_emax(StageUid s) const -> auto
auto param_ecost(StageUid s) const -> auto

Typedef documentation

using gtopt::VolumeRightLP::object_type = VolumeRight
#include <gtopt/object_lp.hpp>

Type of the wrapped object.

Function documentation

bool gtopt::VolumeRightLP::add_to_lp(std::string_view cname, SystemContextT& sc, const ScenarioLP& scenario, const StageLP& stage, LinearProblem& lp, const double flow_conversion_rate, const BIndexHolder<ColIndex>& finp_cols, const double finp_efficiency, const BIndexHolder<ColIndex>& fout_cols, const double fout_efficiency, const double stage_capacity, const std::optional<ColIndex> capacity_col = {}, const std::optional<Real> drain_cost = {}, const std::optional<Real> drain_capacity = {}, const StorageOptions opts = {})
#include <gtopt/storage_lp.hpp>

bool gtopt::VolumeRightLP::add_to_output(OutputContext& out, std::string_view cname) const
#include <gtopt/storage_lp.hpp>

constexpr auto gtopt::VolumeRightLP::class_name(this const Self& self) noexcept
#include <gtopt/object_lp.hpp>

constexpr const auto& gtopt::VolumeRightLP::drain_cols_at(const ScenarioLP& scenario, const StageLP& stage) const
#include <gtopt/storage_lp.hpp>

Return the drain/spill column indices for (scenario, stage).

Drain columns represent the spillway (for reservoirs) or energy curtailment (for batteries). They are only present when the storage object has a non-zero drain cost; if absent for the requested pair, std::out_of_range is thrown (caught by the user-constraint resolver to produce a graceful std::nullopt).

constexpr auto gtopt::VolumeRightLP::efin_col_at(const ScenarioLP& scenario, const StageLP& stage) const
#include <gtopt/storage_lp.hpp>

ColIndex gtopt::VolumeRightLP::eini_col_at(const ScenarioLP& scenario, const StageLP& stage) const
#include <gtopt/storage_lp.hpp>

Return the initial-energy column for (scenario, stage).

Three cases:

  • Global initial condition (first stage of first phase): stored in eini_cols with a fixed "eini" column.
  • Same-phase reuse: eini_cols stores the previous stage's efin col.
  • Cross-phase SDDP boundary: sini_cols stores the "sini" col; fall back from eini_cols (which does NOT have this entry) to sini_cols.

Invariant: every active (scenario, stage) pair is stored in exactly one of the two maps. The fallback throws std::out_of_range only if the caller passes an invalid (scenario, stage) combination.

constexpr const auto& gtopt::VolumeRightLP::energy_cols_at(const ScenarioLP& scenario, const StageLP& stage) const
#include <gtopt/storage_lp.hpp>

constexpr const auto& gtopt::VolumeRightLP::energy_rows_at(const ScenarioLP& scenario, const StageLP& stage) const
#include <gtopt/storage_lp.hpp>

Return the energy balance row indices for (scenario, stage).

These are the storage balance constraint rows (one per block). External entities can add coefficients to these rows to couple their flow variables into this storage's energy balance.

constexpr double gtopt::VolumeRightLP::energy_scale() const noexcept
#include <gtopt/storage_lp.hpp>

Energy/volume scale factor used in the LP: LP_var = physical / scale. For batteries this is Battery::energy_scale; for reservoirs it is Reservoir::energy_scale. Use to convert between LP and physical units.

const auto& gtopt::VolumeRightLP::extraction_cols_at(const ScenarioLP& scenario, const StageLP& stage) const

Return the extraction flow column indices for (scenario, stage). These are the decision variables for how much right volume is extracted per block. External entities can reference these to couple into this VolumeRight's balance.

constexpr double gtopt::VolumeRightLP::flow_scale() const noexcept
#include <gtopt/storage_lp.hpp>

Flow variable scale factor used in the LP.

For drain (and extraction/finp/fout in the reservoir case): LP_var = physical / flow_scale. Default 1.0 (no scaling; battery default). Reservoirs use energy_scale.

constexpr auto gtopt::VolumeRightLP::id() const noexcept
#include <gtopt/object_lp.hpp>

Returns The object's complete identifier (uid + name)

constexpr auto gtopt::VolumeRightLP::id(this const Self& self) noexcept
#include <gtopt/storage_lp.hpp>

Gets the object's identifier (explicit object syntax)

Parameters
self Reference to this object
Returns Id containing the object's uid and name

constexpr bool gtopt::VolumeRightLP::is_active(const StageLP& stage) const
#include <gtopt/object_lp.hpp>

Checks if object is active in given stage.

Parameters
stage The stage to check
Returns true if active in stage, false otherwise

#include <gtopt/object_utils.hpp>
template<typename Self Self, typename SystemContext SystemContext, typename... Args>
constexpr auto gtopt::VolumeRightLP::lp_col_label(this const Self& self, SystemContext& sc, const ScenarioLP& scenario, const StageLP& stage, Args && ... args)

#include <gtopt/object_utils.hpp>
template<typename Self Self, typename SystemContext SystemContext, typename... Args>
constexpr auto gtopt::VolumeRightLP::lp_col_label(this const Self& self, SystemContext& sc, const ScenarioLP& scenario, const StageLP& stage, const BlockLP& block, Args && ... args)

#include <gtopt/object_utils.hpp>
template<typename Self Self, typename SystemContext SystemContext, typename... Args>
constexpr auto gtopt::VolumeRightLP::lp_label(this const Self& self, SystemContext& sc, const ScenarioLP& scenario, const StageLP& stage, Args && ... args)

#include <gtopt/object_utils.hpp>
template<typename Self Self, typename SystemContext SystemContext, typename... Args>
constexpr auto gtopt::VolumeRightLP::lp_label(this const Self& self, SystemContext& sc, const ScenarioLP& scenario, const StageLP& stage, const BlockLP& block, Args && ... args)

#include <gtopt/object_utils.hpp>
template<typename Self Self, typename SystemContext SystemContext, typename... Args>
constexpr auto gtopt::VolumeRightLP::lp_label(this const Self& self, SystemContext& sc, const StageLP& stage, Args && ... args)

constexpr VolumeRight&& gtopt::VolumeRightLP::object() && noexcept
#include <gtopt/object_lp.hpp>

constexpr VolumeRight& gtopt::VolumeRightLP::object() & noexcept
#include <gtopt/object_lp.hpp>

Gets the wrapped object.

Returns Reference to the wrapped object

constexpr const VolumeRight&& gtopt::VolumeRightLP::object() const && noexcept
#include <gtopt/object_lp.hpp>

constexpr const VolumeRight& gtopt::VolumeRightLP::object() const & noexcept
#include <gtopt/object_lp.hpp>

constexpr double gtopt::VolumeRightLP::physical_col_value(std::span<const double> col_values, ColIndex col) const noexcept
#include <gtopt/storage_lp.hpp>

Parameters
col_values LP solution (or bounds) vector indexed by ColIndex
col Column index of the energy/volume variable
Returns The column value converted to physical units

Retrieve a physical energy/volume value from an LP column vector.

double gtopt::VolumeRightLP::physical_efin(const LinearInterface& li, const ScenarioLP& scenario, const StageLP& stage, double default_efin) const
#include <gtopt/storage_lp.hpp>

Retrieve the physical efin (final energy/volume) for a given scenario and stage. Fallback chain:

  1. LP optimal solution
  2. Warm column solution (loaded from hot-start state file)
  3. default_efin

double gtopt::VolumeRightLP::physical_efin(const SystemLPT& sys, const ScenarioLP& scenario, const StageLP& stage, double default_efin) const
#include <gtopt/storage_lp.hpp>

Overload accepting a SystemLP (extracts LinearInterface internally).

double gtopt::VolumeRightLP::physical_eini(const LinearInterface& li, const ScenarioLP& scenario, const StageLP& stage, double default_eini) const
#include <gtopt/storage_lp.hpp>

Retrieve the physical eini without cross-phase lookup.

Used by callers that only have a LinearInterface (e.g. tests, non-SDDP code). Fallback chain: optimal solution → warm solution → default_eini.

double gtopt::VolumeRightLP::physical_eini(const SystemLPT& sys, const ScenarioLP& scenario, const StageLP& stage, double default_eini, const SIdT& sid) const
#include <gtopt/storage_lp.hpp>

Parameters
sys Current SystemLP (provides linear_interface and prev_phase_sys for cross-phase lookups).
scenario Current scenario LP object.
stage Current stage LP object.
default_eini Initial energy/volume when no LP solution exists.
sid ObjectSingleId for this element, used to look up the same storage element in the previous phase.

Retrieve the physical eini (initial energy/volume) for a given scenario and stage.

For the first stage of the first phase the eini column is the fixed initial condition, so default_eini is returned directly.

For cross-phase boundaries (phase > 0), eini corresponds to the previous phase's efin. When the current LP hasn't been solved and no warm solution is available, the method looks up the previous phase's efin from sys.prev_phase_sys(). Fallback chain:

  1. Current LP optimal solution (eini/sini column)
  2. Current LP warm column solution (from hot-start state file)
  3. Previous phase's efin (via sys.prev_phase_sys())
  4. default_eini (system initial volume / vini)

const auto& gtopt::VolumeRightLP::saving_cols_at(const ScenarioLP& scenario, const StageLP& stage) const

Return the saving (inflow) column indices for (scenario, stage). These are the decision variables for how much savings are deposited per block. Only populated when saving_rate is set.

constexpr auto& gtopt::VolumeRightLP::set_id(Uid uid, Name name) noexcept
#include <gtopt/object_lp.hpp>

Sets the object's identifier.

Parameters
uid Unique identifier
name Human-readable name
Returns Reference to self for chaining

constexpr auto gtopt::VolumeRightLP::short_name(this const Self& self) noexcept
#include <gtopt/object_lp.hpp>

std::optional<ColIndex> gtopt::VolumeRightLP::soft_emin_col_at(const ScenarioLP& scenario, const StageLP& stage) const
#include <gtopt/storage_lp.hpp>

Return the soft-emin slack column for (scenario, stage), if it exists.

The soft-emin slack is only created when soft_emin > 0 and soft_emin_cost > 0 for the given stage. Returns std::nullopt when the column was not created (i.e., soft_emin is inactive for this stage).

#include <gtopt/object_utils.hpp>
template<typename Self Self, typename SystemContext SystemContext, typename... Args>
constexpr auto gtopt::VolumeRightLP::state_col_label(this const Self& self, SystemContext& sc, const ScenarioLP& scenario, const StageLP& stage, Args && ... args)

Generates a label for a variable in the optimization problem.

Parameters
self Reference to the object
sc System context
scenario Scenario context
stage Stage context
args Additional arguments to include in the label
Returns Label string

#include <gtopt/object_utils.hpp>
template<typename Self Self, typename SystemContext SystemContext, typename... Args>
constexpr auto gtopt::VolumeRightLP::state_col_label(this const Self& self, SystemContext& sc, const ScenarioLP& scenario, const StageLP& stage, const BlockLP& block, Args && ... args)

constexpr auto&& gtopt::VolumeRightLP::storage(this auto&& self) noexcept
#include <gtopt/storage_lp.hpp>

#include <gtopt/object_utils.hpp>
template<typename Self Self, typename ScenarioLP ScenarioLP, typename StageLP StageLP>
constexpr auto gtopt::VolumeRightLP::sv_key(this const Self& self, const ScenarioLP& scenario, const StageLP& stage, std::string_view col_name) noexcept

Generates a state variable key for the object.

Parameters
self Reference to the object
scenario Scenario context
stage Stage context
col_name The column name for the state variable
Returns StateVariable::Key

#include <gtopt/object_utils.hpp>
template<typename Self Self, typename StageLP StageLP>
constexpr auto gtopt::VolumeRightLP::sv_key(this const Self& self, const StageLP& stage, std::string_view col_name) noexcept

constexpr double gtopt::VolumeRightLP::to_physical(double lp_value) const noexcept
#include <gtopt/storage_lp.hpp>

Convert an LP-unit energy/volume value to physical units.

constexpr auto gtopt::VolumeRightLP::uid() const noexcept
#include <gtopt/object_lp.hpp>

Returns The object's unique identifier

int gtopt::VolumeRightLP::update_lp(SystemLP& sys, const ScenarioLP& scenario, const StageLP& stage)

Returns Number of LP column bounds modified (0 if unchanged)

Update volume-dependent column bounds when bound_rule is set.

auto gtopt::VolumeRightLP::param_emin(StageUid s) const
#include <gtopt/storage_lp.hpp>

auto gtopt::VolumeRightLP::param_emax(StageUid s) const
#include <gtopt/storage_lp.hpp>

auto gtopt::VolumeRightLP::param_ecost(StageUid s) const
#include <gtopt/storage_lp.hpp>