Helper Functions (Tools)¶
These helper functions provide additional functionality for working with specific models.
Resource Tools¶
Access resource tools with import PySAM.ResourceTools
.
These functions help with solar resource, wind resource and utility rate data, downloads and formatting. See how to download solar resource data from the National Solar Radiation Database or wind resource data from the WindToolKit. Use resource files directly in your PySAM models or input them as dictionaries.
Please see an example of FetchResource here

class
files.ResourceTools.
FetchResourceFiles
(tech, nrel_api_key, nrel_api_email, workers=1, resource_type='psm3tmy', resource_year='tmy', resource_interval_min=60, resource_height=100, resource_dir=None, verbose=True)¶ Download solar and wind resource files from NREL developer network https://developer.nrel.gov/.
Parameters:  tech (str) – Required Name of technology. ‘wind’ for NREL WIND Toolkit at https://developer.nrel.gov/docs/wind/windtoolkit/wtkdownload/. ‘solar’ for NREL NSRDB at https://developer.nrel.gov/docs/solar/nsrdb/nsrdb_data_query/
 nrel_api_key (str) – Required NREL developer API key, available at https://developer.nrel.gov/signup/.
 nrel_api_email (str) – Required Email address associated with nrel_api_key.
 resource_dir (str) – Directory to store downloaded files. Default = ‘None’, which results in data/PySAM Downloaded Weather Files.
 workers (int) – Number of threads to use when parellelizing downloads. Default = 1.
 resource_type (str) – Name of API for NSRDB solar data. Default = ‘psm3tmy’ for solar, ‘’ for wind. ‘psm3’ for 30 or 60minute singleyear file ‘psm3tmy’ for 60minute TMY, TGY, or TDY typicalyear file ‘psm35min’ for 5, 30 or 60minute singleyear file ‘’ for WIND Toolkit
 resource_year (str) – Data year, changes over time so check API documentation for latest information. Default = ‘tmy’ for solar, ‘2014’ for wind. ‘1998’ to ‘2019’, etc. for NSRDB psm3 ‘tmy’ for latest TMY file from NSRDB psm3tmy ‘tmy2016’ to ‘tmy2018’, etc. for NSRDB psm3tmy ‘2018’, etc. for NSRDB psm35min ‘2007’ to ‘2014’ for WIND Toolkit
 resource_interval_min (int) – Time interval of resource data in minutes. See available intervals under resource_type above. Default = 60.
 resource_height (int) – For wind only, wind resource measurement height above ground in meters. Default = 100. 10, 40, 60, 80, 100, 120, 140, 160 for windspeed, winddirection, temperature 0, 100, 200 for pressure

fetch
(points)¶ Creates dict with {region:path_to_SAM_resource_file}.
Parameters: points (iterable) – Iterable of lon/lat tuples, i.e. Shapely Points.

files.ResourceTools.
SAM_CSV_to_solar_data
(filename)¶ Format a TMY csv file as ‘solar_resource_data’ dictionary for use in PySAM. For more information about SAM CSV file format, see https://sam.nrel.gov/weatherdata/weatherdatapublications.html
Parameters: filename – Any csv resource file formatted according to NSRDB Returns: Dictionary for PySAM.Pvwattsv7.Pvwattsv7.SolarResource, and other models

files.ResourceTools.
SRW_to_wind_data
(filename)¶ Format as ‘wind_resource_data’ dictionary for use in PySAM. For more information about SRW file format, see https://sam.nrel.gov/weatherdata/weatherdatapublications.html
Parameters: filename – A .srw wind resource file Returns: Dictionary for PySAM.Windpower.Windpower.Resource

files.ResourceTools.
URDBv7_to_ElectricityRates
(urdb_response)¶  Formats response from Utility Rate Database API version 7 for use in PySAM
 i.e.
 model = PySAM.UtilityRate5.new() rates = PySAM.ResourceTools.URDBv7_to_ElectricityRates(urdb_response) model.ElectricityRates.assign(rates)
Param: urdb_response: dictionary with response fields following https://openei.org/services/doc/rest/util_rates/?version=7 Returns: dictionary for PySAM.UtilityRate5.UtilityRate5.ElectricityRates
Battery Tools¶
Access battery tools with import PySAM.BatteryTools
.

files.BatteryTools.
battery_model_change_chemistry
(model, chem)¶ Changes the chemistry and cell properties of the battery to use defaults for that chemistry from BatteryStateful
Parameters:  model – PySAM.Battery.Battery or PySAM.BatteryStateful.BatteryStateful
 chem (str) – Battery chemistry, ‘leadacid’, ‘lfpgraphite’, ‘nmcgraphite’, or ‘lmolto’.

