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