nrel / ssc

SAM Simulation Core (SSC) contains the underlying performance and financial models for SAM

SSC (SAM Simulation Core)

The SSC Open Source Project repository contains the source code for the technology and financial models contained within the National Renewable Energy Laboratory's System Advisor Model (SAM). For more details about SAM's capabilities, see the SAM website at https://sam.nrel.gov/.

You could think of SSC as the home for the algorithms behind the SAM desktop program. Most people run the code through the desktop user interface, but SSC can also be run directly using the SAM Sofware Develoment Kit.

SSC requires building four other open-source projects:

• Google Test
• LK
• wxWidgets
• WEX
• jsoncpp

However, if you remove SDKtool and TCSconsole from your SSC project, you can build SSC without any other software dependencies. Please see the main SAM project wiki for complete build instructions and software dependencies.

SSC directly includes source code from three other open-source projects, and builds them as part of its build process. These projects and their respective licenses are:

• NLopt - code located here, LGPL license
• lp_solve - code located here, LGPL license
• splinter - code located here, MPL license

To explore the code and understand the algorithms used in SSC, start by looking in the "SSC" project at the compute modules (files starting with cmod_) to find the compute module for the technology or financial model of interest.

Contributing

Please see the contribution guidelines in the main SAM project readme.

License

SSC is licensed with BSD-3-Clause terms, found here.

Citing this package

System Advisor Model Version 2023.12.17 (2023). SSC source code. National Renewable Energy Laboratory. Golden, CO. Accessed November 28, 2023. https://github.com/NREL/ssc

ssc's Issues

Simulation progress window blocks other applications in Mac OS

See https://sam.nrel.gov/node/74929 for details including a screenshot.

Battery model replace at specified year not working

When you run a PV+Battery case in lifetime mode, and specify the battery to be replaced at specific years in the simulation, the battery is not replaced and continues to degrade or not operate.

Lead-acid battery replacement oddity

There is something odd with the SAM lead acid battery model with lookahead dispatch. It happens when the first battery hits the replacement threshold. It looks like the battery is not utilized after the first replacement.

SAM Version 2017.9.5 Test-lifetime, lookahead.zip

Implementation of function for module spectral mismatch considering precipitable water

The PVPerformance Modelling Collaborative defines two equations that can be used to describe the spectral behavior of a PV module:

1. Based on the Sandia PV Array Model: A 4th degree polynomial with five coefficients defining a spectral mismatch modifier as a function of Air Mass.
2. Based on research by Lee/Panchula from First Solar: A function with six coefficients defining spectral mismatch as a function of air mass and precipitable water.

To my knowledge, only the first function is currently implemented and used in SAM/SSC in several modules. My suggestion would be to implement the second function as well and make it available as a user input at least in the IEC61853 model.

Very Rarely Encountered Bug with Sunrise/Sunset Calculation

Lines 268-269 in lib_irradproc.cpp employ a shortcut from the original equations that works fine when the time zone and longitude have the same sign (e.g. both positive or both negative), but there are a very few locations in the world where the time zone is positive and the longitude is negative (near the Samoan islands) that the shortcuts don't work. Need to decide whether to institute the "correct" fix, which involves changing the convention for all longitudes/time zones, or a quicker fix that checks for the signs to be the same. Affects both PVWatts and Detailed PV.

query in tcs/sam_mw_trough_type250.cpp

When compiling sam_mw_trough_type250.cpp with clang, the following warnings are produced. reguess_args is an array of doubles, so it is never NULL. What is intended here?

../tcs/sam_mw_trough_type250.cpp:3051:6: warning: comparison of array 'this->reguess_args' equal to a null pointer is always false
      [-Wtautological-pointer-compare]
                if(reguess_args == NULL) goto lab_reguess;
                   ^~~~~~~~~~~~    ~~~~
