gtopt::ReservoirLP class
#include <gtopt/reservoir_lp.hpp>

Linear programming representation of a water reservoir.

This class extends StorageLP to provide LP-specific functionality for reservoirs, including:

  • Storage capacity constraints
  • Water extraction constraints
  • Relationships with connected junctions

Base classes

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

Public types

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

Public static variables

static constexpr LPClassName ClassName

Constructors, destructors, conversion operators

ReservoirLP(const Reservoir& preservoir, 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
Adds reservoir constraints to the linear problem.
auto add_to_output(OutputContext& out) const -> bool
Adds reservoir solution variables to the output context.
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 -> constexpr const auto&
Return the extraction column indices for (scenario, stage).
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.
auto junction_sid() const -> constexpr auto noexcept
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 Reservoir&& noexcept
auto object() & -> constexpr Reservoir& noexcept
Gets the wrapped object.
auto object() const && -> constexpr const Reservoir&& noexcept
auto object() const & -> constexpr const Reservoir& 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 reservoir(this auto&& self) -> constexpr auto&& noexcept
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>
auto spillway_capacity() const -> constexpr auto noexcept
auto spillway_cost() const -> constexpr auto noexcept
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

Parameter accessors for user constraint resolution

auto param_capacity(StageUid s) 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::ReservoirLP::object_type = Reservoir
#include <gtopt/object_lp.hpp>

Type of the wrapped object.

Function documentation

bool gtopt::ReservoirLP::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::ReservoirLP::add_to_lp(SystemContext& sc, const ScenarioLP& scenario, const StageLP& stage, LinearProblem& lp)

Adds reservoir constraints to the linear problem.

Parameters
sc System context containing component relationships
scenario Current scenario being processed
stage Current stage being processed
lp Linear problem to add constraints to
Returns true if successful, false on error

Adds constraints for:

  • Water extraction from reservoir
  • Storage capacity limits
  • Connection to junction balance equations

bool gtopt::ReservoirLP::add_to_output(OutputContext& out) const

Adds reservoir solution variables to the output context.

Parameters
out Output context to write results to
Returns true if successful, false on error

Outputs the solution values for:

  • Water extraction flows
  • Storage variables
  • Associated costs

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

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

constexpr const auto& gtopt::ReservoirLP::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::ReservoirLP::efin_col_at(const ScenarioLP& scenario, const StageLP& stage) const
#include <gtopt/storage_lp.hpp>

ColIndex gtopt::ReservoirLP::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::ReservoirLP::energy_cols_at(const ScenarioLP& scenario, const StageLP& stage) const
#include <gtopt/storage_lp.hpp>

constexpr const auto& gtopt::ReservoirLP::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::ReservoirLP::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.

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

Return the extraction column indices for (scenario, stage).

Extraction columns represent the water extraction flow from the reservoir into its connected junction.

constexpr double gtopt::ReservoirLP::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::ReservoirLP::id() const noexcept
#include <gtopt/object_lp.hpp>

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

constexpr auto gtopt::ReservoirLP::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::ReservoirLP::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::ReservoirLP::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::ReservoirLP::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::ReservoirLP::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::ReservoirLP::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::ReservoirLP::lp_label(this const Self& self, SystemContext& sc, const StageLP& stage, Args && ... args)

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

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

Gets the wrapped object.

Returns Reference to the wrapped object

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

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

constexpr double gtopt::ReservoirLP::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::ReservoirLP::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::ReservoirLP::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::ReservoirLP::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::ReservoirLP::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)

constexpr auto& gtopt::ReservoirLP::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::ReservoirLP::short_name(this const Self& self) noexcept
#include <gtopt/object_lp.hpp>

std::optional<ColIndex> gtopt::ReservoirLP::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::ReservoirLP::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::ReservoirLP::state_col_label(this const Self& self, SystemContext& sc, const ScenarioLP& scenario, const StageLP& stage, const BlockLP& block, Args && ... args)

constexpr auto&& gtopt::ReservoirLP::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::ReservoirLP::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::ReservoirLP::sv_key(this const Self& self, const StageLP& stage, std::string_view col_name) noexcept

constexpr double gtopt::ReservoirLP::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::ReservoirLP::uid() const noexcept
#include <gtopt/object_lp.hpp>

Returns The object's unique identifier

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

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

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