Storage Unit - Inputs

Storage units represent energy storage systems that can both charge (withdraw power) and discharge (inject power) at a bus. Below are all input attributes that you can set for storage unit components.

Basic

Attribute	Data Type	Unit	Default	Required	Storage Type	Description
`type`	string	n/a	n/a	No	static	Placeholder for storage unit type. Not yet implemented.
`carrier`	string	n/a	n/a	No	static	Carrier type for the storage unit (e.g. battery, hydro, hydrogen); required for global constraints on primary energy in optimization
`active`	boolean	n/a	True	No	static	Whether this storage unit is active and should be included in network calculations. Set to False to temporarily disable the storage unit without deleting it.

Capacity

Attribute	Data Type	Unit	Default	Required	Storage Type	Description
`p_nom`	float	MW	0	Yes	static	The maximum rated power capacity of the storage unit in MW. This sets the limit for both charging (negative power) and discharging (positive power) in all calculations.
`p_nom_mod`	float	MW	0	No	static	The unit size for capacity expansion. When extending the nominal power (p_nom), it can only be increased in multiples of this module size.
`p_nom_extendable`	boolean	n/a	False	No	static	Switch to allow the nominal power (p_nom) to be extended in optimization.
`p_nom_min`	float	MW	0	No	static	If the nominal power (p_nom) is extendable in optimization, set its minimum value.
`p_nom_max`	float	MW	inf	No	static	If the nominal power (p_nom) is extendable in optimization, set its maximum value (e.g. limited by technical potential).
`build_year`	int	year	0	No	static	The year when the storage unit can be built or commissioned. Essential for multi-year capacity expansion planning models, which determine optimal investment timing and storage unit retirement schedules.
`lifetime`	float	years	inf	No	static	The operational lifetime of the storage unit in years. Essential for multi-year capacity expansion planning models, which use this to determine when storage units retire (build year + lifetime). Set to "inf" for storage units that never retire.

Power Limits

Attribute	Data Type	Unit	Default	Required	Storage Type	Description
`p_min_pu`	float	per unit	-1	No	static or timeseries	The minimum power flow per unit of the nominal power (p_nom). Negative values represent charging (withdrawing power from the bus), positive values represent discharging. Can be static or time-varying.
`p_max_pu`	float	per unit	1	No	static or timeseries	The maximum power flow per unit of the nominal power (p_nom). Positive values represent discharging (injecting power into the bus), negative values represent charging. Can be static or time-varying.
`p_set`	float	MW	0	No	static or timeseries	Fixed active power output that the storage unit must produce (positive for discharging, negative for charging). Used when the power output is predetermined rather than optimized.
`q_set`	float	MVar	0	No	static or timeseries	Fixed reactive power output that the storage unit must produce. Used when the reactive power output is predetermined rather than optimized.
`sign`	float	n/a	1	No	static	Power flow direction convention: 1 for generation/discharging (positive power flows into the network), -1 for consumption/charging (positive power flows out of the network).

Energy

Attribute	Data Type	Unit	Default	Required	Storage Type	Description
`state_of_charge_initial`	float	MWh	0	No	static	The state of charge (energy stored) at the beginning of the optimization period, before the first snapshot. Ignored if cyclic_state_of_charge is True.
`state_of_charge_initial_per_period`	boolean	n/a	False	No	static	If True, the initial state of charge is applied at the beginning of each investment period separately, rather than only at the start of the entire optimization horizon.
`state_of_charge_set`	float	MWh	1	No	static or timeseries	Fixed state of charge values that the storage unit must maintain at specific snapshots. Used when the state of charge is predetermined rather than optimized. Can be static or time-varying.
`cyclic_state_of_charge`	boolean	n/a	False	No	static	If True, the initial state of charge is ignored and the storage unit must end with the same state of charge as it started (cyclic constraint). This ensures the storage unit returns to its initial state at the end of the optimization period.
`cyclic_state_of_charge_per_period`	boolean	n/a	True	No	static	If True, the cyclic state of charge constraint is applied to each investment period separately, rather than only to the entire optimization horizon.
`max_hours`	float	hours	1	No	static	The maximum energy storage capacity expressed as the number of hours the storage unit can discharge at full nominal power (p_nom). The maximum state of charge in MWh equals max_hours × p_nom.
`efficiency_store`	float	per unit	1	No	static or timeseries	The round-trip efficiency for charging (storing energy). A value of 1.0 means no losses, while lower values represent energy losses during charging. Can be time-varying to model temperature-dependent performance.
`efficiency_dispatch`	float	per unit	1	No	static or timeseries	The round-trip efficiency for discharging (releasing stored energy). A value of 1.0 means no losses, while lower values represent energy losses during discharging. Can be time-varying to model temperature-dependent performance.
`standing_loss`	float	per unit	0	No	static or timeseries	The self-discharge rate per hour, expressed as a fraction of the current state of charge. Represents energy losses that occur even when the storage unit is idle (e.g., battery self-discharge, reservoir evaporation). Can be time-varying.
`inflow`	float	MW	0	No	static or timeseries	Natural inflow of energy to the state of charge (e.g., river inflow to a hydro reservoir, solar charging for a battery). Positive values increase the stored energy without drawing power from the bus. Can be static or time-varying.

Costs

Attribute	Data Type	Unit	Default	Required	Storage Type	Description
`spill_cost`	float	currency/MWh	0	No	static or timeseries	The cost of spilling 1 MWh of energy that cannot be stored (e.g., water spillage from a hydro reservoir when the reservoir is full).
`marginal_cost`	float	currency/MWh	0	No	static or timeseries	The variable cost of discharging one additional MWh of electricity. Used by the optimizer to determine the economic dispatch order (lower cost storage units are dispatched first).
`marginal_cost_quadratic`	float	currency/MWh²	0	No	static or timeseries	Quadratic term for non-linear cost curves. When set, the total discharge cost includes a quadratic component that increases with the square of discharge power, modeling increasing marginal costs at higher discharge levels.
`marginal_cost_storage`	float	currency/MWh/h	0	No	static or timeseries	The variable cost of storing 1 MWh of energy for one hour. This represents the opportunity cost or wear-and-tear cost associated with storing energy in the storage unit.
`capital_cost`	float	currency/MW	0	No	static	The cost per MW of adding new storage capacity. Includes investment costs (spread over the planning period) and fixed operations & maintenance costs. Only relevant when p_nom_extendable is True.

Electrical

Attribute	Data Type	Unit	Default	Required	Storage Type	Description
`control`	string	n/a	PQ	No	static	Power flow control mode: "PQ" (fixed active and reactive power), "PV" (fixed active power and voltage magnitude), or "Slack" (balances system power, typically one per network).