BatteryStateful

BatteryStateful has two major differences from the Battery module: 1) it contains only the “physical” component models of the battery (thermal, voltage, capacity, lifetime) and none of the dispatch methods (peak shaving, etc) of the Battery module; 2) the Battery module runs annual or multi-year simulations in a single execution, whereas BatteryStateful is run one timestep at a time using control variables, current or power, and can be run at sub-minute timesteps.

PySAM.BatteryStateful.default(config) → BatteryStateful

Load defaults for the configuration config. Available configurations are:

“LFPGraphite”

“LMOLTO”

“LeadAcid”

“NMCGraphite”

Note

Some inputs do not have default values and may be assigned a value from the variable’s Required attribute. See variable attribute descriptions below.

PySAM.BatteryStateful.from_existing(data, optional config) → BatteryStateful: Share data with an existing PySAM class. If optional config is a valid configuration name, load the module’s defaults for that configuration.

PySAM.BatteryStateful.new() → BatteryStateful

PySAM.BatteryStateful.wrap(ssc_data_t) → BatteryStateful: Load data from a PySSC object.

Warning

Do not call PySSC.data_free on the ssc_data_t provided to wrap()

BatteryStateful is a wrapper for the SSC compute module cmod_battery_stateful.cpp

Interdependent Variables

The variables listed below are interdependent with other variables. If you change the value of one of these variables, you may need to change values of other variables. The SAM user interface manages these interdependent variables, but in PySAM, it is up to you change the value of all interdependent variables so they are consistent. See Interdependent Variables for examples and details.

None

Functions

class PySAM.BatteryStateful.BatteryStateful

This class contains all the variable information for running a simulation. Variables are grouped together in the subclasses as properties. If property assignments are the wrong type, an error is thrown.

assign(dict) → None

Assign attributes from nested dictionary, except for Outputs

nested_dict = { 'Controls': { var: val, ...}, ...}

execute(int verbosity) → None: Execute simulation with verbosity level 0 (default) or 1

export() → dict: Export attributes into nested dictionary

get_data_ptr() → Pointer: Get ssc_data_t pointer

replace(dict) → None

Replace attributes from nested dictionary, except for Outputs. Unassigns all values in each Group then assigns from the input dict.

nested_dict = { 'Controls': { var: val, ...}, ...}

setup() → None: Setup parameters in simulation

unassign(name) → None: Unassign a value in any of the variable groups.

value(name, optional value) → None | float | dict | sequence | str: Get or set by name a value in any of the variable groups.

Controls Group

class PySAM.BatteryStateful.BatteryStateful.Controls

assign(dict) → None

Assign attributes from dictionary, overwriting but not removing values.

Controls_vals = { var: val, ...}

export() → dict: Export attributes into dictionary.

replace(dict) → None

Replace attributes from dictionary, unassigning values not present in input dict.

Controls_vals = { var: val, ...}

control_mode

Control using current (0) or power (1) [0/1]

Required: True

Type:: float

dt_hr

Time step in hours [hr]

Required: True

Type:: float

input_current

Current at which to run battery [A]

Required: Required if control_mode=0

Type:: float

input_power

Power at which to run battery [kW]

Required: Required if control_mode=1

Type:: float

ParamsCell Group

class PySAM.BatteryStateful.BatteryStateful.ParamsCell

assign(dict) → None

Assign attributes from dictionary, overwriting but not removing values.

ParamsCell_vals = { var: val, ...}

export() → dict: Export attributes into dictionary.

replace(dict) → None

Replace attributes from dictionary, unassigning values not present in input dict.

ParamsCell_vals = { var: val, ...}

C_rate

Rate at which voltage vs. capacity curve input

Required: Required if voltage_choice=0&chem~2

Type:: float

Qexp

Cell capacity at end of exponential zone [Ah]

Required: Required if voltage_choice=0&chem~2

Type:: float

Qfull

Fully charged cell capacity [Ah]

Required: True

Type:: float

Qfull_flow

Fully charged flow battery capacity [Ah]

Required: Required if voltage_choice=0&chem=3

Type:: float

Qnom

Cell capacity at end of nominal zone [Ah]

Required: Required if voltage_choice=0&chem~2

Type:: float

Vcut

Cell cutoff voltage [V]

Required: Required if voltage_choice=0&chem~2

Type:: float

Vexp

Cell voltage at end of exponential zone [V]

