nrel/sam

System Advisor Model (SAM)

System Advisor Model (SAM)

The SAM Open Source Project repository contains the source code, tools, and instructions to build a desktop version of the National Renewable Energy Laboratory's System Advisor Model (SAM). SAM is a simulation program for electricity generation projects. It has models for different kinds of renewable energy systems and financial models for residential, commercial, and utility-scale projects. For more details about SAM's capabilities, see the SAM website at https://sam.nrel.gov/.

For a short video describing the SAM repositories, see https://youtu.be/E5z1iiZfZ3M.

The SAM release notes are in https://github.com/NREL/SAM/blob/gh-pages/doc/releasenotes.html.

The desktop version of SAM for Windows, Mac, or Linux builds from the following open source projects:

• SSC is a set of "compute modules" that simulate different kinds of power systems and financial structures. It can be run directly using the SAM Software Development Kit. This is the source code for SAM's models, and is the repository to use for researching the algorithms underlying the models.

• LK is a scripting language that is integrated into SAM. SAM's user interface uses LK to calculate values to display on input pages. The user interface includes a script editor that allows users to write their own scripts from the user interface.

• wxWidgets is a cross-platform graphical user interface platform used for SAM's user interface, and for the development tools included with SSC (SDKtool) and LK (LKscript).

• WEX is a set of extensions to wxWidgets for custom user-interface elements developed specifically for SAM, LK script, and DView.

• Google Test is a C++ test framework that enables comprehensive unit-testing of software. Contributions to the project will eventually be required to have associated unit tests written in this framework.

• jsoncpp is a C++ library that allows manipulating JSON values, including serialization and deserialization to and from strings.

• Python/Miniconda is for integration of Python scripts with the SAM user interface.

This repository, SAM, contains the code for SAM's user interface that assigns values to inputs of the SSC compute modules, runs the modules in the correct order, and displays simulation results. It also includes tools for editing LK scripts, viewing time series results, and generating shade data from a 3-dimensional representation of a photovoltaic array or solar hot water collector and nearby shading objects.

The SAM repository also includes two libraries from Sandia National Laboratories, stepwise, and LHS, which are distributed as part of the Dakota platform, licensed under LGPL.

Building SAM

For build instructions see the wiki with specific instructions for:

• Windows
• Mac
• Linux

Contributing

If you would like to report an issue with SAM or make a feature request, please let us know by adding a new issue on the issues page.

If you would like to submit code to fix an issue or add a feature, you can use GitHub to do so. Please see Contributing for instructions.

License

SAM's open source code is copyrighted by the Alliance for Sustainable Energy and licensed with BSD-3-Clause terms, found here.

The stepwise and LHS LGPL licensed libraries from Sandia National Laboratories are pre-compiled Fortran libraries that are included in the SAM repository as binaries in the Sandia folder. You can replace the binaries with different versions by compiling your own version and replacing the binary/executable viles in the Sandia folder.

Citing this package

System Advisor Model Version 2023.12.17 (2023). SAM source code. National Renewable Energy Laboratory. Golden, CO. Accessed December 18, 2023. https://github.com/NREL/SAM

sam's Issues

Update PV sizing macro

Make sure we upload the latest and greatest of Abhi's new PV sizing macro

Solar Resource download options not clear on Location and Resource page

"Download a weather file for your location" downloads PSM data as TMY files works for NSRDB locations in Western Hemisphere, but not SUNY locations in Asia.

"Choose files to download (advanced)" works for all locations and all data sets, and downloads data as both TMY files or single-year files, and can download multiple files for P50/P90 simulations.

Error saving & loading "Time of Day" schedules and factors

Hi there - There seems to be an issue with loading and saving schedule data (specifically in the 'Time of Delivery Factors' tab).

Recieve a popup message, which appears to be generated by SAM:

"Data load failed"

Or

"Data save failed"

And another popup message, that seems to be system generated:

"can't open file '/path/to/csvfile.csv' (error 2: No such file or directory).

(Files definitely exist)

Using SAM on Linux (Version 2017.1.17, 64 bit, updated to revision 4)
SSC Version 174: Linux 64 bit GNU/C++ Jun 19 2017 05:06:12
wxWidgets 3.1.0 on Linux 4.10.0-32-generic x86_64
Internet connection method: default

Linux build improvements

Currently the Linux build requires a folder hierarchy looking like:

/workspace
/workspace/lk
/workspace/wex
/workspace/ssc
/workspace/SAM
/workspace/googletest

The Linux build can be improved in the following ways:

