BatteryStateful¶
Wrapper for SAM Simulation Core model: cmod_battery_stateful.cpp
Input Consistency Warning¶
As described in Possible Problems, some input parameters are interdependent but the equations that enforce consistency are not available in this PySAM module. Therefore, the onus is on the PySAM user to check that interdependencies are correctly handled. The variables which may require additional logic include:
Provided for each of these inputs is a list of other inputs that are potentially interdependent.
Creating an Instance¶
Refer to the Initializing a Model page for details on the different ways to create an instance of a PySAM class.
BatteryStateful model description
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¶ Use default attributes config options:
- “LFPGraphite”
- “LMOLTO”
- “LeadAcid”
- “NMCGraphite”
-
PySAM.BatteryStateful.from_existing(data, optional config) → BatteryStateful¶ Share underlying data with an existing PySAM class. If config provided, default attributes are loaded otherwise.
-
PySAM.BatteryStateful.new() → BatteryStateful¶
-
PySAM.BatteryStateful.wrap(ssc_data_t) → BatteryStateful¶ Use existing PySSC data
Warning
Do not call PySSC.data_free on the ssc_data_t provided to
wrap
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
-
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) → Union[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: True if control_mode=0
Type: float
-
input_power¶ Power at which to run battery [kW]
Required: True 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: True if voltage_choice=0&chem~2
Type: float
-
Qexp¶ Cell capacity at end of exponential zone [Ah]
Required: True 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: True if voltage_choice=0&chem=3
Type: float
-
Qnom¶ Cell capacity at end of nominal zone [Ah]
Required: True if voltage_choice=0&chem~2
Type: float
-
Vcut¶ Cell cutoff voltage [V]
Required: True if voltage_choice=0&chem~2
Type: float
-
Vexp¶ Cell voltage at end of exponential zone [V]
Required: True if voltage_choice=0&chem~2
Type: float
-
Vfull¶ Fully charged cell voltage [V]
Required: True if voltage_choice=0&chem~2
Type: float
-
Vnom¶ Cell voltage at end of nominal zone [V]
Required: True 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: True if life_model=0&calendar_choice=1
Type: float
-
calendar_b¶ Calendar life model coefficient [K]
Required: True if life_model=0&calendar_choice=1
Type: float
-
calendar_c¶ Calendar life model coefficient [K]
Required: True 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: True if life_model=0
Type: float
-
calendar_matrix¶ Table with Day # and Capacity % columns [[[#, %]]]
Required: True if life_model=0&calendar_choice=2
Type: sequence[sequence]
-
calendar_q0¶ Calendar life model initial capacity cofficient
Required: True 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: True 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: True if chem=0
Type: float
-
leadacid_q20¶ Capacity at 20-hour discharge rate [Ah]
Required: True if chem=0
Type: float
-
leadacid_qn¶ Capacity at discharge rate for n-hour rate [Ah]
Required: True if chem=0
Type: float
-
leadacid_tn¶ Hours to discharge for qn rate [h]
Required: True 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: If not provided, assumed to be 0
Type: float
-
voltage_matrix¶ Table with depth-of-discharge % and Voltage as columns [[[%, V]]]
Required: True 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: True 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: If not provided, assumed to be 0
Type: float
-
mass¶ Battery mass [kg]
Required: True
Type: float
-
monthly_charge_loss¶ Battery system losses when charging [[kW]]
Required: If not provided, assumed to be 0
Type: sequence
-
monthly_discharge_loss¶ Battery system losses when discharging [[kW]]
Required: If not provided, assumed to be 0
Type: sequence
-
monthly_idle_loss¶ Battery system losses when idle [[kW]]
Required: If not provided, assumed to be 0
Type: sequence
-
nominal_energy¶ Nominal installed energy [kWh]
Required: True
Type: float
-
nominal_voltage¶ Nominal DC voltage [V]
Required: True
Type: float
-
replacement_capacity¶ Capacity degradation at which to replace battery [%]
Required: True 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: If not provided, assumed to be 0
Type: float Type: Replacements
-
replacement_schedule_percent¶ Percentage of battery capacity to replace in each year [[%/year]]
Options: length <= analysis_period
Required: True if replacement_option=2
Type: sequence
-
schedule_loss¶ Battery system losses at each timestep [[kW]]
Required: If not provided, assumed to be 0
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]
Type: float
-
I_chargeable¶ Estimated max chargeable current [A]
Type: float
-
I_dischargeable¶ Estimated max dischargeable current [A]
Type: float
-
P¶ Power [kW]
Type: float
-
P_chargeable¶ Estimated max chargeable power [kW]
Type: float
-
P_dischargeable¶ Estimated max dischargeable power [kW]
Type: float
-
Q¶ Capacity [Ah]
Type: float
-
Q_max¶ Max Capacity [Ah]
Type: float
-
SOC¶ State of Charge [%]
Type: float
-
T_batt¶ Battery temperature averaged over time step [C]
Type: float
-
T_room¶ Room temperature [C]
Type: float
-
V¶ Voltage [V]
Type: float
-
heat_dissipated¶ Heat dissipated due to flux [kW]
Type: float
-
indices_replaced¶ Lifetime indices of replacement occurrences
Type: sequence
-
last_idx¶ Last index (lifetime)
Type: float
-
loss_kw¶ Ancillary power loss (kW DC for DC connected, AC for AC connected) [kW]
Type: float
-
n_replacements¶ Number of replacements at current year
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
Type: float
-
DOD_min¶ Min DOD of battery for current day [%]
Info: Cycles for Life Model
Type: float
-
EFC¶ Total Equivalent Full Cycles [1]
Info: LMO/LTO Life Model
Type: float
-
EFC_dt¶ Equivalent Full Cycles cumulated for current day [1]
Info: LMO/LTO Life Model
Type: float
-
I_loss¶ Lifetime and thermal losses [A]
Type: float
-
SOC_prev¶ State of Charge of last time step [%]
Type: float
-
T_batt_prev¶ Battery temperature at end of last time step [C]
Type: float
-
average_range¶ Average cycle cycle_range [%]
Type: float
-
b1_dt¶ b1 coefficient cumulated for current day [day^-0.5]
Info: NMC Life Model
Type: float
-
b2_dt¶ b2 coefficient cumulated for current day [1/cycle]
Info: NMC Life Model
Type: float
-
b3_dt¶ b3 coefficient cumulated for current day [1]
Info: NMC Life Model
Type: float
-
c0_dt¶ c0 coefficient cumulated for current day [Ah]
Info: NMC Life Model
Type: float
-
c2_dt¶ c2 coefficient cumulated for current day [1/cycle]
Info: NMC Life Model
Type: float
-
cell_current¶ Cell current [A]
Type: float
-
cell_voltage¶ Cell voltage [V]
Type: float
-
chargeChange¶ Whether Charge mode changed since last step [0/1]
Type: float
-
charge_mode¶ Charge (0), Idle (1), Discharge (2) [0/1/2]
Type: float
-
cum_dt¶ Elapsed time for current day [day]
Info: Cycles for Life Model
Type: float
-
cycle_DOD¶ cycle_DOD of last cycle [%]
Type: float
-
cycle_DOD_max¶ Max DODs of cycles concluded in current day [%]
Info: Cycles for Life Model
Type: sequence
-
cycle_DOD_range¶ DOD cycle_range of each cycle [%]
Info: NMC Life Model
Type: sequence
-
cycle_range¶ Range of last cycle [%]
Type: float
-
day_age_of_battery¶ Day age of battery [day]
Type: float
-
dq_relative_cal¶ Cumulative capacity change from calendar degradation [%]
Info: LMO/LTO Life Model
Type: float
-
dq_relative_calendar_old¶ Change in capacity of last time step [%]
Type: float
-
dq_relative_cyc¶ Cumulative capacity change from cycling degradation [%]
Info: LMO/LTO Life Model
Type: float
-
dq_relative_li1¶ Cumulative capacity change from time-dependent Li loss [1]
Info: NMC Life Model
Type: float
-
dq_relative_li2¶ Cumulative capacity change from cycle-dependent Li loss [1]
Info: NMC Life Model
Type: float
-
dq_relative_li3¶ Cumulative capacity change from BOL Li loss [1]
Info: NMC Life Model
Type: float
-
dq_relative_neg¶ Cumulative capacity change from negative electrode [1]
Info: NMC Life Model
Type: float
-
n_cycles¶ Number of cycles
Type: float
-
prev_charge¶ Charge mode of last time step [0/1/2]
Type: float
-
q0¶ Cell capacity at timestep [Ah]
Type: float
-
q1_0¶ Lead acid - Cell charge available [Ah]
Type: float
-
q2¶ Lead acid - Cell capacity at 10-hr discharge rate [Ah]
Type: float
-
q2_0¶ Lead acid - Cell charge bound [Ah]
Type: float
-
q_relative¶ Overall relative capacity due to lifetime effects [%]
Type: float
-
q_relative_calendar¶ Relative capacity due to calendar effects [%]
Type: float
-
q_relative_cycle¶ Relative capacity due to cycling effects [%]
Type: float
-
q_relative_li¶ Relative capacity due to loss of lithium inventory [%]
Info: NMC Life Model
Type: float
-
q_relative_neg¶ Relative capacity due to loss of anode material [%]
Info: NMC Life Model
Type: float
-
q_relative_thermal¶ Relative capacity due to thermal effects [%]
Type: float
-
qmax_lifetime¶ Maximum possible cell capacity [Ah]
Type: float
-
qmax_thermal¶ Maximum cell capacity adjusted for temperature effects [Ah]
Type: float
-
qn¶ Lead acid - Cell capacity at n-hr discharge rate [Ah]
Type: float
-
rainflow_Xlt¶ Rainflow cycle_range of second to last half cycle [%]
Type: float
-
rainflow_Ylt¶ Rainflow cycle_range of last half cycle [%]
Type: float
-
rainflow_jlt¶ Rainflow number of turning points
Type: float
-
rainflow_peaks¶ Rainflow peaks of cycle_DOD [[%]]
Type: sequence
-
temp_avg¶ Average temperature for current day [K]
Info: LMO/LTO Life Model
Type: float
-