Required: Required if voltage_choice=0&chem~2

Type:: float

Vfull

Fully charged cell voltage [V]

Required: Required if voltage_choice=0&chem~2

Type:: float

Vnom

Cell voltage at end of nominal zone [V]

Required: Required if voltage_choice=0&chem~2

Type:: float

Vnom_default

Default nominal cell voltage [V]

Required: True

Type:: float

calendar_a

Calendar life model coefficient [1/sqrt(day)]

Required: Required if life_model=0&calendar_choice=1

Type:: float

calendar_b

Calendar life model coefficient [K]

Required: Required if life_model=0&calendar_choice=1

Type:: float

calendar_c

Calendar life model coefficient [K]

Required: Required if life_model=0&calendar_choice=1

Type:: float

calendar_choice

Calendar life degradation input option [0/1/2]

Options: 0=None,1=LithiumIonModel,2=InputLossTable

Required: Required if life_model=0

Type:: float

calendar_matrix

Table with Day # and Capacity % columns [[[#, %]]]

Required: Required if life_model=0&calendar_choice=2

Type:: sequence[sequence]

calendar_q0

Calendar life model initial capacity cofficient

Required: Required if life_model=0&calendar_choice=1

Type:: float

chem

Lead Acid (0), Li Ion (1), Vanadium Redox (2), Iron Flow (3) [0/1/2/3]

Required: True

Type:: float

cycling_matrix

Table with DOD %, Cycle #, and Capacity % columns [[[%, #, %]]]

Required: Required if life_model=0

Type:: sequence[sequence]

initial_SOC

Initial state-of-charge [%]

Required: True

Type:: float

leadacid_q10

Capacity at 10-hour discharge rate [Ah]

Required: Required if chem=0

Type:: float

leadacid_q20

Capacity at 20-hour discharge rate [Ah]

Required: Required if chem=0

Type:: float

leadacid_qn

Capacity at discharge rate for n-hour rate [Ah]

Required: Required if chem=0

Type:: float

leadacid_tn

Hours to discharge for qn rate [h]

Required: Required if chem=0

Type:: float

life_model

Battery life model specifier [0/1/2]

Options: 0=calendar/cycle,1=NMC,2=LMO/LTO

Required: True

Type:: float

maximum_SOC

Maximum allowed state-of-charge [%]

Required: True

Type:: float

minimum_SOC

Minimum allowed state-of-charge [%]

Required: True

Type:: float

resistance

Internal resistance [Ohm]

Required: True

Type:: float

voltage_choice

Battery voltage input option [0/1]

Options: 0=Model,1=Table

Required: False. Automatically set to 0 if not assigned explicitly or loaded from defaults.

Type:: float

voltage_matrix

Table with depth-of-discharge % and Voltage as columns [[[%, V]]]

Required: Required if voltage_choice=1

Type:: sequence[sequence]

ParamsPack Group

class PySAM.BatteryStateful.BatteryStateful.ParamsPack

assign(dict) → None

Assign attributes from dictionary, overwriting but not removing values.

ParamsPack_vals = { var: val, ...}

export() → dict: Export attributes into dictionary.

replace(dict) → None

Replace attributes from dictionary, unassigning values not present in input dict.

ParamsPack_vals = { var: val, ...}

Cp

Battery specific heat capacity [J/KgK]

Required: True

Type:: float

T_room_init

Temperature of storage room [C]

Required: True

Type:: float

cap_vs_temp

Table with Temperature and Capacity % as columns [[[C,%]]]

Required: Required if life_model=0

Type:: sequence[sequence]

h

Heat transfer between battery and environment [W/m2K]

Required: True

Type:: float

loss_choice

Loss power input option [0/1]

Options: 0=Monthly,1=TimeSeries

Required: False. Automatically set to 0 if not assigned explicitly or loaded from defaults.

Type:: float

mass

Battery mass [kg]

Required: True

Type:: float

monthly_charge_loss

Battery system losses when charging [[kW]]

Required: False. Automatically set to 0 if not assigned explicitly or loaded from defaults.

Type:: sequence

monthly_discharge_loss

Battery system losses when discharging [[kW]]

Required: False. Automatically set to 0 if not assigned explicitly or loaded from defaults.

Type:: sequence

monthly_idle_loss

Battery system losses when idle [[kW]]

Required: False. Automatically set to 0 if not assigned explicitly or loaded from defaults.

