Battery¶

Wrapper for SAM Simulation Core model: cmod_battery.cpp

Creating an Instance¶

There are three methods to create a new instance of a PySAM module. Using default populates the newclass’ attributes with default values specific to a config. Each technology-financialconfiguration corresponds to a SAM GUI configuration. Using new creates an instance with empty attributes. The wrap function allows compatibility with PySSC, for details, refer to PySSC.

StandAloneBattery model description

Detailed battery storage model

PySAM.StandAloneBattery.default(config) → StandAloneBattery¶

Use financial model-specific default attributes config options:

“BatteryNone”
“FuelCellCommercial”
“FuelCellSingleOwner”
“GenericSystemAllEquityPartnershipFlip”
“GenericSystemCommercial”
“GenericSystemCommercialPPA”
“GenericSystemHostDeveloper”
“GenericSystemIndependentPowerProducer”
“GenericSystemLeveragedPartnershipFlip”
“GenericSystemResidential”
“GenericSystemSaleLeaseback”
“GenericSystemSingleOwner”
“GenericSystemThirdParty”

PySAM.StandAloneBattery.new() → StandAloneBattery¶

PySAM.StandAloneBattery.wrap(ssc_data_t) → StandAloneBattery¶: Use existing PySSC data

Warning

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

Functions¶

class PySAM.StandAloneBattery.StandAloneBattery¶

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 = { 'Simulation': { var: val, ...}, ...}

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

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

Simulation Group¶

class PySAM.StandAloneBattery.StandAloneBattery.Simulation¶

assign() → None¶

Assign attributes from dictionary

Simulation_vals = { var: val, ...}

export() → dict¶: Export attributes into dictionary

analysis_period¶

float: Lifetime analysis period [years]

Info: The number of years in the simulation

Required: set to 1 if not provided.

percent_complete¶: float: Estimated simulation status [%]

system_use_lifetime_output¶

float: Lifetime simulation [0/1]

Options: 0=SingleYearRepeated,1=RunEveryYear

Constraints: BOOLEAN

Required: set to 0 if not provided.

Battery Group¶

class PySAM.StandAloneBattery.StandAloneBattery.Battery¶

assign() → None¶

Assign attributes from dictionary

Battery_vals = { var: val, ...}

export() → dict¶: Export attributes into dictionary

LeadAcid_q10_computed¶: float: Capacity at 10-hour discharge rate [Ah]

LeadAcid_q20_computed¶: float: Capacity at 20-hour discharge rate [Ah]

LeadAcid_qn_computed¶: float: Capacity at discharge rate for n-hour rate [Ah]

LeadAcid_tn¶: float: Time to discharge [h]

annual_energy¶

float: Annual Energy [kWh]

Required: set to 0 if not provided.

batt_C_rate¶: float: Rate at which voltage vs. capacity curve input

batt_Cp¶: float: Battery specific heat capacity [J/KgK]

batt_Qexp¶: float: Cell capacity at end of exponential zone [Ah]

batt_Qfull¶: float: Fully charged cell capacity [Ah]

batt_Qfull_flow¶: float: Fully charged flow battery capacity [Ah]

batt_Qnom¶: float: Cell capacity at end of nominal zone [Ah]

batt_Vexp¶: float: Cell voltage at end of exponential zone [V]

batt_Vfull¶: float: Fully charged cell voltage [V]

batt_Vnom¶: float: Cell voltage at end of nominal zone [V]

batt_Vnom_default¶: float: Default nominal cell voltage [V]

batt_ac_dc_efficiency¶: float: Inverter AC to battery DC efficiency

batt_ac_or_dc¶

float: Battery interconnection (AC or DC)

Options: 0=DC_Connected,1=AC_Connected

batt_auto_gridcharge_max_daily¶: float: Allowed grid charging percent per day for automated dispatch [kW]

batt_calendar_a¶: float: Calendar life model coefficient [1/sqrt(day)]