files.BatteryTools.
battery_model_sizing
(model, desired_power, desired_capacity, desired_voltage, size_by_ac_not_dc=None, module_specs: dict = None, tol=0.05)¶ Sizes the battery model using its current configuration such as chemistry, cell properties, etc and modifies the model’s power, capacity and voltage without changing its fundamental properties. The battery’s thermal parameters (surface area and mass) are modified according to assumptions about the mass and volume per specific energy and assuming the battery is a cube. If the battery’s thermal parameters should be sized according to a particular module’s capacity and surface area, use the module_specs input.
Parameters:  model – PySAM.Battery.Battery or PySAM.BatteryStateful.BatteryStateful
 desired_power (float) – For Battery, kWAC if ACconnected, kWDC otherwise. For BatteryStateful, battery kWDC.
 desired_capacity (float) – For Battery, kWhAC if ACconnected, kWhDC otherwise. For BatteryStateful, battery kWhDC.
 desired_voltage (float) – Volts
 optional size_by_ac_not_dc (bool,) – Sizes for power and capacity are on AC side not DC side of batteryinverter regardless of connection type.
 optional module_specs (dict,) –
{capacity (float), surface_area (float)} Dictionary of battery module specifications for scaling surface area, assuming the battery is made of individual modules.
 capacity: float
 Capacity of a single battery module. For the Battery model, use kWhAC if ACconnected, use kWhDC otherwise. For the BatteryStateful model, use battery kWhDC.
 surface_area: float
 Surface area of as single battery module in m^2.

files.BatteryTools.
calculate_battery_size
(input_dict, tol=0.05)¶ Helper function to battery_model_sizing. All efficiencies and rates in percentages, 0100. Inverter efficiency depends on which inverter model is being used, inverter_model.
Parameters:  input_dict (dict) –
Dictionary of battery parameters. {batt_chem (int), batt_Qfull (float), batt_Vnom_default (float)}
 batt_chem: int
 Lithiumion (1) or Lead acid (0)
 batt_Qfull: float
 capacity of single cell in Ah
 batt_Vnom_default: float
 voltage of single cell in V
 batt_ac_or_dc (bool) –
 desired_power (float) –
 desired_capacity (float) –
 desired_voltage (float) –
 size_by_ac_not_dc (bool) –
 batt_dc_ac_efficiency (float) –
 inverter_eff (float) –
 batt_dc_dc_efficiency (float) –
 LeadAcid_q10 (float) – Required if batt_chem = 0. 10hour disharge rate in Ah, between 0 and 100.
 LeadAcid_q20 (float) – Required if batt_chem = 0. 20hour discharge rate in Ah, between 0 and 100.
 LeadAcid_qn (float) – Required if batt_chem = 0. nhour discharge rate in Ah, between 0 and 100.
 LeadAcid_tn (int) – Required if batt_chem = 0. Hour for custom hour discharge rate.
 batt_ac_or_dc – Set to True if acconnected, set to False otherwise.
 desired_power – Power of the battery in kW.
 desired_capacity – Desired battery capacity in kWh.
 desired_voltage – Desired battery voltage in V.
 size_by_ac_not_dc – Set to True for sizing battery as kWAC and kWhAC. Default is False.
 batt_dc_ac_efficiency – Required only if size_by_ac_not_dc = True AC to DC power in conversion, between 0 and 100.
 inverter_eff – Required only if batt_ac_or_dc = False. Inverter DC to AC conversion efficiency, between 0 and 100.
 optional batt_dc_dc_efficiency (float,) – DC to DC power conversion in battery management system, between 0 and 100.
Returns: Dictionary of battery size parameters.
Return type: dict {voltage (float), power (float), batt_computed_bank_capacity (float), batt_computed_series (int), batt_computed_string0250s (int), time_capacity (float), batt_current_charge_max (float), batt_current_discharge_max (float), batt_power_charge_max_kwac (float), batt_power_discharge_max_kwac (float), batt_power_charge_max_kwdc (float), batt_power_discharge_max_kwdc (float), LeadAcid_q10_computed (float), LeadAcid_q20_computed (float), LeadAcid_qn_computed (float)}
 voltage: float
Computed voltage.
 power: float
Computed power.
 batt_computed_bank_capacity: float
Computed bank capacity.
 batt_computed_series: int
Computed number of cells connected in series.
 batt_computed_strings: int
Computed number of cell strings connected in parallel.
 time_capacity: float
01
 batt_current_charge_max: float
A
 batt_current_discharge_max: float
A
 batt_power_charge_max_kwac: float
kWAC
 batt_power_discharge_max_kwac: float
kWAC
 batt_power_charge_max_kwdc: float
kWDC
 batt_power_discharge_max_kwdc: float
kWDC
 Lead acid parameters returned if batt_chem = 0:
LeadAcid_q10_computed, LeadAcid_q20_computed, LeadAcid_qn_computed, all in Ah between 0 and 100.
 input_dict (dict) –