Type:: sequence

nominal_energy

Nominal installed energy [kWh]

INOUT: This variable is both an input and an output to the compute module.

Required: True

Type:: float

nominal_voltage

Nominal DC voltage [V]

INOUT: This variable is both an input and an output to the compute module.

Required: True

Type:: float

replacement_capacity

Capacity degradation at which to replace battery [%]

Required: Required if replacement_option=1

Type:: float

replacement_option

none (0), by capacity (1), or schedule (2) [0=none,1=capacity limit,2=yearly schedule]

Constraints: INTEGER,MIN=0,MAX=2

Required: False. Automatically set to 0 if not assigned explicitly or loaded from defaults.

Type:: float
Type:: Replacements

replacement_schedule_percent

Percentage of battery capacity to replace in each year [[%/year]]

Options: length <= analysis_period

Required: Required if replacement_option=2

Type:: sequence

schedule_loss

Battery system losses at each timestep [[kW]]

Required: False. Automatically set to 0 if not assigned explicitly or loaded from defaults.

Type:: sequence

surface_area

Battery surface area [m^2]

Required: True

Type:: float

StatePack Group

class PySAM.BatteryStateful.BatteryStateful.StatePack

assign(dict) → None

Assign attributes from dictionary, overwriting but not removing values.

StatePack_vals = { var: val, ...}

export() → dict: Export attributes into dictionary.

replace(dict) → None

Replace attributes from dictionary, unassigning values not present in input dict.

StatePack_vals = { var: val, ...}

I

Current [A]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

I_chargeable

Estimated max chargeable current [A]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

I_dischargeable

Estimated max dischargeable current [A]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

P

Power [kW]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

P_chargeable

Estimated max chargeable power [kW]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

P_dischargeable

Estimated max dischargeable power [kW]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

Q

Capacity [Ah]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

Q_max

Max Capacity [Ah]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

SOC

State of Charge [%]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

T_batt

Battery temperature averaged over time step [C]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

T_room

Room temperature [C]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

V

Voltage [V]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

heat_dissipated

Heat dissipated due to flux [kW]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

indices_replaced

Lifetime indices of replacement occurrences

INOUT: This variable is both an input and an output to the compute module.

Type:: sequence

last_idx

Last index (lifetime)

INOUT: This variable is both an input and an output to the compute module.

Type:: float

loss_kw

Ancillary power loss (kW DC for DC connected, AC for AC connected) [kW]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

n_replacements

Number of replacements at current year

INOUT: This variable is both an input and an output to the compute module.

Type:: float

StateCell Group

class PySAM.BatteryStateful.BatteryStateful.StateCell

assign(dict) → None

Assign attributes from dictionary, overwriting but not removing values.

StateCell_vals = { var: val, ...}

export() → dict: Export attributes into dictionary.

replace(dict) → None

Replace attributes from dictionary, unassigning values not present in input dict.

StateCell_vals = { var: val, ...}

DOD_max

Max DOD of battery for current day [%]

Info: Cycles for Life Model

INOUT: This variable is both an input and an output to the compute module.

Type:: float

DOD_min

Min DOD of battery for current day [%]

Info: Cycles for Life Model

INOUT: This variable is both an input and an output to the compute module.

Type:: float

EFC

Total Equivalent Full Cycles [1]

Info: LMO/LTO Life Model

INOUT: This variable is both an input and an output to the compute module.

Type:: float

EFC_dt

Equivalent Full Cycles cumulated for current day [1]

Info: LMO/LTO Life Model

INOUT: This variable is both an input and an output to the compute module.

Type:: float

I_loss

Lifetime and thermal losses [A]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

SOC_prev

State of Charge of last time step [%]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

T_batt_prev

Battery temperature at end of last time step [C]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

average_range

Average cycle cycle_range [%]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

b1_dt

b1 coefficient cumulated for current day [day^-0.5]

Info: NMC Life Model

INOUT: This variable is both an input and an output to the compute module.

Type:: float

b2_dt

b2 coefficient cumulated for current day [1/cycle]

Info: NMC Life Model

INOUT: This variable is both an input and an output to the compute module.

Type:: float

b3_dt

b3 coefficient cumulated for current day [1]

Info: NMC Life Model

INOUT: This variable is both an input and an output to the compute module.

Type:: float

c0_dt

c0 coefficient cumulated for current day [Ah]

Info: NMC Life Model