batt_calendar_b¶: float: Calendar life model coefficient [K]

batt_calendar_c¶: float: Calendar life model coefficient [K]

batt_calendar_choice¶

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

Options: 0=NoCalendarDegradation,1=LithiomIonModel,2=InputLossTable

batt_calendar_lifetime_matrix¶: sequence[sequence]: Days vs capacity

batt_calendar_q0¶: float: Calendar life model initial capacity cofficient

batt_chem¶

float: Battery chemistry

Options: 0=LeadAcid,1=LiIon

batt_computed_bank_capacity¶: float: Computed bank capacity [kWh]

batt_computed_series¶: float: Number of cells in series

batt_computed_strings¶: float: Number of strings of cells

batt_current_charge_max¶: float: Maximum charge current [A]

batt_current_choice¶: float: Limit cells by current or power

batt_current_discharge_max¶: float: Maximum discharge current [A]

batt_custom_dispatch¶

sequence: Custom battery power for every time step [kW]

Required: set to 1&batt_dispatch_choice=3 if not provided.

batt_cycle_cost¶: float: Input battery cycle costs [$/cycle-kWh]

batt_cycle_cost_choice¶

float: Use SAM model for cycle costs or input custom [0/1]

Options: 0=UseCostModel,1=InputCost

batt_dc_ac_efficiency¶: float: Battery DC to AC efficiency

batt_dc_dc_efficiency¶: float: PV DC to battery DC efficiency

batt_dispatch_auto_can_charge¶: float: PV charging allowed for automated dispatch? [kW]

batt_dispatch_auto_can_clipcharge¶: float: Battery can charge from clipped PV for automated dispatch? [kW]

batt_dispatch_auto_can_fuelcellcharge¶: float: Charging from fuel cell allowed for automated dispatch? [kW]

batt_dispatch_auto_can_gridcharge¶: float: Grid charging allowed for automated dispatch? [kW]

batt_dispatch_choice¶

float: Battery dispatch algorithm [0/1/2/3/4]

Options: If behind the meter: 0=PeakShavingLookAhead,1=PeakShavingLookBehind,2=InputGridTarget,3=InputBatteryPower,4=ManualDispatch, if front of meter: 0=AutomatedLookAhead,1=AutomatedLookBehind,2=AutomatedInputForecast,3=InputBatteryPower,4=ManualDispatch

Required: set to 1 if not provided.

batt_dispatch_update_frequency_hours¶: float: Frequency to update the look-ahead dispatch [hours]

batt_h_to_ambient¶: float: Heat transfer between battery and environment [W/m2K]

batt_height¶: float: Battery height [m]

batt_initial_SOC¶: float: Initial state-of-charge [%]

batt_length¶: float: Battery length [m]

batt_lifetime_matrix¶: sequence[sequence]: Cycles vs capacity at different depths-of-discharge

batt_look_ahead_hours¶: float: Hours to look ahead in automated dispatch [hours]

batt_loss_choice¶

float: Loss power input option [0/1]

Options: 0=Monthly,1=TimeSeries

Required: set to 0 if not provided.

batt_losses¶

sequence: Battery system losses at each timestep [kW]

Required: set to 0 if not provided.

batt_losses_charging¶

sequence: Battery system losses when charging [kW]

Required: set to 0 if not provided.

batt_losses_discharging¶

sequence: Battery system losses when discharging [kW]

Required: set to 0 if not provided.

batt_losses_idle¶

sequence: Battery system losses when idle [kW]

Required: set to 0 if not provided.

batt_mass¶: float: Battery mass [kg]

batt_maximum_SOC¶: float: Maximum allowed state-of-charge [%]

batt_meter_position¶

float: Position of battery relative to electric meter

Options: 0=BehindTheMeter,1=FrontOfMeter

batt_minimum_SOC¶: float: Minimum allowed state-of-charge [%]

batt_minimum_modetime¶: float: Minimum time at charge state [min]

