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 PySAM.ResourceTools.FetchResourceFiles(tech, nrel_api_key, nrel_api_email, workers=1, resource_type='nsrdb-GOES-tmy-v4-0-0', resource_year='tmy', resource_interval_min=60, resource_height=100, resource_dir=None, verbose=True)

Download solar and wind resource files from NLR developer network https://developer.nlr.gov/.

Parameters:

  • tech (str) – Required Name of technology. ‘wind’ for NLR WIND Toolkit at https://developer.nlr.gov/docs/wind/wind-toolkit/wtk-download/. ‘solar’ for NLR NSRDB at https://developer.nlr.gov/docs/solar/nsrdb/nsrdb_data_query/

  • nrel_api_key (str) – Required NLR developer API key, available at https://developer.nlr.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 = ‘nsrdb-GOES-tmy-v4-0-0’ for solar, ‘’ for wind. ‘nsrdb-GOES-aggregated-v4-0-0’ for 30- or 60-minute single-year file ‘nsrdb-GOES-conus-v4-0-0’ for 5-, 15-, 30- or 60-minute single-year file in CONUS region ‘nsrdb-GOES-full-disc-v4-0-0’ for 10-, 30- or 60-minute single-year file in GOES satellite coverage area ‘nsrdb-GOES-tmy-v4-0-0’ for 60-minute TMY, TGY, or TDY typical-year file ‘’ for solar will automatically assign a relevant resource at the location ‘’ 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 ‘2024’ for specific year from NSRDB nsrdb-GOES-aggregated-v4-0-0 ‘tmy’ for latest TMY file from NSRDB nsrdb-GOES-tmy-v4-0-0 ‘tmy-2022’ to ‘tmy-2024’ for specific TMY year from NSRDB nsrdb-GOES-tmy-v4-0-0 ‘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.

PySAM.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.nlr.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

PySAM.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.nlr.gov/weather-data/weather-data-publications.html

Parameters:

filename – A .srw wind resource file

Returns:

Dictionary for PySAM.Windpower.Windpower.Resource

PySAM.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.

PySAM.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’.

PySAM.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.

PySAM.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

PySAM.BatteryTools.chem_battery(model: Battery | Pvsamv1, chem)

Helper function for battery_model_change_chemistry().

PySAM.BatteryTools.chem_batterystateful(model: BatteryStateful, chem)

Helper function for battery_model_change_chemistry

PySAM.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

PySAM.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.

PySAM.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

PySAM.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

Pvsamv1 Tools

Access Pvsamv1 tools with import PySAM.Pvsamv1Tools.

These functions are for PV system design and layout

For examples, see here

PySAM.Pvsamv1Tools.align_from_capacity(system_capacity_target: float, dc_ac_ratio: float, modules_per_string: float, module_power: float, inverter_power: float) → list

Ensure coherence between parameters for detailed PV model (pvsamv1), keeping the DC-to-AC ratio approximately the same

Parameters:

  • system_capacity_target – target system capacity, kW

  • dc_ac_ratio – DC-to-AC ratio

  • modules_per_string – modules per string, -

  • module_power – module power at maximum point point at reference conditions, kW

  • inverter_power – inverter maximum AC power, kW

  • n_inverters_orig – original number of inverters

Returns:

number strings, calculated system capacity [kW], number of inverters

PySAM.Pvsamv1Tools.find_inverter_count(model, dc_ac_ratio: float, modules_per_string: float, n_strings: float, module_power: float, inverter_power: float)

Helper function for size_electrical_parameters that sizes the number of inverters

Parameters:

  • model – PySAM.Pvsamv1 model

  • dc_ac_ratio – DC-to-AC ratio

  • modules_per_string – modules per string

  • n_strings – number of strings in array

  • module_power – module power at maximum point point at reference conditions, kW

  • inverter_power – inverter maximum AC power, kW

Returns:

number of inverters in array

PySAM.Pvsamv1Tools.find_modules_per_string(model, v_mppt_min: float, v_mppt_max: float, v_mp_module: float, v_oc_module: float, inv_vdcmax: float, target_relative_string_voltage: float | None = None) → float

Helper function for size_electrical_parameters that calculates the number of modules per string to best match target string voltage

Parameters:

  • model – PySAM.PVsamv1 model

  • v_mppt_min – lower boundary of inverter maximum-power-point operating window, V

  • v_mppt_max – upper boundary of inverter maximum-power-point operating window, V

  • v_mp_module – voltage of module at maximum point point at reference conditions, V

  • v_oc_module – open circuit voltage of module at reference conditions, V

  • inv_vdcmax – maximum inverter input DC voltage, V

  • target_relative_string_voltage – relative string voltage within MPPT voltage window, [0, 1]

Returns:

number of modules per string

PySAM.Pvsamv1Tools.get_num_modules(pvsam_model) → float

Return the number of modules in all subarrays

PySAM.Pvsamv1Tools.set_cec_inverter_library_selection(model, inverter_name: str) → dict

Return the inverter values from the CEC Inverter Database library as a dictionary. Requires inverter_model = 0.

Parameters:

  • model – Pvsamv1 model to write the inverter values to

  • inverter_name – Name of inverter for indexing library, str

Returns:

dictionary with variable values for selected inverter

PySAM.Pvsamv1Tools.set_cec_module_library_selection(model, module_name: str) → dict

Return the module values from the CEC Module Database library as a dictionary. Requires module_model = 1.

Parameters:

  • model – Pvsamv1 model to write the module values to

  • module_name – Name of module for indexing library, str

Returns:

dictionary with variable values for selected module

PySAM.Pvsamv1Tools.size_electrical_parameters(model, target_system_capacity: float, target_dc_ac_ratio: float, vdcmax_inverter: float | None = None, n_inputs_inverter: float | None = None, n_inputs_combiner: float | None = None)

Calculates the number of strings, combiner boxes and inverters to best match target capacity and DC/AC ratio

Parameters:

  • model – PySAM.Pvsamv1 model

  • target_system_capacity – target system capacity, kW

  • target_dc_ac_ratio – target DC-to-AC ratio

  • vdcmax_inverter – inverter maximum DC voltage, V

  • n_inputs_inverter – number of DC inputs per inverter

  • n_inputs_combiner – number of DC inputs per combiner box

Returns:

number of strings, number of combiner boxes, number of inverters, calculated system capacity, kW

PySAM.Pvsamv1Tools.verify_capacity_from_electrical_parameters(system_capacity_target: float, n_strings: List[int], modules_per_string: List[int], module_power: float, percent_max_deviation: float = 5) → float

Computes system capacity from specified number of strings, modules per string and module power. If computed capacity is significantly different than the specified capacity an exception will be thrown.

Parameters:

  • system_capacity_target – target system capacity, kW

  • n_strings – number of strings in each subarray, -

  • modules_per_string – modules per string in each subarray, -

  • module_power – module power at maximum point point at reference conditions, kW

  • percent_max_deviation – if calculated system capacity differs from target by this percent or more, raise an exception; if None, do not check

Returns:

calculated system capacity, kW