1. Require the assignment the following as environment variables:
   LKDIR - /path/to/lk
   WEXDIR - /path/to/wex
   SSCDIR - /path/to/ssc
   SAMNTDIR - /path/to/SAM
   GTEST - /path/to/googletest

2. Update the Linux Makefiles to use these environment variables rather than forcing a specific folder hierarchy.

Unable to build sam.bin

This has never worked for me in the Linux build. Am I doing something obviously wrong? I suspect it is related to the problem I am having building SDKtool (see SSC issue number 80). Thanks.

g++ -g -o sam.bin ide.o lossdiag.o defmgr.o s3engine.o s3objects.o s3tool.o s3view.o stochastic.o urdb.o nsrdb.o windtoolkit.o gridsupport.o macro.o p50p90.o reports.o script.o graph.o excelexch.o simulation.o library.o results.o ipagelist.o casewin.o invoke.o case.o main.o equations.o inputpage.o uiobjects.o lossadj.o widgets.o variables.o project.o object.o variablegrid.o parametric.o welcome.o ptlayoutctrl.o troughloop.o shadingfactors.o materials.o codegenerator.o -std=c++11 ssc.so /home/bje/source/lk/lkuxwx3.a /home/bje/source/wex.nrel/wexuxwx3.a `wx-config-3 --libs propgrid` `wx-config-3 --libs aui` `wx-config-3 --libs stc` `wx-config-3 --libs richtext` `wx-config-3 --libs` -lm -lstdc++ -lcurl
/usr/bin/ld: /home/bje/source/wex.nrel/wexuxwx3.a(pdffontmanager.o): undefined reference to symbol 'FcPatternAddInteger'
//usr/lib/x86_64-linux-gnu/libfontconfig.so.1: error adding symbols: DSO missing from command line

Electricity bill calculation improvements

• Apply end-of-year credit to following year for California NEM: https://sam.nrel.gov/forum/forum-general/1159

• Change month for end-of-year kWh rollover credit
  For Residential and Commercial financial models, SAM applies any kWh rollover credits remaining in December 31 to the December electricity bill. Some states specify a different month, for example Maryland is end of April. Request is to add an input to specify the month for the "end of year" credit: https://sam.nrel.gov/forum/forum-general/1824. Duke Energy NC "resets accumulated excess on May 31" https://sam.nrel.gov/forum/forum-general/2170

• Allow separate TOU schedules for Saturday and Sunday per NamPower rates in Namibia: https://www.nampower.com.na/Page.aspx?p=178, and also as typical in South Africa: https://sam.nrel.gov/forum/forum-general/2969

Wind Resource Histogram macro appears in all configurations

The macro only works for Wind configurations, so should be moved to a new "Wind Power" folder in the runtime/macros folder.

Model utility rate structures with California baseline electricity use

Some references:

http://www.cpuc.ca.gov/General.aspx?id=12186

SCE Tiered Rate Plan

From SAM user Joe C:

The way it works is:

All kWh have the same rate in $/kWh regardless of time of day

A discount $/kWh is applied to all kWh used each day, up to the Baseline Maximum, regardless of the time of use

I’m not sure what rate plan you are displaying below, but it does not look like the current PG&E TOU rates, which is:

Summer

Peak (3-8pm) $.39479

Off-Peak (8pm-3pm) $.39479

Baseline Usage Discount -$.08874

Baseline usage is defined for several geographic areas within PG&E territory

Baseline usage is a daily total, not a daily total for each TOU period

Winter – similar with different rates and different Baseline usage, and the same discount

Peak (3-8pm) $.27682

Off-Peak (8pm-3pm) $.27682

Baseline Usage Discount -$.08874

Baseline usage is defined for several geographic areas within PG&E territory

Baseline usage is a daily total, not a daily total for each TOU period

If I could have a Period 0 that applies to all periods, I could set up it up so that a discount is applied to the total usage each day, up to the daily Baseline maximum. However, if the discount amount is changed so that it’s different in winter versus summer, I would need two such periods.

PGE’s newest residential TOU rate plan is used by new solar customers. It has different TOU rates for inter versus summer. It’s sort of a tiered rate, but not exactly, so I’m having a hard time figuring out how to use it in SAM.

PG&E E-TOU Option A rate
TOU 3-8pm, different rates for summer and winter
Each geographic region in PG&E’s territory has a number of “Baseline” kWh each day, different in summer and winter
The Baseline kWh usage determines if the energy purchased is at the full rate, or a discounted rate
Example: say Baseline is 10 kWh per day in the summer, the first 10 kWh of purchased energy each summer day are at the full TOU rate, less a discount, all additional purchased energy each day is full rate.
However, the discount is applied to the first 10 kWh purchased each day, regardless of the TOU period – some can be during period 1, and some can be during period 2

