Getting Started

To get started using PySAM, install it as described in Installing PySAM, and then work through Example 1 and Example 2 below to familiarize yourself with how to set up a model with inputs from SAM, and how set up a complete configuration from defaults.

For a general description of PySAM, including the relationship between PySAM, SSC, and SAM, see PySAM Overview.

There are two ways to approach building a model in PySAM. The first, and the one we recommend, is to build the model in SAM and then export the inputs to use in PySAM as shown in Example 1 below and described in more detail in Importing Inputs from SAM.

The second approach is to create a model from defaults as described in Example 2. This approach does not require running SAM, but makes it harder to troubleshoot when you get unexpected results or errors. For more details on this approach see Accessing SAM Defaults.

If you are new to PySAM, work through these two examples to familiarize yourself with the process of building models in PySAM before building your own models.

Example 1: Build a Model from SAM

For this example, you will:

  • Create a model in SAM and use the PySAM documentation to identify a compute module’s input and output variables.

  • Export inputs from SAM to a JSON file.

  • Write a Python script to create the model in PySAM and then read and set inputs from JSON, run the model, and get outputs.

If you are new to SAM, download and install it from the SAM website at https://sam.nrel.gov/download.

This example uses SAM’s PVWatts – No Financial configuration to model a photovoltaic system with no financial model. This runs the pvwattsv8 SSC compute module, equivalent to the “Pvwattsv8” compute module in PySAM.

Create a PVWatts model in SAM

  1. Create a PVWatts / No financing case in SAM.

  2. On the System Design page, note the System nameplate capacity input.

  3. On the File menu, click Inputs browser and use the search box to find the variable name for the system nameplate capacity input. SAM’s inputs browser displays a table of all of the inputs in the case with both the SSC variable name and SAM variable label so you can quickly identify the name of the SSC variable you want to change in your Python script.

  4. Click Simulate to run a simulation and review results: On the Data Tables tab, you can see a list of all of the PVWatts outputs. Expand the Single Values section and check the box for the Annual AC output variable.

  5. Find the SSC variable name for the “Annual AC output” variable in the documentation for the Pvwattsv8 module.

Tip

You can use SAM’s LK script editor to find the SSC names of both input and output variables.

Export SAM inputs to JSON

  1. On SAM’s Case menu, click Generate code and choose PySAM JSON at the bottom of the list. This will create a folder with a JSON file and SSC library files.

  2. Open the JSON file in a text editor or web browser that renders JSON and find the system nameplate capacity input variable to confirm that it was exported with the correct value. By default, the JSON file is named untitled_pvwattsv8.json.

Write the Python script

Create a new .py file for your script and save it in the same folder as the JSON file. This script runs the Pvwattsv8 module twice: Once with the JSON inputs from SAM, and once after modifying the system capacity input. Run the script, and then run SAM to compare the value of the Annual AC variable.

import json
import PySAM.Pvwattsv8 as pv # import the PVWatts module from PySAM

# create a new instance of the Pvwattsv8 module
pv_model = pv.new()

# get the inputs from the JSON file
with open( 'untitled_pvwattsv8.json', 'r') as f:
        pv_inputs = json.load( f )

# iterate through the input key-value pairs and set the module inputs
for k, v in pv_inputs.items():
    if k != 'number_inputs':
        pv_model.value(k, v)

# run the module
pv_model.execute()

# print results
print('Annual AC output for {capacity:,.2f} kW system is {output:,.0f} kWh.\n'.format(capacity = pv_model.value('system_capacity'), output = pv_model.Outputs.ac_annual) )

# run PVWatts for a series of nameplate capacities
capacities = [10, 100, 1000]
for c in capacities:
    # change the value of the system_capacity input
    pv_model.value('system_capacity',c)
    # run the module
    pv_model.execute()
    # print some results
    print('Annual AC output for {capacity:,.2f} kW system is {output:,.0f} kWh.'.format(capacity = pv_model.value('system_capacity'), output = pv_model.Outputs.ac_annual) )

For the first model run, the results for Annual AC Output in SAM and PySAM should be the same. If they aren’t, compare the inputs in the JSON file to those in SAM and make sure the input values are the same. You can also change the system nameplate capacity in SAM to 10, 100, and 1000 kW to verify that PySAM’s results are the same as SAM’s.

Note

For this simple example, comparing the JSON file to the SAM inputs is reasonable because Pvwattsv8 has a relatively small number of inputs. As you build more complex models, you will find that the modules have more inputs than it is practical to compare manually in this way.

Also, changing the system nameplate capacity in this way is possible with PVWatts, but not for other performance models including the Detailed PV model and CSP models because of Interdependent Variables. For those models, you have to inputs like Number of Strings in Parallel for the Detailed PV model, or Design Turbine Gross Output for the CSP models.

Example 2: Build a Model from Defaults

In Example 1, we created a simple model of a photovoltaic system with a single Pvwattsv8 compute module. In Example 2, we create a model for a complete PVWatts - Single Owner configuration using default input values.

A SAM configuration is a combination of a performance model and financial model that represents a renewable energy project. Each configuration consists of a series of compute modules that must be executed in the correct order.

Note

PySAM defaults do not include the renewable resource data file (solar, wind, wave or tide) from SAM, so when you use set up a configuration from defaults, you must have a weather file ready to use for the simulation. For the example script below, we assume you used SAM’s Location and Resource input page to download a weather file for Denver, CO to SAM’s default “SAM Downloaded Weather Files” folder. (Some compute modules allow resource data input as a dictionary instead of file, see the module documentation for details.)

See Accessing SAM Defaults for more details.

import os # need this to get user path for weather file

# import compute modules required for the PVWatts - Single Owner configuration
import PySAM.Pvwattsv8 as pv
import PySAM.Grid as gr
import PySAM.Utilityrate5 as ur
import PySAM.Singleowner as so

# create an instance of the Pvwattsv8 module with defaults from the PVWatts - Single Owner configuration
system_model = pv.default('PVWattsSingleOwner')

# create instances of the other modules with shared data from the PVwattsv8 module
grid_model = gr.from_existing(system_model, 'PVWattsSingleOwner')
utilityrate_model = ur.from_existing(system_model, 'PVWattsSingleOwner')
financial_model = so.from_existing(system_model, 'PVWattsSingleOwner')

# use weather file downloaded from SAM as "denver, co", you can replace this with a path to any valid weather file in the SAM CSV format
filename = os.path.expanduser('~') + '/SAM Downloaded Weather Files/denver_co_39.7385_-104.985_psm3-tmy_60_tmy.csv'
system_model.SolarResource.solar_resource_file = filename

# run the modules in the correct order
system_model.execute()
grid_model.execute()
utilityrate_model.execute()
financial_model.execute()

# display results
print( 'Annual AC Output in Year 1 = {:,.3f} kWh'.format( system_model.Outputs.ac_annual ) )
print( 'Net Present Value = ${:,.2f}'.format(financial_model.Outputs.project_return_aftertax_npv) )