batt_power_charge_max¶: float: Maximum charge power [kW]

batt_power_discharge_max¶: float: Maximum discharge power [kW]

batt_pv_clipping_forecast¶

sequence: PV clipping forecast [kW]

Required: set to 1&batt_meter_position=1&batt_dispatch_choice=2 if not provided.

batt_pv_dc_forecast¶

sequence: PV dc power forecast [kW]

Required: set to 1&batt_meter_position=1&batt_dispatch_choice=2 if not provided.

batt_replacement_capacity¶: float: Capacity degradation at which to replace battery [%]

batt_replacement_option¶

float: Enable battery replacement? [0=none,1=capacity based,2=user schedule]

Constraints: INTEGER,MIN=0,MAX=2

Required: set to 0 if not provided.

batt_replacement_schedule¶

sequence: Battery bank replacements per year (user specified) [number/year]

Required: set to 2 if not provided.

batt_resistance¶: float: Internal resistance [Ohm]

batt_room_temperature_celsius¶: sequence: Temperature of storage room [C]

batt_target_choice¶

float: Target power input option [0/1]

Options: 0=InputMonthlyTarget,1=InputFullTimeSeries

Required: set to 1&batt_meter_position=0&batt_dispatch_choice=2 if not provided.

batt_target_power¶

sequence: Grid target power for every time step [kW]

Required: set to 1&batt_meter_position=0&batt_dispatch_choice=2 if not provided.

batt_target_power_monthly¶

sequence: Grid target power on monthly basis [kW]

Required: set to 1&batt_meter_position=0&batt_dispatch_choice=2 if not provided.

batt_voltage_choice¶

float: Battery voltage input option [0/1]

Options: 0=UseVoltageModel,1=InputVoltageTable

Required: set to 0 if not provided.

batt_voltage_matrix¶: sequence[sequence]: Battery voltage vs. depth-of-discharge

batt_width¶: float: Battery width [m]

cap_vs_temp¶: sequence[sequence]: Effective capacity as function of temperature [C,%]

dispatch_manual_charge¶

sequence: Periods 1-6 charging from system allowed?

Required: set to 1&batt_dispatch_choice=4 if not provided.

dispatch_manual_discharge¶

sequence: Periods 1-6 discharging allowed?

Required: set to 1&batt_dispatch_choice=4 if not provided.

dispatch_manual_gridcharge¶

sequence: Periods 1-6 grid charging allowed?

Required: set to 1&batt_dispatch_choice=4 if not provided.

dispatch_manual_percent_discharge¶

sequence: Periods 1-6 discharge percent [%]

Required: set to 1&batt_dispatch_choice=4 if not provided.

dispatch_manual_percent_gridcharge¶

sequence: Periods 1-6 gridcharge percent [%]

Required: set to 1&batt_dispatch_choice=4 if not provided.

dispatch_manual_sched¶

sequence[sequence]: Battery dispatch schedule for weekday

Required: set to 1&batt_dispatch_choice=4 if not provided.

dispatch_manual_sched_weekend¶

sequence[sequence]: Battery dispatch schedule for weekend

Required: set to 1&batt_dispatch_choice=4 if not provided.

en_batt¶

float: Enable battery storage model [0/1]

Required: set to 0 if not provided.

om_replacement_cost1¶: sequence: Cost to replace battery per kWh [$/kWh]

System Group¶

class PySAM.StandAloneBattery.StandAloneBattery.System¶

assign() → None¶

Assign attributes from dictionary

System_vals = { var: val, ...}

export() → dict¶: Export attributes into dictionary

capacity_factor¶

float: Capacity factor [%]

Required: set to 0 if not provided.

gen¶: sequence: System power generated [kW]

ElectricLoad Group¶

class PySAM.StandAloneBattery.StandAloneBattery.ElectricLoad¶

assign() → None¶

Assign attributes from dictionary

ElectricLoad_vals = { var: val, ...}

