Tools¶
These helper functions provide additional functionality for working with specific models.
Resource Tools¶
These can be accessed via 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='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/ !param str nrel_api_key: Required NREL developer API key, available at https://developer.nrel.gov/signup/.
Parameters: - 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¶
These can be accessed via 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 – string ‘leadacid’, ‘lfpgraphite’, ‘nmcgraphite’, ‘lmolto’
-
files.BatteryTools.
battery_model_sizing
(model, desired_power, desired_capacity, desired_voltage, size_by_ac_not_dc=None, module_specs: dict = None)¶ 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 Battery: kWAC if AC-connected, kWDC otherwise. BatteryStateful: battery kWDC
- desired_capacity – float Battery: kWhAC if AC-connected, kWhDC otherwise. BatteryStateful: battery kWhDC
- desired_voltage – float volts
- size_by_ac_not_dc – optional bool Sizes for power and capacity are on AC side not DC side of battery-inverter regardless of connection type
- module_specs –
optional dict Module specifications for scaling surface area assuming the battery is made of inividual modules.
- capacity: float
- Single battery module capacity for scaling surface area Battery: kWhAC if AC-connected, kWhDC otherwise BatteryStateful: battery kWhDC
- surface_area: float
- Single battery module surface area m^2 m^2 of module battery
-
files.BatteryTools.
calculate_battery_size
(input_dict)¶ 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 – - batt_chem: int
- Lithium-ion (1) or Lead-Acid (0)
- batt_Qfull: float, Ah
- capacity of single cell
- batt_Vnom_default: float, V
- voltage of single cell
- Required only if batt_chem is False:
- LeadAcid_q10: float 0-100, Ah
- 10 hour discharge rate
- LeadAcid_q20: float 0-100, Ah
- 20 hour discharge rate
- LeadAcid_tn: int, hour
- hour for custom hour discharge rate
- LeadAcid_qn: float 0-100, Ah
- n-hour discharge rate
- batt_ac_or_dc: bool
- True if ac-connected
- desired_power: float, kW
- power of the battery
- desired_capacity: float, kWh
- capacity
- desired_voltage: float, V
- voltage
- size_by_ac_not_dc: bool, default False
- True for sizing battery as kWAC and kWhAC
- batt_dc_ac_efficiency: float 0-100, required only if size_by_ac_not_dc is True
- AC to DC power in conversion
- inverter_eff: float 0-100, required only if batt_ac_or_dc is False
- AC to DC power from inverter
- batt_dc_dc_efficiency: float 0-100, optional
- DC to DC power conversion in battery management system
Returns: output_dict: voltage: float, V computed- power: float
- computed
- batt_computed_bank_capacity: float
- computed
- batt_computed_series: int
- number of cells connected in series
- batt_computed_strings: int
- number of 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
- only if batt_chem is False:
- LeadAcid_q10_computed: float 0-100, Ah
LeadAcid_q20_computed: float 0-100, Ah
LeadAcid_qn_computed: float 0-100, Ah
-
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.
Param: - input_dict:
- 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: optional float
Wh of module battery size
- module_surface_area: optional float
m^2 of module battery
Returns: - mass: float
kg of battery at desired size
- surface_area: float
m^2 of battery at desired size
Return type: output_dict
-
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)¶ 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 kWAC if AC-connected, kWDC otherwise
- desired_capacity – float kWhAC if AC-connected, kWhDC otherwise
- desired_voltage – float volts
- size_by_ac_not_dc – optional bool Sizes for power and capacity are on AC side not DC side of battery-inverter
- module_dict –
optional dict Module specs for scaling surface area
- capacity: float
- Single battery module capacity for scaling surface area kWhAC if AC-connected, kWhDC otherwise
- surface_area: float
- Single battery module surface area m^2 m^2 of module battery
Returns: output_dictionary of sizing parameters
-
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 use size_battery
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 –
optional dict Module specs for scaling surface area
- capacity: float
- Single battery module capacity for scaling surface area kWhAC if AC-connected, kWhDC otherwise
- surface_area: float
- Single battery module surface area m^2 m^2 of module battery
Returns: output_dictionary of sizing parameters