gtopt::BatteryLP class
#include <gtopt/battery_lp.hpp>

Linear programming representation of a battery energy storage system.

This class provides the LP formulation for battery models, including:

  • Energy balance constraints
  • State of charge tracking
  • Charge/discharge limits
  • Capacity constraints

Base classes

template<typename Object Object>
class StorageLP<CapacityObjectLP<Battery>>

Public types

using Base = ObjectLP<Battery>
using CapacityAndCol = std::pair<std::optional<double>, std::optional<ColIndex>>
Pair of optional capacity value and optional expansion column index.
using CapacityBase = CapacityObjectLP<Battery>
using object_type = ObjectType
Type of the wrapped object.
using StorageBase = StorageLP<CapacityObjectLP<Battery>>

Public static variables

static constexpr LPClassName ClassName

Constructors, destructors, conversion operators

BatteryLP(const Battery& pbattery, const InputContext& ic) explicit
Constructs a BatteryLP from a Battery object.

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 battery variables and constraints to the linear problem.
auto add_to_output(OutputContext& out) const -> bool
Adds battery output results to the output context.
auto add_to_output(OutputContext& out, std::string_view cname) const -> bool
auto battery(this auto&& self) -> constexpr auto&& noexcept
Access the underlying battery object (non-const)
auto capacity_and_col(const StageLP& stage, LinearProblem& lp) const -> CapacityAndCol -> constexpr auto
Query capacity value and optional expansion column for a stage.
auto capacity_at(const StageLP& stage, const double def_capacity = std::numeric_limits<double>::max()) const -> constexpr double
Get the capacity at a specific stage.
auto capacity_col_at(const StageLP& stage) const -> constexpr auto noexcept
Get the column index for capacity at a specific stage.
template<typename Self Self>
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 finp_cols_at(const ScenarioLP& scenario, const StageLP& stage) const -> constexpr auto&&
Gets the flow variables for a specific scenario and stage.
auto flow_scale() const -> constexpr double noexcept
auto fout_cols_at(const ScenarioLP& scenario, const StageLP& stage) const -> constexpr auto&&
auto id() const -> constexpr const Id& noexcept
auto id() const -> constexpr auto noexcept
auto id(this const Self& self) -> constexpr auto noexcept
Gets the object's identifier (explicit object syntax)
template<typename StageLP StageLP>
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 ObjectType&& noexcept
auto object() & -> constexpr ObjectType& noexcept
Gets the wrapped object.
auto object() const && -> constexpr const ObjectType&& noexcept
auto object() const & -> constexpr const ObjectType& 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 set_id(Uid uid, Name name) -> constexpr auto& noexcept
Sets the object's identifier.
template<typename Self Self>
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 uid() const -> constexpr auto noexcept

Parameter accessors for user constraint resolution

auto param_input_efficiency(StageUid s) const -> auto
auto param_output_efficiency(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::BatteryLP::Base = ObjectLP<Battery>
#include <gtopt/capacity_object_lp.hpp>

using gtopt::BatteryLP::CapacityAndCol = std::pair<std::optional<double>, std::optional<ColIndex>>
#include <gtopt/capacity_object_lp.hpp>

Pair of optional capacity value and optional expansion column index.

using gtopt::BatteryLP::object_type = ObjectType
#include <gtopt/object_lp.hpp>

Type of the wrapped object.

Function documentation

gtopt::BatteryLP::BatteryLP(const Battery& pbattery, const InputContext& ic) explicit

Constructs a BatteryLP from a Battery object.

Parameters
pbattery Battery object to convert to LP representation
ic Input context for parameter processing

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

Adds battery variables and constraints to the linear problem.

Parameters
sc System context containing current state
scenario Current scenario LP object.
stage Current stage LP object.
lp Linear problem to add variables and constraints to
Returns True if successful, false otherwise

This method creates:

  1. Flow variables for each time block (can be positive for discharge or negative for charge)
  2. State of charge tracking constraints between time blocks
  3. Capacity constraints linking battery operation to installed capacity

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

Adds battery output results to the output context.

Parameters
out Output context to add results to
Returns True if successful, false otherwise

Processes planning results for:

  • Finp variables (charge/discharge decisions)
  • Storage levels
  • Capacity-related outputs

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

constexpr auto&& gtopt::BatteryLP::battery(this auto&& self) noexcept

Access the underlying battery object (non-const)

Returns Reference to the battery object

constexpr auto gtopt::BatteryLP::capacity_and_col(const StageLP& stage, LinearProblem& lp) const -> CapacityAndCol
#include <gtopt/capacity_object_lp.hpp>

Query capacity value and optional expansion column for a stage.

Parameters
stage The stage to query
lp Linear problem reference (needed for expansion col bounds)

Returns {std::optional<double>, std::optional<ColIndex>}. The capacity is nullopt when no expansion column exists AND no capacity schedule value is defined — i.e. when the physical capacity is truly undefined. Callers that need a numeric fallback should use value_or(default) on the returned optional.

constexpr double gtopt::BatteryLP::capacity_at(const StageLP& stage, const double def_capacity = std::numeric_limits<double>::max()) const
#include <gtopt/capacity_object_lp.hpp>

Get the capacity at a specific stage.

Parameters
stage The stage to query capacity for
def_capacity Default value if capacity not specified (default: unlimited)
Returns The capacity at given stage or default if not specified

constexpr auto gtopt::BatteryLP::capacity_col_at(const StageLP& stage) const noexcept
#include <gtopt/capacity_object_lp.hpp>

Get the column index for capacity at a specific stage.

Parameters
stage The stage to get column index for
Returns Optional containing column index if exists

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

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

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

constexpr const auto& gtopt::BatteryLP::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::BatteryLP::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 auto&& gtopt::BatteryLP::finp_cols_at(const ScenarioLP& scenario, const StageLP& stage) const

Gets the flow variables for a specific scenario and stage.

Returns Reference to the flow variables

constexpr double gtopt::BatteryLP::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 const Id& gtopt::BatteryLP::id() const noexcept
#include <gtopt/capacity_object_lp.hpp>

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

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

constexpr auto gtopt::BatteryLP::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

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

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

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

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

Gets the wrapped object.

Returns Reference to the wrapped object

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

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

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

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

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

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

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

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

Returns The object's unique identifier

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

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

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