To import a case from the SAM GUI

Export from SAM GUI

On the drop-down menu for the case, click Generate code then PySAM JSON, which will export the case inputs to a JSON file per PySAM module. Each JSON file name will have the case name prefixed to the PySAM module name.

Move the data into the appropriate PySAM Module Classes

For each PySAM module required for the simulation (see SAM Simulation Configurations), import the module, and create the sequence of simulations using from_existing. Then, read the input data from the JSON files.


Suppose we wish to make a python script that replicates the simulation SAM does for a PVWatts Distributed Commercial installation. There will be a JSON file generated by SAM for each of these modules: pvwatts7, grid, utilityrate5, and cashloan. The order of the modules can be found in (SAM Simulation Configurations). The from_existing function (see Writing Your First PySAM Script) allows different modules to share the same underlying data.

import json
import PySAM.Pvwattsv7 as PVWatts
import PySAM.Grid as Grid
import PySAM.Utilityrate5 as UtilityRate
import PySAM.Cashloan as Cashloan

pv =
grid = Grid.from_existing(pv)
ur = UtilityRate.from_existing(pv)
cl = Cashloan.from_existing(pv)

The json files exported from the SAM GUI are then collected in order.

dir = "/Users/dguittet/SAM-Dev/PySAM Json/"
file_names = ["untitled_pvwattsv7", "untitled_grid", "untitled_utilityrate5", "untitled_cashloan"]
modules = [pv, grid, ur, cl]

Then read the data from the json into the models.

for f, m in zip(file_names, modules):
with open(dir + f + ".json", 'r') as file:
    data = json.load(file)
    for k, v in data.items():
        if k != "number_inputs":
            m.value(k, v)

Execute the sequence of models

Downsteam models require upstream model outputs as inputs. Since the underlying data between pv, ur and cl are shared due to the from_existing function, the outputs of pv required as inputs to ur and cl will automatically be accessible to them. To execute a model, 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.

Example (Continued)

Here we continue our example.

for m in modules:

We can then print out some of the data. The variable and group names are found in the Modules.

print('ac_annual: ', pv.Outputs.ac_annual)
print('ur_ec_tou_mat: ', ur.ElectricityRates.ur_ec_tou_mat)
print('cl.Outputs.npv: ', cl.Outputs.npv)

Possible Problems

You probably noticed that in SAM, there are black and blue input variables. The blue ones are calculated by the SAM GUI from the black ones. 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.

In each PySAM Module’s page, each variable that may be affected by such equations will have a “Changes to this variable may require updating the values of the following” and “This variable may need to be updated if the values of the following have changed” section to provide suggestions for which variables may be affected upstream or downstream.

For greatest detail, 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