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: FetchResourceFileExample.py

class files.ResourceTools.FetchResourceFiles(tech, nrel_api_key, nrel_api_email, workers=1, resource_type='psm3-tmy', 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/wind-toolkit/wtk-download/. ‘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 = ‘psm3-tmy’ for solar, ‘’ for wind. ‘psm3’ for 30- or 60-minute single-year file ‘psm3-tmy’ for 60-minute TMY, TGY, or TDY typical-year file ‘psm3-5min’ for 5-, 30- or 60-minute single-year 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 psm3-tmy ‘tmy-2016’ to ‘tmy-2018’, etc. for NSRDB psm3-tmy ‘2018’, etc. for NSRDB psm3-5min ‘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/weather-data/weather-data-publications.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/weather-data/weather-data-publications.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 = 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 AC-connected, kWDC otherwise. For BatteryStateful, battery kWDC.

  • desired_capacity (float) – For Battery, kWhAC if AC-connected, kWhDC otherwise. For BatteryStateful, battery kWhDC.

  • desired_voltage (float) – Volts

  • size_by_ac_not_dc (bool, optional) – Sizes for power and capacity are on AC side not DC side of battery-inverter regardless of connection type.

  • module_specs (dict, optional) –

    {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 AC-connected, 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, 0-100. 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

    Lithium-ion (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, optional) –

  • LeadAcid_q10 (float) – Required if batt_chem = 0. 10-hour disharge rate in Ah, between 0 and 100.

  • LeadAcid_q20 (float) – Required if batt_chem = 0. 20-hour discharge rate in Ah, between 0 and 100.

  • LeadAcid_qn (float) – Required if batt_chem = 0. n-hour 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 ac-connected, 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_efficiencyRequired 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.

  • batt_dc_dc_efficiency – 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

0-1

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.

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: 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 AC-connected, kWDC otherwise.

  • desired_capacity (float) – Desired battery capacity, kWhAC if AC-connected, 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 AC-connected or kWhDC if DC-connected.

    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, use size_battery() instead. Only battery side DC sizing.

Parameters:
  • model – PySAM.Battery model

  • _ – Not used.

  • desired_capacity (float) – kWhAC if AC-connected, 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 AC-connected, 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: LoadToolsExample.py

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