More specifically, the rates (approximate) are:

Summer Peak $.39/kWh
Summer Off-peak $.32/kWh
Discount of $.09/kWh applied to the Baseline kWh each day, regardless of period.

If I could have tiers separate from TOU, I would assign a discount of -$0.09 to tier 1 up to 10 kWh per day, and a discount of $0.00 to tier 2 up to maximum hours per day. But, I don’t see how this is possible.

I could make an assumption that all of the discount is applied in one TOU period or the other, but this is not very accurate.
I could make an assumption that approximately half of the Baseline kWh each day are purchase in each TOU period. This might be more accurate, but not really okay.
I believe NEM 2 requires a true-up every day, so it’s fairly important that this is accurate.
It may not matter so much with a system that offsets a high percentage of usage, in which case most energy purchased will be at the discounted rate, but that’s not always the case.

SHW model: no way to get cost of auxiliary energy

It seems that there is no way to get an output variable in SAM for the dollars per year spent on auxiliary energy in the solar hot water model. You can get cost with system, cost without system, etc., but these include pumping energy, etc. All I want to know is how much money is being spent on auxiliary boosting of the tank?

Cash flow send-to-Excel issue with tax rates as schedule

Applies to Residential/Commercial financial models only. See https://sam.nrel.gov/node/75102 for details.

SWH auxiliary gas macro conversion error

For a solar DHW system, I understand that SAM only calculates savings in kWh. There is a macro to run using an auxiliary gas water heat that gives the savings in kWh. Converting to BTU or therms is easy enough. However, with the 2017 version on SAM, I'm seeing results that suggest an error. The scale of auxiliary gas water savings is very low.

As an example, using the default system that opens up in SAM's residential solar water heating module, I get 2,407 kWh of annual savings for the electric water heater, but only 3 kWh savings when using the gas water heater macro. In a prior version of SAM I was getting comparable kWh or BTU savings between an electric and gas water heater (adjusting for water heater system efficiencies).

Using basic energy conversion factors, I'm seeing an 2 order of magnitude or greater issue. I also allow that I may be misunderstanding what I'm doing or seeing, but I'm not convinced that the case. The solar fraction for electric is 0.68 and for gas is 0.62. 3 kWh savings and a 0.62 solar fraction are not in alignment.

https://sam.nrel.gov/node/75395

CEC module library has duplicate entries

For the following modules:

['Silevo_Triex_U310_Black', 'Solartec_S72MC6_290', 'Solartec_S72MC6_295',
'Solartec_S72MC6_305', 'Solartec_S72MC6_310', 'Solartec_S72MC6_315']

It looks like the parameter values and date are different, although the module names are the same. It would be useful to clarify if the duplicates result from two separate test evolutions reported to the CEC, or from re-analysis of a single test report but using a different process.

Handling of missing data

The EPW and TMY3 file formats specify special values for missing data, but lib_weatherfile.cpp does not appear to observe these. It treats these as literal values, giving haphazard results without any warning. It would be useful for SAM to either do sensible interpolation or at least notify the user of any missing data values it is using.

Fix System Sizing Callback

Detailed PV System Sizing callback needs some updating (see the residential auto-sizing case as an example of how bad it is). It would be nice to do this before the next release.

Wind model simulation crashes when using weather file downloaded from NREL WIND Toolkit

https://sam.nrel.gov/node/75805

To replicate, create a new wind case with no financials, click Download on Wind Resource page, and then OK to use default location for WIND Toolkit download. After file downloads, run a simulation.

Report generator graphs don't show y-axis values

LK script does not set om_production

An LK script that sets an Excel cell to the value of om_production ("Variable cost by generation") has no effect. It works for other variables such as om_fixedmodulecost, om_fuel_cost, etc.

Direct steam power tower model ITD at design and condenser pressure ratio not editable

Solution is to change property of I_ITD_des and P_cond_ratio input variables on PBNS Power Block UI form from not editable to editable.

PV report generates errors

Battery lifetime simulation with 3rd party ownership doesn't work

It appears that if you run a PV+battery with a 3rd party ownership model and lifetime mode, the simulation will run and return: "Replacements are enabled without running lifetime simulation, please run over lifetime to consider battery replacements". Essentially, it seems as if the simulation is run in single-year mode regardless of whether lifetime is selected.

Send-to-Excel cashflow workbook issue with single value income tax rate

State and federal income tax rates are now input as arrays and correctly exported to the workbook, but need to remove the single value in the input table (toward the top of the workbook) to avoid confusion. Best solution would be to use the single value when the array length is 1, and set it to "see below" string when array length > 1.