INOUT: This variable is both an input and an output to the compute module.

Type:: float

c2_dt

c2 coefficient cumulated for current day [1/cycle]

Info: NMC Life Model

INOUT: This variable is both an input and an output to the compute module.

Type:: float

cell_current

Cell current [A]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

cell_voltage

Cell voltage [V]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

chargeChange

Whether Charge mode changed since last step [0/1]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

charge_mode

Charge (0), Idle (1), Discharge (2) [0/1/2]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

cum_dt

Elapsed time for current day [day]

Info: Cycles for Life Model

INOUT: This variable is both an input and an output to the compute module.

Type:: float

cycle_DOD

cycle_DOD of last cycle [%]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

cycle_DOD_max

Max DODs of cycles concluded in current day [%]

Info: Cycles for Life Model

INOUT: This variable is both an input and an output to the compute module.

Type:: sequence

cycle_counts

Counts of cycles by DOD [[%, cycles]]

Options: If life_model=0, counts all cycles in simulation; else, cycles per day

INOUT: This variable is both an input and an output to the compute module.

Type:: sequence[sequence]

cycle_range

Range of last cycle [%]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

day_age_of_battery

Day age of battery [day]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

dq_relative_cal

Cumulative capacity change from calendar degradation [%]

Info: LMO/LTO Life Model

INOUT: This variable is both an input and an output to the compute module.

Type:: float

dq_relative_calendar_old

Change in capacity of last time step [%]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

dq_relative_cyc

Cumulative capacity change from cycling degradation [%]

Info: LMO/LTO Life Model

INOUT: This variable is both an input and an output to the compute module.

Type:: float

dq_relative_li1

Cumulative capacity change from time-dependent Li loss [1]

Info: NMC Life Model

INOUT: This variable is both an input and an output to the compute module.

Type:: float

dq_relative_li2

Cumulative capacity change from cycle-dependent Li loss [1]

Info: NMC Life Model

INOUT: This variable is both an input and an output to the compute module.

Type:: float

dq_relative_li3

Cumulative capacity change from BOL Li loss [1]

Info: NMC Life Model

INOUT: This variable is both an input and an output to the compute module.

Type:: float

dq_relative_neg

Cumulative capacity change from negative electrode [1]

Info: NMC Life Model

INOUT: This variable is both an input and an output to the compute module.

Type:: float

n_cycles

Number of cycles

INOUT: This variable is both an input and an output to the compute module.

Type:: float

prev_charge

Charge mode of last time step [0/1/2]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

q0

Cell capacity at timestep [Ah]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

q1_0

Lead acid - Cell charge available [Ah]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

q2

Lead acid - Cell capacity at 10-hr discharge rate [Ah]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

q2_0

Lead acid - Cell charge bound [Ah]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

q_relative

Overall relative capacity due to lifetime effects [%]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

q_relative_calendar

Relative capacity due to calendar effects [%]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

q_relative_cycle

Relative capacity due to cycling effects [%]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

q_relative_li

Relative capacity due to loss of lithium inventory [%]

Info: NMC Life Model

INOUT: This variable is both an input and an output to the compute module.

Type:: float

q_relative_neg

Relative capacity due to loss of anode material [%]

Info: NMC Life Model

INOUT: This variable is both an input and an output to the compute module.

Type:: float

q_relative_thermal

Relative capacity due to thermal effects [%]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

qmax_lifetime

Maximum possible cell capacity [Ah]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

qmax_thermal

Maximum cell capacity adjusted for temperature effects [Ah]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

qn

Lead acid - Cell capacity at n-hr discharge rate [Ah]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

rainflow_Xlt

Rainflow cycle_range of second to last half cycle [%]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

rainflow_Ylt

Rainflow cycle_range of last half cycle [%]

INOUT: This variable is both an input and an output to the compute module.

Type:: float

rainflow_jlt

Rainflow number of turning points

INOUT: This variable is both an input and an output to the compute module.

Type:: float

rainflow_peaks

Rainflow peaks of cycle_DOD [[%]]

INOUT: This variable is both an input and an output to the compute module.

Type:: sequence

temp_avg

Average temperature for current day [K]

Info: LMO/LTO Life Model

INOUT: This variable is both an input and an output to the compute module.

Type:: float

temp_dt

Temperature cumulated for current day [K]

Info: NMC Life Model

INOUT: This variable is both an input and an output to the compute module.

Type:: float