export() → dict¶: Export attributes into dictionary

load¶: sequence: Electricity load (year 1) [kW]

Common Group¶

class PySAM.StandAloneBattery.StandAloneBattery.Common¶

assign() → None¶

Assign attributes from dictionary

Common_vals = { var: val, ...}

export() → dict¶: Export attributes into dictionary

inverter_model¶

float: Inverter model specifier

Options: 0=cec,1=datasheet,2=partload,3=coefficientgenerator,4=generic

Constraints: INTEGER,MIN=0,MAX=4

Inverter Group¶

class PySAM.StandAloneBattery.StandAloneBattery.Inverter¶

assign() → None¶

Assign attributes from dictionary

Inverter_vals = { var: val, ...}

export() → dict¶: Export attributes into dictionary

inv_cec_cg_eff_cec¶: float: Inverter Coefficient Generator CEC Efficiency [%]

inv_cec_cg_paco¶: float: Inverter Coefficient Generator Max AC Power [Wac]

inv_ds_eff¶: float: Inverter Datasheet Efficiency [%]

inv_ds_paco¶: float: Inverter Datasheet Maximum AC Power [Wac]

inv_pd_eff¶: float: Inverter Partload Efficiency [%]

inv_pd_paco¶: float: Inverter Partload Maximum AC Power [Wac]

inv_snl_eff_cec¶: float: Inverter Sandia CEC Efficiency [%]

inv_snl_paco¶: float: Inverter Sandia Maximum AC Power [Wac]

inverter_count¶: float: Number of inverters

PV Group¶

class PySAM.StandAloneBattery.StandAloneBattery.PV¶

assign() → None¶

Assign attributes from dictionary

PV_vals = { var: val, ...}

export() → dict¶: Export attributes into dictionary

dcoptimizer_loss¶: float: PV loss in DC/DC w/MPPT conversion

FuelCell Group¶

class PySAM.StandAloneBattery.StandAloneBattery.FuelCell¶

assign() → None¶

Assign attributes from dictionary

FuelCell_vals = { var: val, ...}

export() → dict¶: Export attributes into dictionary

dispatch_manual_fuelcellcharge¶: sequence: Periods 1-6 charging from fuel cell allowed?

fuelcell_power¶: sequence: Electricity from fuel cell [kW]

ElectricityRate Group¶

class PySAM.StandAloneBattery.StandAloneBattery.ElectricityRate¶

assign() → None¶

Assign attributes from dictionary

ElectricityRate_vals = { var: val, ...}

export() → dict¶: Export attributes into dictionary

en_electricity_rates¶

float: Enable Electricity Rates [0/1]

Options: 0=EnableElectricityRates,1=NoRates

ur_ec_sched_weekday¶

sequence[sequence]: Energy charge weekday schedule

Info: 12 x 24 matrix

Required: set to 1&batt_meter_position=1&batt_dispatch_choice=2 if not provided.

ur_ec_sched_weekend¶

sequence[sequence]: Energy charge weekend schedule

Info: 12 x 24 matrix

Required: set to 1&batt_meter_position=1&batt_dispatch_choice=2 if not provided.

ur_ec_tou_mat¶

sequence[sequence]: Energy rates table

Required: set to 1&batt_meter_position=1&batt_dispatch_choice=2 if not provided.

TimeOfDelivery Group¶

Outputs Group¶

class PySAM.StandAloneBattery.StandAloneBattery.Outputs¶

assign() → None¶

Assign attributes from dictionary

Outputs_vals = { var: val, ...}

export() → dict¶: Export attributes into dictionary

annual_export_to_grid_energy¶: sequence: Annual energy exported to grid [kWh]

annual_import_to_grid_energy¶: sequence: Annual energy imported from grid [kWh]

average_battery_conversion_efficiency¶: float: Battery average cycle conversion efficiency [%]

average_battery_roundtrip_efficiency¶: float: Battery average roundtrip efficiency [%]