Request TOU demand rates based on contracted prediction of peak kW

From SAM support conversation https://sam.nrel.gov/forum/forum-general/1854-demand-charge-for-spanish-bills.html#5787:

The maximum power is what is registered in every TOU. The contracted power is what you sign with your electricity commercializer in every TOU (it is based on your demand prevision and there is a lot of benefits optimicing it with control data). So the demand charge depends on if the maximum power is under or over the contracted power, that's what I tried to explain in my first message. In this kind of bill the calculation is always done by the contracted power, except when your maximum power is between the 85 % and the 105 % of your contracted power. It is difficult to understand even for us.

This is based on a Spanish tariff structure -- not sure if a similar structure is being considered or in force in the U.S. or other countries.

Questionable inverter data from CEC

Some of the inverter data in the CEC database is incorrect.

In particular, data for some Enphase inverters has been reported to be incorrect. We have received the corrected data and will release in the next patch.

Improved weather file validation

When selecting a weather file "from your computer" (using the Browse button), it would be good if detailed validation of the file could be done before running the simulation and discovering there is a problem.

Finalize weather interpolation script

Include any feedback on the new weather interpolation script

PV PDF report does not show values needed to calculate performance ratio

The "POA kW/m2/day" value in the report is the irradiance incident on the cell, not on the top of the module surface. The performance ratio calculation is based on the nominal irradiance on the top of the module surface. (All of the values necessary to calculate performance ratio are available on SAM's Results page.)

The units "kW/m2/day" units in the PDF report are incorrect. The should be "kWh/m2/day" and are annual totals.

PV Report Template issue with TPO PPA price

Within the PV Report, there is an issue with the third-party ownership PPA price being displayed as 0.

Solar hot water model lacks azimuth & tilt helper image

The PV model includes a little diagram (System Design -> Tracking & Orientation pane) that helps people in the southern hemisphere work out the right azimuth value. The tilt diagram is also useful. Can these be included in the Solar Hot Water -> System pane?

Request up to 36 TOU periods for electricity rate structures

This is for a CFE (Mexico) rate structure:

https://sam.nrel.gov/node/75299, now at https://sam.nrel.gov/forum/forum-general/1856

Note that the rates also change every year, so even with the additional TOU periods, the rate structure data will not match the actual rates.

modules for hydrogen electrolysis

Hi ! I would like to add new modules to SSC library in ordre to build model for production of hydrogen using eletrolysis (The eletricity needed in electrolysis of water will be generated from PV/CSP system). I'm not sure how to get started, so wanted to touch base with your team to plan how I can add this new feature.

Clean up timeseries TOD factor input

Clean up timeseries TOD factor input

New feature to show solar resource files closest to a given lat/long

The Passivhaus Planning Package (PHPP) has a nice feature that could be replicated in SAM. The user enters a lat/long and SAM would show (under "Location and Resource") half a dozen or so of the closest locations in the library.

Add error checks for database specs

NREL doesn't maintain the CEC module and inverter databases, but sometimes the specifications in the CEC databases are wrong. We encourage users to report the issues directly to the CEC; however, it might be nice to also have a few simple mechanisms in place to alert the user that the specs for the component they've chosen look suspicious.

For both the inverter and the modules, we could display some warnings (probably in the UI?) when specs are either not physical (negative or zero voltages, etc) or not self-consistent (voltage and current don't multiply to the same order of magnitude as power, etc). More thought is needed to figure out what we could check for, and how to best display it.

Add an ssc_copy method

When running an ssc_exec simulation through a SAM lk script or callback, it would be nice to be able to set up the ssc_create() with a copy of the existing SAM environment.

Power tower heliostat availability not used in simulations

Heliostat availability is used in design calculations but not during performance simulations. Workaround solution is to use the Constant loss in the Edit Losses window to represent heliostat availability.

Rename "string inverters" button on losses page

It should say Central inverters (we labeled this button before there was really a difference between string inverters and central inverters)

SWH Auxiliary Gas Heater macro units issue

Remove conversion of results from W to kW now that they are reported in kW.

Bug in Solar Resource Interpolation

15324_19.73_-156.06_2015.csv.zip
In the Macro "Solar Resource Interpolation", if I try to use "Same as Load" for the attached file, when the load is 15-minutes, I get the error: "Macro did not finish", [754] runtime exception at line 754: access violation: expected numeric, but found null".

If I select the interval length as 15 min directly, it appears to work, but oddly outputs the file in C:\users<username>\SAM weather files, rather than the location of the original file

Requests for ratcheting demand rates

Demand ratchets: https://sam.nrel.gov/forum/forum-general/1164

Topic on old forum not on Wayback Machine: https://sam.nrel.gov/node/75891

Australia kVA with rolling capacity demand charges: https://sam.nrel.gov/forum/forum-general/1341

From Owen Z 5/11/2021:

Demand Ratchets / Minimum Billing Demands – These are already ubiquitous among commercial and industrial customers, but not currently represented in SAM (although you can sometimes calculate a workaround using the minimum bill function, but not in a super streamlined manner). If I define “Billing Demand” as the amount of kW that are billed (and thus gets multiplied by the demand charge), these are usually not as simple as just the peak 15- or 30-minute demand during the month. Usually, they are specified as something like this:

The Billing Demand shall be the highest of the following:
(a) Actual maximum demand measured during the month
(b) 75% percent of maximum demand over the previous 12 months
(c) 30 kW

This is just an example, but you get the point. Option (b) is referred to as a Demand Ratchet, and it’s a way to make sure that distribution utilities recover their costs! There are some more nuances to this whole area, but this is the general gist.

Shading_bug branch merged into develop but not patch_release

3d shading bug fixed in Shading_bug branch and merged into develop but never updated in 2017.9.5.r3 or patch_release branch - see https://sam.nrel.gov/node/75819

Third Party Ownership model does not include load download macros

Need to decide whether to include "Download Electric Load" macro for residential buildings or commercial buildings, or both.

Updating solar resource library

In the windows SAM build instruction, step 6 suggest to "Start a new project" on SAM's welcome page. However, after I click the bottom, a window comes out saying "Updating solar resource library..." and after a few minutes, the program stops.

Do you know how to solve this problem? Thanks!
Regards,
Kangqian

Can't parse "CEC Inverters.csv" library - what does "C2=-1.#IND" mean ?

In the latest CEC Inverters.csv library, the very first entry, on L4, for "AAA Perfect Tech A-1 Perfect Inverter 500V [CEC 2016]" has the value in the C2 column set to -1.#IND which doesn't parse to a float or any numeric. What is it supposed to mean? Is this special to SAM?

SAM/deploy/libraries/CEC Inverters.csv

Line 4 in e3ec5ff

AAA Perfect Tech: A-1 Perfect Inverter 500V [CEC 2016],500,1000000,1.00E+06,500,0,-1.38E-16,0,-1.#IND,0,0,1000,1000,0,1000

Stochastic simulations show computed samples and issues with large number of samples

1. Would be helpful to show computed samples in table of results: See https://sam.nrel.gov/forum/forum-general/1838-samples-don-t-correspond-to-output-in-stochastic-analysis.html#5730 for details.

2. Stepwise.exe crashes for 1000 or more samples, and progress bars get stuck between 800 and 900 samples: See https://sam.nrel.gov/forum/forum-general/1840-stochastic-analysis-1-000-samples-breaks-regression-999-does-not.html#5738 for details

CEC inverter file has entry with missing values

Line 2508:

LeadSolar Energy: LS600T [208V] 208V [CEC 2018],208,500,75790.4,36,-nan(ind),1.22899e-07,-0.0251886,-nan(ind),0.0798754,1,45,2105.29,27,45

Solar Resource download buttons not clear on Location and Resource page

"Download a TMY file for Americas" downloads PSM data as TMY files works for NSRDB locations in Western Hemisphere, but not SUNY locations in Asia.

"TMY or Single-year for Americas and Asia" works for all locations and all data sets, and downloads data as both TMY files or single-year files, and can download multiple files for P50/P90 simulations.

Consider integrating all download functionality into a single window that can be accessed by one button, and using small map images to make it clear what world regions are covered. Also need to add code to download PVGIS data when their API becomes stable.

http://re.jrc.ec.europa.eu/pvg_tools/en/tools.html#TMY

http://re.jrc.ec.europa.eu/pvg_static/web_service.html

This is related to #54, which we resolved with a temporary solution.

PVWatts: Tilt and Azimuth in 2-Axis Tracking Systems

In PVWatts UI, the tilt and azimuth variables are not appropriately grayed out for the 2-axis tracking systems, even though they are meaningless and not used.

Basic report template does not work for all configurations

Excel Exchange fails to open Excel file

See post on SAM support forum for details and a workaround solution:

https://sam.nrel.gov/node/75533

Labels for generic system model input variables are misleading: Energy kWh vs power kW

Labels on the Generic System Plant UI form and the descriptions in Help are misleading because they are based on the old assumption that input vectors are hourly and could be described either in kWh/h or kW. Now that the vectors can be subhourly, need to be clear that the vectors require kW values.