gtopt::Battery struct
#include <gtopt/battery.hpp>

Represents a battery energy storage system (BESS)

A battery can charge (absorb energy) and discharge (deliver energy) within its operational constraints. The state of charge (SoC) is tracked between time blocks, accounting for round-trip efficiency losses.

The energy balance per block is:

SoC[t+1] = SoC[t] × (1 − annual_loss/8760) + input_efficiency × charge
           − discharge / output_efficiency

When the bus field is set, System::expand_batteries() auto-generates the corresponding Generator, Demand, and Converter elements so the user only needs to define a single Battery object. This approach follows the convention used by PyPSA StorageUnit and pandapower storage.

When source_generator is also set, the battery operates in generation-coupled mode: a dedicated internal bus is created for the charge path so that the source generator feeds the battery directly.

Public variables

OptActive active: Activation status (default: active)
OptTRealFieldSched annual_capcost: Annualized investment cost [$/MWh-year].
OptTRealFieldSched annual_derating: Annual capacity derating factor [p.u./year].
OptTRealFieldSched annual_loss: Annual self-discharge rate [p.u./year].
OptSingleId bus
OptTRealFieldSched capacity: Installed energy capacity [MWh].
OptTRealFieldSched capmax: Absolute maximum energy capacity [MWh].
OptBool daily_cycle
OptTRealFieldSched ecost: Storage usage cost (penalty for SoC) [$/MWh].
OptReal efin
OptReal eini
OptTRealFieldSched emax: Maximum state of charge (usable capacity) [MWh].
OptTRealFieldSched emin: Minimum state of charge [MWh].
OptReal energy_scale
OptTRealFieldSched expcap: Energy capacity per expansion module [MWh].
OptTRealFieldSched expmod: Maximum number of expansion modules [dimensionless].
OptTRealFieldSched gcost: Discharge generation cost [$/MWh] (unified definition)
OptTRealFieldSched input_efficiency: Charging efficiency [p.u.].
Name name: Human-readable battery name.
OptTRealFieldSched output_efficiency: Discharging efficiency [p.u.].
OptTRealFieldSched pmax_charge: Max charging power [MW] (unified definition)
OptTRealFieldSched pmax_discharge: Max discharging power [MW] (unified definition)
OptTRealFieldSched soft_emin
OptTRealFieldSched soft_emin_cost
OptSingleId source_generator
OptName type: Optional battery type tag (e.g. "li-ion", "flow", "pumped")
Uid uid: Unique identifier.
OptBool use_state_variable

Default physical constants

static constexpr Real default_energy_scale: [dimensionless]

Variable documentation

OptSingleId gtopt::Battery::bus

External bus connection for the unified battery definition. When set, System::expand_batteries() auto-generates a discharge Generator, a charge Demand, and a linking Converter.

OptBool gtopt::Battery::daily_cycle

Enable PLP-style daily cycle operation: block durations in the energy balance are scaled by 24/stage_duration so that emin/emax constraints represent a daily cycle regardless of the stage length. Implies decoupled stage/phase behaviour (use_state_variable forced false). Default for batteries is true (enabled); can be disabled explicitly.

OptReal gtopt::Battery::efin

Minimum required terminal state of charge [MWh]. Sets a >= constraint SoC_end >= efin in the last stage of the last phase (not an equality).

OptReal gtopt::Battery::eini

Initial state of charge [MWh]. Sets an equality constraint SoC_start = eini in the first stage of the first phase only.

OptReal gtopt::Battery::energy_scale

Energy scale factor: the LP energy variable is divided by this value so that the LP works in scaled units (physical_energy / energy_scale). Default is 1.0 (no scaling). Output values are rescaled back to physical units so results are invariant to the choice of energy_scale.

OptTRealFieldSched gtopt::Battery::soft_emin

Soft minimum SoC per stage [MWh]. Creates a penalized constraint: efin + slack >= soft_emin.

OptTRealFieldSched gtopt::Battery::soft_emin_cost

Penalty cost per unit of soft_emin violation [$/MWh].

OptSingleId gtopt::Battery::source_generator

Optional reference to a co-located generator that directly charges the battery (generation-coupled / hybrid battery configuration). When set together with bus, expand_batteries() creates an internal bus so that:

The discharge Generator connects to the external bus
The charge Demand connects to the internal bus
The source generator's bus is set to the internal bus The source generator's own bus field is overwritten. Without source_generator the battery is standalone: both charge and discharge connect to the same external bus.

OptBool gtopt::Battery::use_state_variable

Whether to propagate SoC state across stage/phase boundaries via StateVariables (SDDP-style coupling). When false (the default for batteries), each phase is solved independently with no state carry-over; an efin==eini constraint is added automatically to close each phase.