../tcs/sam_mw_trough_type250.cpp:3090:8: warning: comparison of array 'this->reguess_args' not equal to a null pointer is always true
      [-Wtautological-pointer-compare]
                                if(reguess_args != NULL){
                                   ^~~~~~~~~~~~    ~~~~
../tcs/sam_mw_trough_type250.cpp:3102:8: warning: comparison of array 'this->reguess_args' not equal to a null pointer is always true
      [-Wtautological-pointer-compare]
                                if(reguess_args != NULL){
                                   ^~~~~~~~~~~~    ~~~~

uninitialised variables in GTI_DIRINT (lib_irradproc.cpp)

g++ warns about uninitialised variables in GTI_DIRINT():

../shared/lib_irradproc.cpp:633:28: warning: ‘poaBest[2]’ may be used uninitialized in this function [-Wmaybe-uninitialized]
../shared/lib_irradproc.cpp:631:28: warning: ‘poaBest[0]’ may be used uninitialized in this function [-Wmaybe-uninitialized]
../shared/lib_irradproc.cpp:632:28: warning: ‘poaBest[1]’ may be used uninitialized in this function [-Wmaybe-uninitialized]

There is an execution path that leads to these variables being accessed uninitialised (ie. if fabs(diff) is never less than fabs(destDiff). Rather than just zeroing this array, I think it makes sense for someone else to check the code. This may be demonstrating a logic bug.

3D Shading Bug

There may be a new bug in the 3D shade calculator that wasn’t there in SAM 2017.1.17 r4. I think it is caused by objects below the active surface, even though they are not “touching.” For the attached shading scene, the time series shading factors generated by the calculator for PVWatts are:

In SAM 2017.9.5 – this looks wrong:

In SAM 2017.1.17 - this looks reasonable

IPH Trough model does not work with custom HTF property tables

Reported in https://sam.nrel.gov/node/75714

query: variables assigned to themselves

clang reports the following warnings when compiling tcs:

../tcs/sam_pf_dish_parasitic_type298.cpp:512:16: warning: explicitly assigning value of variable of type 'double' to itself [-Wself-assign]
                                        fan_speed =  fan_speed;
../tcs/sam_pf_dish_parasitic_type298.cpp:799:10: warning: explicitly assigning value of variable of type 'double' to itself [-Wself-assign]
                        P_fan = P_fan;
../tcs/sam_pf_dish_parasitic_type298.cpp:808:16: warning: explicitly assigning value of variable of type 'double' to itself [-Wself-assign]
                        P_tower_fan = P_tower_fan;
../tcs/storage_hx.cpp:100:18: warning: assigning field to itself [-Wself-assign-field]
        m_max_q_htr_hot = m_max_q_htr_hot;
../tcs/csp_solver_pt_sf_perf_interp.cpp:373:16: warning: assigning field to itself [-Wself-assign-field]
        m_v_wind_prev = m_v_wind_prev;

What was intended in each case?

Subhourly wind resource data bug

Address issue sent to team 11/15/17 regarding subhourly resource data. It appears the nstep variable was not being updated with the proper number of records, and was assumed to be hourly always.

lib_irradproc.cpp calls exit()

This library code calls exit(1) which seems to be wrong to me.

ssc/shared/lib_irradproc.cpp

Line 674 in c49793e

exit(1);

Won't this give users the impression that SAM has crashed?

Output error if temp or WS not in weather file (PV)

If temperature or wind speed is missing from the weather file in the PV model, we need to output a useful error.

Consideration of site slopes in module self-shading calculations

Currently, the self-shading calculations in SSC/PVSAMV1 consider all PV array rows to be mounted in one horizontal plane. However, in reality, many ground-mount PV systems are built on sloped surfaces. While in the end, considering the actual topography of a site is required in more complex cases, one simple and helpful first step to consider more complex topographies would be to consider the average East-West and North-South slopes of the site as a single value each and applying these parameters in the self-shading calculations. The slope values could either be defined for each project or for each array (allowing four different slopes per project). Allowing definition per array would be more in line with current practice, as other geometric metrics (gcr, tilt, azimuth) are also defined per array.

By my understanding of the code these added inputs would serve as an input to the geometric calculations used in the self-shading algorithm in ssc/shared/lib_pvshade.cpp. The geometric calculation routines would have to be updated to consider these inputs geometrically.

Bug with certain PV radiation input combinations

There is bug that affects all lifetime pvsamv1 simulations that use irradiance data other than (DNI and DHI) or (DNI and GHI) on the Solar resource page. This has been fixed and will be released in an upcoming patch.

array overrun in sam_mw_type234.cpp

Line 213 of sam_mw_type234.cpp defines an array of nine doubles:

double m_F_wc[9];

g++ noticed that the array is overrun on line 263:

m_F_wc[9] = std::numeric_limits<double>::quiet_NaN();

Filing an issue as it's not clear what the right fix is. Perhaps it is to just delete line 263?

Module coefficient generator 6parsolve does not work for First Solar Series 6 CdTe modules.

https://sam.nrel.gov/forum/forum-general/1929

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.

Geothermal capacity factor calculated from gross nameplate instead of net nameplate capacity

CSP with subhourly weather data

Discussed on 6/23/2017 SAM meeting with Steve, Mike, Ty, and Nick.

For CSP models, set simulation time step to weather file time step so that SAM reports results at simulation time step instead of hourly averages.

Note that current behavior is for physical trough model to report results at simulation time step, but other models report hourly averages of subhourly time steps that appear to be incorrectly averaged from Time Step 1 instead of Time Step zero.

(Also, in SAM UI we can generate messages on Location and Resource input page explaining that subhourly simulations may cause erroneous results, e.g., MSPT with one-minute data might turn off receiver as a result of a drop in DNI.)

For a workaround, see this discussion on the SAM support forum: https://sam.nrel.gov/node/75047

Variable Shading Bugs in Solar Pilot

Not quite sure what the issue here was, but there was some issues identified by @mjwagner2.

Lifetime mode "Electricity to/from grid" differs from single year analysis

The electricity to/from grid reported in the lifetime hourly data differs from the electricity to/from grid in the hourly data for the same period:

sCO2 Brayton Power cycle new configurations (reheating, PCRC, RCMCI).

Dear developers,
Based on the files sco2_pc_core.h, sco2_pc_core.cpp, I started programming the recompression power cycle with one ReHeating stage in the turbine.
My plan is after integrating the ReHeating in the recompression power cycle continuing programming the PCRC, RCMCI cycles with reheating and without reheating.
Please confirm me you agree with my developing plan, and if these new capabilities are beneficial for central tower, parabolic and fresnel thermosolar power plants modelled in SAM.
Best Regards,
Luis Coco Enríquez
Contact e-mail: [email protected]

query in shared/lib_util.cpp

In shared/lib_utill.cpp, we have this in util::format:

do
{
	va_list argptr_copy;
	va_copy( argptr_copy, arglist );
	ret = util::format_vn(buffer,size-1,fmt,argptr_copy);
	va_end( argptr_copy );

	if (ret == 0)
	{
		delete [] buffer;
		size *= 2;
		buffer = new char[size];
		if (!buffer)
			return "";
	}
	
}
while (ret < 0);

ret is of type size_t which is an unsigned type and so ret can never be negative. This do/while loop can only ever execute once. Is this what was intended?

(Mis-)handling of missing TMY3/EPW values

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.

DC-connected battery has battery discharging to grid

In some cases, the dc-connected battery algorithm is allowing battery power to discharge to the grid in a behind-the-meter application, which is generally not wanted. This leads to more battery discharge than is required.

Solver failure

Solver fails when 2nd guess value is the correct value but 1st guess value is invalid. This does not happen often but will return the wrong answer.

Remove interpmet

The interpmet flag in the weather file header seems to be a holdover from internal testing. Its use to external parties (or at this point even to the team) isn't immediately obvious, and it isn't implemented correctly to begin with (it averages using the already-updated data, rather than with the original data). Therefore, we have decided to remove it from the code.

Uninitialised variable in Heliostat_AzElAod.cpp

Found by clang:

../tcs/Heliostat_AzElAod.cpp:181:18: error: variable 'rows' is uninitialized when used here [-Werror,-Wuninitialized]
                for(int i=0; i<rows; i++){
                               ^~~~

Indeed, if you inspect the code, rows is uninitialised.

PVSAMV1 reports annual GHI in Wh/m2/year, but units indicate kWh/m2/year

Other annual outputs are in kWh, so kWh/m2/year may be best to be consistent.

bug in csp_solver_two_tank_tes.cpp

g++ produces the following warning:

../tcs/csp_solver_two_tank_tes.cpp:614:59: warning: left operand of comma operator has no effect [-Wunused-value]

The line involved is:

double cp_T_avg = mc_store_htfProps.Cp(0.5*(T_cold_ini, T_hot_K));

The comma oprerator appears between T_cold_ini and T_hot_K, so the expression always calculates one half of the hot temperature. The comma should be +, right?

matrix_t misuse in C_DSG_Boiler::Initialize_Boiler

Similar to #36, C_DSG_Boiler::Initialize_Boiler uses [row, col] array notation, not the matrix_t at() method:

../tcs/direct_steam_receivers.cpp:146:22: warning: left operand of comma operator has no effect [-Wunused-value]
../tcs/direct_steam_receivers.cpp:146:96: warning: left operand of comma operator has no effect [-Wunused-value]

I'll submit a PR and attach it to this issue.

Battery thermal adjustment of capacity results in undesired behavior

In some cases, adjusting the battery state of charge for thermal effects has the unintended consequence of making the battery try to charge more in the next time-step, in a continuous manner. For instance, if the battery SOC is 100%, and the thermal model temperature predicts a 3% loss in SOC at the temperature, the SOC gets updated to 97%. But, then in the next time step, the dispatch model detects that the battery should charge to 100%. Some rework required.

Bug with specifying subhourly generation profile within generic system model

If you specify a sub-hourly generation profile and sub-hourly load within the generic system, it appears that the "gen" array is still only 8760, and the utility rate module throws the error:

IPH Trough model does not work with user-defined HTF properties

Linear dsg process heat model with evacuated tube heat loss bug

Not sure exactly what the bug was, but there was an issue @tyneises identified within the linear dsg process heat model with evacuated tube heat loss.

bug in Heliostat::getPanelById

As far as I can see, this function has never worked properly. g++ warns about this problem with the following messages:

../solarpilot/Heliostat.cpp:748:18: warning: left operand of comma operator has no effect [-Wunused-value]
../solarpilot/Heliostat.cpp:749:23: warning: left operand of comma operator has no effect [-Wunused-value]
../solarpilot/Heliostat.cpp:756:20: warning: left operand of comma operator has no effect [-Wunused-value]
../solarpilot/Heliostat.cpp:764:23: warning: left operand of comma operator has no effect [-Wunused-value]

I think this is a genuine bug, so submitting this issue (and I'll also submit a PR that fixes it).

nlopt config.h is stale

Numerous nlopt source files #include config.h. The file is generated by cmake, but is not generated dynamically by the build system. This file looks like it was generated once, committed to git, and is now static.

It's a problem because on my system, some of the#defines are wrong. config.h should be generated on the fly just as it is in many autoconfiscated projects.

Bug in description of standoff mode

I have found that in the SSC SDKtool, the standoff mode is commented differently between module models in the META column:

• cec_standoff: 0=bipv,1=>3.5in,2=2.5-3.5in,3=1.5-2.5in,4=0.5-1.5in,5=<0.5in,6=ground/rack
• 6par_standoff: 0=bipv,1=>3.5in,2=2.5-3.5in,3=1.5-2.5in,4=0.5-1.5in,5=<0.5in,6=ground/rack
• sd11par_standoff: 0=bipv,1=>3.5in,2=2.5-3.5in,3=1.5-2.5in,4=0.5-1.5in,6=<0.5in,5=ground/rack

For the 11-parameter model, index 5 and 6 are switched in the comment, but treated the same in the code as they all access function setup_noct_model. This switch thus seems to be a bug?

Unable to build SDKtool

This has never worked for me in the Linux build. Am I doing something wrong?

make[1]: Entering directory '/home/bje/source/ssc.bje/build_linux'
g++ -g -o SDKtool dataview.o dllinvoke.o editvariable.o scripting.o sscdev.o ../../wex/wexuxwx3.a -std=c++0x ../../wex/wexuxwx3.a ../../lk/lkuxwx3.a `wx-config-3 --libs stc` `wx-config-3 --libs aui` `wx-config-3 --libs` -lm  -lfontconfig -ldl -lcurl 
/usr/bin/ld: ../../wex/wexuxwx3.a(pltext.o): undefined reference to symbol 'FT_Library_SetLcdFilter'
//usr/lib/x86_64-linux-gnu/libfreetype.so.6: error adding symbols: DSO missing from command line

pvsamv1 kWhperkW metric incorrect for subhourly data

In pvsamv1:

		double kWhperkW = 0.0;
		double nameplate = as_double("system_capacity");
		if (nameplate > 0) kWhperkW = annual_energy / nameplate;
		// adjustment for timestep values
		kWhperkW *= ts_hour;
		assign("capacity_factor", var_data((ssc_number_t)(kWhperkW / 87.6)));
		assign("kwh_per_kw", var_data((ssc_number_t)kWhperkW));

The adjustment for time step does not seem to be necessary -- kWhperkW = annual_energy / nameplate should be valid regardless of the time step.

See support forum discussion: https://sam.nrel.gov/node/74919

PV+battery for PPA, some battery outputs don't add up

It also appears that for PV-battery with PPA financial models, "Electricity to grid from battery" is not consistent with "Electricity to/from battery."

Implementation of the Mermoud/Lejeune module model

Due to its wide application in the solar industry and its use as the de-facto standard in bankable yield assessment of solar power plants, the Mermoud/Lejeune module model could be a valuable addition for SAM/SSC.

The governing equations are published in "Performance assessment of a simulation model for PV modules of any available technology", André Mermoud and Thibault Lejeune, 2010. A summary can be found on the PVPMC website as well.

One advantage is that module manufacturers typically make their module data available in the PAN format, which contains parameters fit for use with this module models' governing equations. Examples for PAN files can be found for First Solar modules for the older PAN format or from Astroenergy for the more recent format. Thus, implementing this model would allow to import and use manufacturer data easily in SAM.

The model has already been implemented in the CanadianSolar/CASSYS open source simulation tool in C#. This code could serve as a reference in the development. Its licensing terms can be found here. On the other hand, I assume that the existing SAM code base could be easily adapted to use these governing equations in addition to the ones currently implemented.

Possible logic bug in SolarField::radialStaggerPositions?

g++ warns that:

../solarpilot/SolarField.cpp:2473:40: warning: logical not is only applied to the left hand side of comparison [-Wlogical-not-parentheses]

That line reads:

 && !Htv->is_round.mapval() == var_heliostat::IS_ROUND::ROUND) {

It's not clear to me if what is meant was to invert the mapval() result and then test equality with ROUND or if what was meant was !(expr == ROUND) or, simply, expr != ROUND.

If someone can please clarify, I'll fix it either way.

Subhourly irradiance exceeding extraterrestrial irradiance

As pointed out by Timo, sometimes subhourly irradiance can in fact exceed extraterrestrial irradiance due to cloud enhancement (sources provided in his question). SAM currently flags these and sets the irradiance to zero, but perhaps it should be a warning and proceed as-is, particularly for subhourly simulations.

It may be difficult to tell subhourly from hourly simulations in the place where this error is thrown, so it may not be possible to treat the instances differently.

We also need to check if any subsequent algorithms will break with irradiance > extraterrestrial irradiance.

See support forum https://sam.nrel.gov/node/75023

Demand Charge accounting in Monthly $ rollover

Demand charges not properly accounted for in months with $ rollovers in second metering option per https://sam.nrel.gov/node/75710

Missing Time Zone errors

In PVWatts and detailed PV models, if the time zone is missing, annual energy will return 0 or negative. In at least one CSP model, if time zone is missing, an unhandled exception is thrown.

control reaches end of two non-void functions

There are two functions that return double, but have execution paths that do not return a value. The warnings are:

../tcs/sco2_power_cycle.cpp:2061:1: warning: control reaches end of non-void function [-Wreturn-type]
../tcs/sco2_power_cycle.cpp:2067:1: warning: control reaches end of non-void function [-Wreturn-type]

Should these functions return a quiet NaN, perhaps, if frame == NULL?

Better documentation of SSC layout

Add some documentation to help guide users looking for particular pieces of source code. Also give an overview of the general layout of the SAM code.

Bug with Demand Charge Calculation using sub-hourly data

In the event that one-minute weather and load data are used, and multiple TOU demand periods are defined, the TOU demand charges which are calculated are incorrrect. If there is only one TOU demand period, the charges are calculated correctly.