batt_DOD¶: sequence: Battery cycle depth of discharge [%]

batt_I¶: sequence: Battery current [A]

batt_SOC¶: sequence: Battery state of charge [%]

batt_annual_charge_energy¶: sequence: Battery annual energy charged [kWh]

batt_annual_charge_from_grid¶: sequence: Battery annual energy charged from grid [kWh]

batt_annual_charge_from_pv¶: sequence: Battery annual energy charged from PV [kWh]

batt_annual_discharge_energy¶: sequence: Battery annual energy discharged [kWh]

batt_annual_energy_loss¶: sequence: Battery annual energy loss [kWh]

batt_annual_energy_system_loss¶: sequence: Battery annual system energy loss [kWh]

batt_bank_installed_capacity¶: float: Battery bank installed capacity [kWh]

batt_bank_replacement¶: sequence: Battery bank replacements per year [number/year]

batt_capacity_percent¶: sequence: Battery capacity percent for lifetime [%]

batt_capacity_thermal_percent¶: sequence: Battery capacity percent for temperature [%]

batt_conversion_loss¶: sequence: Electricity loss in battery power electronics [kW]

batt_cost_to_cycle¶: sequence: Computed cost to cycle [$/cycle]

batt_cycles¶: sequence: Battery number of cycles

batt_dispatch_sched¶: sequence[sequence]: Battery dispatch schedule

batt_power¶: sequence: Electricity to/from battery [kW]

batt_power_target¶: sequence: Electricity battery power target for automated dispatch [kW]

batt_pv_charge_percent¶: float: Battery percent energy charged from PV [%]

batt_q0¶: sequence: Battery total charge [Ah]

batt_q1¶: sequence: Battery available charge [Ah]

batt_q2¶: sequence: Battery bound charge [Ah]

batt_qmax¶: sequence: Battery maximum charge with degradation [Ah]

batt_qmaxI¶: sequence: Battery maximum capacity at current [Ah]

batt_qmax_thermal¶: sequence: Battery maximum charge at temperature [Ah]

batt_system_loss¶: sequence: Electricity loss from battery ancillary equipment [kW]

batt_temperature¶: sequence: Battery temperature [C]

batt_to_grid¶: sequence: Electricity to grid from battery [kW]

batt_to_load¶: sequence: Electricity to load from battery [kW]

batt_voltage¶: sequence: Battery voltage [V]

batt_voltage_cell¶: sequence: Battery cell voltage [V]

fuelcell_to_batt¶: sequence: Electricity to battery from fuel cell [kW]

grid_power¶: sequence: Electricity to/from grid [kW]

grid_power_target¶: sequence: Electricity grid power target for automated dispatch [kW]

grid_to_batt¶: sequence: Electricity to battery from grid [kW]

grid_to_load¶: sequence: Electricity to load from grid [kW]

monthly_batt_to_grid¶: sequence: Energy to grid from battery [kWh]

monthly_batt_to_load¶: sequence: Energy to load from battery [kWh]

monthly_grid_to_batt¶: sequence: Energy to battery from grid [kWh]

monthly_grid_to_load¶: sequence: Energy to load from grid [kWh]

monthly_pv_to_batt¶: sequence: Energy to battery from PV [kWh]

monthly_pv_to_grid¶: sequence: Energy to grid from PV [kWh]

monthly_pv_to_load¶: sequence: Energy to load from PV [kWh]

pv_to_batt¶: sequence: Electricity to battery from PV [kW]

pv_to_grid¶: sequence: Electricity to grid from PV [kW]

pv_to_load¶: sequence: Electricity to load from PV [kW]

Table of Contents

This Page

Battery¶

Creating an Instance¶

Functions¶

Simulation Group¶

Battery Group¶

System Group¶

ElectricLoad Group¶

Common Group¶

Inverter Group¶

PV Group¶

FuelCell Group¶

ElectricityRate Group¶

TimeOfDelivery Group¶

Outputs Group¶