files.BatteryTools.
calculate_thermal_params
(input_dict)¶ Calculates the mass and surface area of a battery by calculating from its current parameters the mass / specific energy and volume / specific energy ratios. If module_capacity and module_surface_area are provided, battery surface area is calculated by scaling module_surface_area by the number of modules required to fulfill desired capacity.
Parameters: input_dict (dict) – A dictionary of battery thermal parameters at original size. {mass (float), surface_area (float), original_capacity (float), desired_capacity (float), module_capacity (float, optional), surface_area (float, optional)}
 mass: float
 kg of battery at original size
 surface_area: float
 m^2 of battery at original size
 original_capacity: float
 Wh of battery
 desired_capacity: float
 Wh of new battery size
 module_capacity: float, optional
 Wh of module battery size
 module_surface_area: float, optional
 m^2 of module battery
Returns: Dictionary of battery mass and surface area at desired size. Return type: dict {mass (float), surface_area (float)}  mass: float
 kg of battery at desired size
 surface_area: float
 m^2 of battery at desired size

files.BatteryTools.
chem_battery
(model: Union[Battery, Pvsamv1], chem)¶ Helper function for battery_model_change_chemistry().

files.BatteryTools.
chem_batterystateful
(model: BatteryStateful, chem)¶ Helper function for battery_model_change_chemistry

files.BatteryTools.
size_battery
(model, desired_power, desired_capacity, desired_voltage, size_by_ac_not_dc=None, module_dict=None, tol=0.05)¶ Helper function for battery_model_sizing. Modifies Battery model with new sizing. For BatteryStateful use size_batterystateful.
Parameters:  model – PySAM.Battery model
 desired_power (float) – Desired battery power, kWAC if ACconnected, kWDC otherwise.
 desired_capacity (float) – Desired battery capacity, kWhAC if ACconnected, kWhDC otherwise.
 desired_voltage (float) – Desired battery voltage, V.
 size_by_ac_not_dc (bool,optional) – True sizes for power and capacity based on AC cpacities, False sizes for DC capacities.
 module_dict (dict) –
{capacity (float), surface_area (float)} Battery module specs for scaling surface area.
 capacity: float
 Capacity of a single battery module in kWhAC if ACconnected or kWhDC if DCconnected.
 surface_area: float
 Surface area is of single battery module in m^2.
Returns: Dictionary of of sizing parameters.
Return type: dict

files.BatteryTools.
size_batterystateful
(model: BatteryStateful, _, desired_capacity, desired_voltage, module_dict=None)¶ Helper function for
battery_model_sizing()
. Modifies BatteryStateful model with new sizing. For Battery model, usesize_battery()
instead. Only battery side DC sizing.Parameters:  model – PySAM.Battery model
 _ – Not used.
 desired_capacity (float) – kWhAC if ACconnected, kWhDC otherwise.
 desired_voltage (float) – Volts.
 module_dict (dict) –
{capacity (float), surface_area (float)} Optional, module specs for scaling surface area.
 capacity: float
 Capacity of a single battery module in kWhAC if ACconnected, kWhDC otherwise.
 surface_area: float
 Surface area is of single battery module in m^2.
Returns: Dictionary of sizing parameters.
Return type: dict
Load Tools¶
Access load tools with import PySAM.LoadTools
.
These functions help manipulate load data for local analysis and the utility rate functions
Please see an example of get_monthly_peaks here
A list of hour of year that ends each month. Given an hourly array, hourly_data[max_hrs[0]:max_hrs[1]] would return all of the data from January. Multiply indicies by steps per hour to do subhourly data.

files.LoadTools.
get_monthly_peaks
(load_profile, steps_per_hour)¶ Get a list of monthly peaks from a grid usage profile Developed to create year 0 peaks for billing demand functions in utility rate code
Param: load_profile: list of one year of load data in floats. Length is 8760 * steps_per_hour Param: steps_per_hour: integer of steps per hour. 1=hourly data, 4=15 min data, etc Returns: list of peak values, length 12
Utility Rate Tools¶
Access utility rate tools with import PySAM.UtilityRateTools
.
These functions translate URDB data into the SAM format
Please see an example of URDBv8_to_ElectricityRates here

files.UtilityRateTools.
URDBv8_to_ElectricityRates
(urdb_response)¶  Formats response from Utility Rate Database API version 8 for use in PySAM
 i.e.
 model = PySAM.UtilityRate5.new() rates = PySAM.ResourceTools.URDBv8_to_ElectricityRates(urdb_response) model.ElectricityRates.assign(rates)
This function does the additional processing when these rate features are present.
Param: urdb_response: dictionary with response fields following https://openei.org/services/doc/rest/util_rates/?version=8 Returns: dictionary for PySAM.UtilityRate5.UtilityRate5.ElectricityRates