National Renewable Energy Laboratory's System Advisor Model Python Wrapper
Project description
- Provides a wrapper around the SAM library that groups together the C API functions by technology or financial model into modules.
- Includes error-checking, explicit input and output definition, and conversion between Python data types.
- PySAM modules are compatible with PySSC, which is included as a subpackage. PySSC is the original wrapper used by SAM's code generator.
- Automatically assign default values to input parameters from SAM's default value database.
- Built-in documentation of models and parameters.
- Minimum Python 3.5 for Windows 7 64-bit, MacOSX 10.6, or CentOS 5.
Set up
Install:
pip install NREL-PySAM
Import a technology or financial model:
import PySAM.<PySAM Module>
Import PySSC subpackage:
from PySAM.PySSC import PySSC
Create a new empty model:
PySAM.<PySAM Module>.new()
Create a new model with values assigned from defaults:
PySAM.<PySAM Module>.default(string configuration)
View parameter groups per class and available default values:
help(model)
View descriptions of parameters in a group:
help(model.<group>)
Module Names and Descriptions
PySAM Module | SAM Desktop | Description |
---|---|---|
Battwatts | Simplified battery storage model | |
Belpe | Electric load calculator for residential buildings | |
Biomass | Biomass combustion | Biomass combustion for electricity generation |
CashloanModel | Financial model for residential and commercial behind-the-meter projects | |
Equpartflip | All Equity Partnership Flip | PPA all equity partnership flip (no debt) financial model |
Fuelcell | ||
GenericSystem | Generic system | Basic power system model using either capacity, capacity factor, and heat rate, or an hourly power generation profile as input |
Geothermal | Geothermal | Geothermal power model for hydrothermal and EGS systems with flash or binary conversion |
Hcpv | High concentration PV | Concentrating photovoltaic system with a high concentration photovoltaic module model and separate inverter model |
HostDeveloper | Third party ownership - host/developer | Third party ownership with PPA financial model from host and developer perspective |
IphToLcoefcr | LCOH Calculator | Calculate levelized cost of heat using fixed charge rate method for industrial process heat models |
Lcoefcr | LCOE calculator (FCR method) | Calculate levelized cost of electricity using fixed charge rate method instead of cash flow |
Levpartflip | Leveraged Partnership Flip | PPA leveraged partnership flip (with debt) financial model |
LinearFresnelDsgIph | Process heat linear direct steam | Linear Fresnel for industrial process heat applications |
Pvsamv1 | Photovoltaic (detailed) | Detailed photovoltaic system model with separate components for module and inverter |
Pvwattsv5 | Photovoltaic (PVWatts) | PVWatts photovoltaic system model with simple inputs |
Pvwattsv5Lifetime | PVWatts photovoltaic system model for multi-year lifetime analysis | |
Saleleaseback | PPA sale leaseback (utility) | PPA sale leaseback partnership financial model |
Singleowner | PPA single owner (utility) | PPA single owner financial model |
StandAloneBattery | Detailed battery storage model | |
Swh | Solar water heating | Solar water heating model for residential and commercial building applications |
TcsdirectSteam | CSP power tower direct steam | CSP direct steam power tower model for power generation |
Tcsdish | CSP dish Stirling | CSP dish-Stirling model with parameters for SES and WGA-ADDS systems for power generation |
TcsgenericSolar | CSP generic model | CSP power system model with solar field characterized using a table of optical efficiency values |
Tcsiscc | CSP integrated solar combined cycle | CSP molten salt power tower system with a natural gas combined cycle power plant |
TcslinearFresnel | CSP linear Fresnel direct steam | Linear Fresnel model with steam heat transfer fluid for industrial process heat applications |
TcsmoltenSalt | CSP power tower molten salt | CSP molten salt power tower for power generation |
TcsMSLF | CSP linear Fresnel molten salt | CSP linear Fresnel with molten salt heat transfer fluid for power generation |
TcstroughEmpirical | CSP parabolic trough (empirical) | CSP parabolic trough model based on empirically-derived coefficients and equations for power generation |
TcstroughPhysical | CSP parabolic trough (physical) | CSP parabolic trough model based on heat transfer and thermodynamic principles for power generation |
Thermalrates | Thermal flat rate structure net revenue calculator | |
Thirdpartyownership | Third party ownership - host | Third party ownership with PPA or lease agreement financial model from host perspective |
TroughPhysicalProcessHeat | Process heat parabolic trough | Parabolic trough for industrial process heat applications |
Utilityrate5 | Retail electricity bill calculator | |
Windpower | Wind | Wind power system with one or more wind turbines |
To run a case from the SAM GUI:
-
On the drop-down menu for the case, click Generate code then JSON for inputs, and export the case inputs to a JSON file.
-
For each SSC compute module required for the simulation (see Configurations and SSC Compute Modules below), create a new PySSC data table and wrap it with the equivalent PySAM class, releasing memory ownership to the newly created instance. Do not call
PySSC.data_free
on the data passed to the wrap function!
For example, the following code imports the parameters from a JSON file named genericsystem_case.json that was exported from a Generic System-Single Owner case in SAM, creates a PySSC table for the Generic System and Single Owner SSC compute modules, and then wraps each table in the appropriate PySAM class:
import json
import PySAM.GenericSystem as GenericSystem
import PySAM.Singleowner as Singleowner
from PySAM.PySSC import *
ssc = PySSC()
with open("genericsystem_case.json") as f:
dic = json.load(f)
gs_dat = dict_to_ssc_table(dic, "generic_system")
so_dat = dict_to_ssc_table(dic, "singleowner")
gs = GenericSystem.wrap(gs_dat)
so = Singleowner.wrap(so_dat)
-
For each PySAM class, you can export the parameters to separate dictionaries. This allows the data to be loaded later using
assign
.help(gs.Plant) # descriptions gs_params = gs.export() so_params = so.export() ... another_gs = GenericSystem.new() another_gs.assign(gs_params) another_so = Singleowner.new() another_so.assign(so_params)
-
For some compute module input parameters, the SAM graphical user interface (GUI) uses equations to calculate the value of the parameter from special GUI inputs that are not passed to the compute module. Other compute module input parameters are used by more than one compute module in the simulation. In some cases, you may need to write additional code to ensure values for these parameters are correctly assigned. We hope to eliminate the need for this additional code in the future. Until then, you can find the SAM GUI equations in the runtime/ui folder, and determine compute module inputs from the SSC source code or using the SDKtool, available as part of the SAM installation as described on the SAM SDK web page.
For example, for the Flat Plate PV-Single Owner configuration, the ground coverage ratio (GCR) is used in two ways: It is an input to the Flat Plate PV compute module for self-shading calculations, and also may be used in GUI equations to calculate the land cost component of the total installed cost input to the Single Owner compute module. If your Python code changes the value of Pvsamv1.SystemDesign.gcr
to x
, and you are including land cost y
in $/acre in your analysis, you need code like the following adapted from the GUI equations in runtime/ui/PV System Design.txt to ensure the change is accounted for in Singleowner.SystemCosts.total_installed_cost
:
pv.SystemDesign.subarray1_gcr = x
land_area = pv.CECPerformanceModelWithModuleDatabase.cec_area
* (pv.SystemDesign.subarray1_nstrings
* pv.SystemDesign.subarray1_modules_per_string) / x * 0.0002471 # m^2 to acres
# total_installed_cost = total_direct_cost + permitting_total + engr_total + grid_total + landprep_total + sales_tax_total + land_total
# y = land cost in $/acre
so.SystemCosts.total_installed_cost = cost_without_land + y * land_area
For the same Flat Plate PV-Single Owner configuration, an example of an input that is used by both compute modules is analysis_period
. It is used by the Single Owner module as the number of years for the cash flow, and by the Flat Plate PV model for battery lifecycle calculations.
- To run a simulation, use
execute(verbosity)
where 0 indicates minimal messages and 1 produces log messages. All outputs are available in the Outputs group of a PySAM class.
pv.Outputs.export() # as dictionary
Configurations and SSC Compute Modules
A configuration is a combination of compute modules required to model a type of system (performance model) or project (performance model plus financial model).
Configuration | SSC Compute Module(s) |
---|---|
Battery-None | battery |
Biopower-All Equity Partnership Flip | biomass, equpartflip |
Biopower-Commercial | biomass, utilityrate5, cashloan |
Biopower-LCOE Calculator | biomass, lcoefcr |
Biopower-Leveraged Partnership Flip | biomass, levpartflip |
Biopower-None | biomass |
Biopower-Sale Leaseback | biomass, saleleaseback |
Biopower-Single Owner | biomass, singleowner |
Dish Stirling-All Equity Partnership Flip | tcsdish, equpartflip |
Dish Stirling-Commercial | tcsdish, utilityrate5, cashloan |
Dish Stirling-LCOE Calculator | tcsdish, lcoefcr |
Dish Stirling-Leveraged Partnership Flip | tcsdish, levpartflip |
Dish Stirling-None | tcsdish |
Dish Stirling-Sale Leaseback | tcsdish, saleleaseback |
Dish Stirling-Single Owner | tcsdish, singleowner |
DSGL IPH-LCOH Calculator | linear_fresnel_dsg_iph, iph_to_lcoefcr, lcoefcr |
DSGL IPH-None | linear_fresnel_dsg_iph |
DSLF-All Equity Partnership Flip | tcslinear_fresnel, equpartflip |
DSLF-Commercial | tcslinear_fresnel, utilityrate5, cashloan |
DSLF-LCOE Calculator | tcslinear_fresnel, lcoefcr |
DSLF-Leveraged Partnership Flip | tcslinear_fresnel, levpartflip |
DSLF-None | tcslinear_fresnel |
DSLF-Sale Leaseback | tcslinear_fresnel, saleleaseback |
DSLF-Single Owner | tcslinear_fresnel, singleowner |
DSPT-All Equity Partnership Flip | tcsdirect_steam, equpartflip |
DSPT-Leveraged Partnership Flip | tcsdirect_steam, levpartflip |
DSPT-Sale Leaseback | tcsdirect_steam, saleleaseback |
DSPT-Single Owner | tcsdirect_steam, singleowner |
Empirical Trough-All Equity Partnership Flip | tcstrough_empirical, equpartflip |
Empirical Trough-Commercial | tcstrough_empirical, utilityrate5, cashloan |
Empirical Trough-LCOE Calculator | tcstrough_empirical, lcoefcr |
Empirical Trough-Leveraged Partnership Flip | tcstrough_empirical, levpartflip |
Empirical Trough-None | tcstrough_empirical |
Empirical Trough-Sale Leaseback | tcstrough_empirical, saleleaseback |
Empirical Trough-Single Owner | tcstrough_empirical, singleowner |
Flat Plate PV-All Equity Partnership Flip | pvsamv1, equpartflip |
Flat Plate PV-Commercial | pvsamv1, utilityrate5, cashloan |
Flat Plate PV-Host Developer | pvsamv1, utilityrate5, host_developer |
Flat Plate PV-LCOE Calculator | pvsamv1, lcoefcr |
Flat Plate PV-Leveraged Partnership Flip | pvsamv1, levpartflip |
Flat Plate PV-None | pvsamv1 |
Flat Plate PV-Residential | belpe, pvsamv1, utilityrate5, cashloan |
Flat Plate PV-Sale Leaseback | pvsamv1, saleleaseback |
Flat Plate PV-Single Owner | pvsamv1, utilityrate5, singleowner |
Flat Plate PV-Third Party | belpe, pvsamv1, utilityrate5, thirdpartyownership |
Fuel Cell-Commercial | pvwattsv5_lifetime, fuelcell, battery, utilityrate5, thermalrate, cashloan |
Fuel Cell-Single Owner | pvwattsv5_lifetime, fuelcell, battery, utilityrate5, thermalrate, singleowner |
Generic CSP System-All Equity Partnership Flip | tcsgeneric_solar, equpartflip |
Generic CSP System-Commercial | tcsgeneric_solar, utilityrate5, cashloan |
Generic CSP System-LCOE Calculator | tcsgeneric_solar, lcoefcr |
Generic CSP System-Leveraged Partnership Flip | tcsgeneric_solar, levpartflip |
Generic CSP System-None | tcsgeneric_solar |
Generic CSP System-Sale Leaseback | tcsgeneric_solar, saleleaseback |
Generic CSP System-Single Owner | tcsgeneric_solar, singleowner |
Generic System-All Equity Partnership Flip | generic_system, equpartflip |
Generic System-Commercial | generic_system, utilityrate5, cashloan |
Generic System-Host Developer | generic_system, utilityrate5, host_developer |
Generic System-LCOE Calculator | generic_system, lcoefcr |
Generic System-Leveraged Partnership Flip | generic_system, levpartflip |
Generic System-None | generic_system |
Generic System-Residential | generic_system, utilityrate5, cashloan |
Generic System-Sale Leaseback | generic_system, saleleaseback |
Generic System-Single Owner | generic_system, singleowner |
Generic System-Third Party | generic_system, utilityrate5, thirdpartyownership |
Geothermal Power-All Equity Partnership Flip | geothermal, equpartflip |
Geothermal Power-LCOE Calculator | geothermal, lcoefcr |
Geothermal Power-Leveraged Partnership Flip | geothermal, levpartflip |
Geothermal Power-None | geothermal |
Geothermal Power-Sale Leaseback | geothermal, saleleaseback |
Geothermal Power-Single Owner | geothermal, singleowner |
High-X Concentrating PV-All Equity Partnership Flip | hcpv, equpartflip |
High-X Concentrating PV-LCOE Calculator | hcpv, lcoefcr |
High-X Concentrating PV-Leveraged Partnership Flip | hcpv, levpartflip |
High-X Concentrating PV-None | hcpv |
High-X Concentrating PV-Sale Leaseback | hcpv, saleleaseback |
High-X Concentrating PV-Single Owner | hcpv, singleowner |
ISCC-Single Owner | tcsiscc, singleowner |
MSLF-All Equity Partnership Flip | tcsMSLF, equpartflip |
MSLF-Commercial | tcsMSLF, utilityrate5, cashloan |
MSLF-LCOE Calculator | tcsMSLF, lcoefcr |
MSLF-Leveraged Partnership Flip | tcsMSLF, levpartflip |
MSLF-None | tcsMSLF |
MSLF-Sale Leaseback | tcsMSLF, saleleaseback |
MSLF-Single Owner | tcsMSLF, singleowner |
MSPT-All Equity Partnership Flip | tcsmolten_salt, equpartflip |
MSPT-Leveraged Partnership Flip | tcsmolten_salt, levpartflip |
MSPT-Sale Leaseback | tcsmolten_salt, saleleaseback |
MSPT-Single Owner | tcsmolten_salt, singleowner |
Physical Trough IPH-LCOH Calculator | trough_physical_process_heat, iph_to_lcoefcr, lcoefcr |
Physical Trough IPH-None | trough_physical_process_heat |
Physical Trough-All Equity Partnership Flip | tcstrough_physical, equpartflip |
Physical Trough-Commercial | tcstrough_physical, utilityrate5, cashloan |
Physical Trough-LCOE Calculator | tcstrough_physical, lcoefcr |
Physical Trough-Leveraged Partnership Flip | tcstrough_physical, levpartflip |
Physical Trough-None | tcstrough_physical |
Physical Trough-Sale Leaseback | tcstrough_physical, saleleaseback |
Physical Trough-Single Owner | tcstrough_physical, singleowner |
PVWatts-All Equity Partnership Flip | pvwattsv5, equpartflip |
PVWatts-Commercial | pvwattsv5, battwatts, utilityrate5, cashloan |
PVWatts-Host Developer | pvwattsv5, utilityrate5, host_developer |
PVWatts-LCOE Calculator | pvwattsv5, lcoefcr |
PVWatts-Leveraged Partnership Flip | pvwattsv5, levpartflip |
PVWatts-None | pvwattsv5 |
PVWatts-Residential | pvwattsv5, belpe, battwatts, utilityrate5, cashloan |
PVWatts-Sale Leaseback | pvwattsv5, saleleaseback |
PVWatts-Single Owner | pvwattsv5, singleowner |
PVWatts-Third Party | pvwattsv5, belpe, battwatts, utilityrate5, thirdpartyownership |
Solar Water Heating-Commercial | swh, utilityrate5, cashloan |
Solar Water Heating-LCOE Calculator | swh, lcoefcr |
Solar Water Heating-None | swh |
Solar Water Heating-Residential | swh, belpe, utilityrate5, cashloan |
Wind Power-All Equity Partnership Flip | windpower, equpartflip |
Wind Power-Commercial | windpower, utilityrate5, cashloan |
Wind Power-LCOE Calculator | windpower, lcoefcr |
Wind Power-Leveraged Partnership Flip | windpower, levpartflip |
Wind Power-None | windpower |
Wind Power-Residential | windpower, utilityrate5, cashloan |
Wind Power-Sale Leaseback | windpower, saleleaseback |
Wind Power-Single Owner | windpower, singleowner |
Version 1.1, April 15, 2019 ~ SAM 2018.11.11.3, SSC Version 208
- Group all modules under PySAM namespace
- Defaults for technology and financial models according to SAM GUI configurations
- Include PySSC with dictionary functions as subpackage
- Remove AdjustmentFactors group from non-technology modules
- Fix custom exception for use with multiprocessing package
- Documentation updates
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distributions
Hashes for NREL_PySAM-1.1-cp37-cp37m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c3b58903a07c88fbfa2aae800f20cac39e8871474791677285637987fc231f10 |
|
MD5 | 78f53fcb1042f7935944461668aa686e |
|
BLAKE2b-256 | e9eb2858a8265fbd4742bd28667096955cc03cc67d8b2c53470650ffe757b3b5 |
Hashes for NREL_PySAM-1.1-cp37-cp37m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3066533833cfeea040c678c38b1f91f9856d377c850532653b4667c5a16eba6e |
|
MD5 | fa97dcc84de095c1347b4ae2a7b7a9c5 |
|
BLAKE2b-256 | f901c6501de4ca81613ad8a1afefd74ebe4226ba48c0d9b3ab1d7f2b9d065ee5 |
Hashes for NREL_PySAM-1.1-cp37-cp37m-macosx_10_14_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | bdc34325e054d87d61f33ae1d71cb0958b878f086e27c518faedb99edfe00064 |
|
MD5 | df8c3a07aa5bb290bbe1a2ab79ecee8d |
|
BLAKE2b-256 | d7e03d909f4e3c7417c0cd968789674e815e6ea2c6a82046a23688c220368b8b |
Hashes for NREL_PySAM-1.1-cp36-cp36m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | cea2aa0587fe90ebf2c19da1ddacba2da4aa108eba0ca2fac0c3ef56653ad801 |
|
MD5 | 0918b2b42c90f33db5e6f7b9851beefb |
|
BLAKE2b-256 | 44833040a151803aafe6ed14cf49abed140caf96dd9385a52ea03e8bb82f1aa8 |
Hashes for NREL_PySAM-1.1-cp36-cp36m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c9f9a757c0c947c036051e9b55672350f21539a6c088aeb9b282b4d5eacebd60 |
|
MD5 | 6fdfed75b19053332d06dea1523322f1 |
|
BLAKE2b-256 | 591efabd72aca08f5a549b9bab848272c2b95ff8670fd2df9f660e59b9b78f5c |
Hashes for NREL_PySAM-1.1-cp36-cp36m-macosx_10_7_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 55809b563fd4cc19712595a730706e2124cc194b42c9f61904079e8970983c53 |
|
MD5 | f9d547d696db0a0e581c6acdd671ea63 |
|
BLAKE2b-256 | 2337dec8aaceda4c2926a755b38afac431547acb1c4526cd1d503ac25cbc250b |
Hashes for NREL_PySAM-1.1-cp35-cp35m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 92149ae67a414e1e6c027988ead40a1fa74c65d1925e476eab27b5a67e052534 |
|
MD5 | b44cb6c850812e646b7dc23838c4a21d |
|
BLAKE2b-256 | c6f4db2337b6f55a143356cb3cd6c608ad5272a17d7c1044c652085d1c185fdc |
Hashes for NREL_PySAM-1.1-cp35-cp35m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | fa922e2c67b68f2d7ffb00b35fc0020f0152e6ddfaba4a39531a31b0b25a5831 |
|
MD5 | 451dc77f7cffd6918154ec5d0d9f6e2d |
|
BLAKE2b-256 | e1dd5bc8ff3edc2bf1f1d3b955f72995ce593a6dc0bb851987a29713fdeb9e26 |
Hashes for NREL_PySAM-1.1-cp35-cp35m-macosx_10_6_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9486c9dca8ee7c1ec0cd869868e5e99d967eb0d286939072dd685d81bd167768 |
|
MD5 | 191d47ac0ac183f982672761ab19810c |
|
BLAKE2b-256 | 4a0223eb711ca8991af4631fe32683274af1be7c692b87d79e51cbd96ee4301f |