SSC Compute Modules

Compute modules in SSC are a structure that contain complete functions calculating large sections of a model in SAM. They serve as the main access points from external applications, including the SAM user interface and the SAM SDK. For example, each technology model and financial model has its own compute module. Cost models may also have their own compute module. If you’re unsure whether your function should be a new compute module or not, please contact the SAM team.

Adding a new compute module to SSC

1. Create a new file named cmod_compute_module_name.cpp in the ssc folder of the ssc project (you can do this by copying, pasting, and renaming another compute module that you wish to emulate).

2. Add the compute module to the list of source files in ssc/ssc/CMakeLists.txt. Then reload your project:

   1. Visual Studio: Re-run the CMake command from the build directory, per build instructions.

      cmake -G "Visual Studio 16 2019" -DCMAKE_CONFIGURATION_TYPES="Debug;Release" -DCMAKE_SYSTEM_VERSION=10.0 -DSAMAPI_EXPORT=1 .. 
      

   2. CMake on Unix: Re-run the CMake command from the build directory, per build instructions for Mac and Linux:

      cmake .. -DCMAKE_BUILD_TYPE=<Debug;Release>
      

   3. Clion and other CMake-integrated IDEs: Reloading the CMakeLists.txt will update the project

3. Compute modules must be listed twice in ssc/sscapi.cpp, once in extern module_entry_info and once in static module_entry_info *module_table[]. Follow the formatting of the other compute modules in each list.

4. Add a Module description to builder_PySAM.cpp::module_doc

   The compute module name needs to be reformatted by removing "cmod", removing underscores and capitalizing each letter that followed an underscore: "cmod_xx_yy" becomes "XxYy". The description should provide a high level way of distinguishing this compute module.

5. Identify the config name with the compute module in data_structures.h::config_to_cmod_name

   The first entry is the config name with the spaces removed, and the second entry is the reformatted compute module name from step one (e.g. XxYy).

6. Follow the instructions at https://github.com/NREL/SAM/wiki/Compute-modules-in-SAM as needed.

Compute module structure

The easiest way to create a new compute module is to copy and edit an existing compute module. lib_windbos.cpp provides a fairly simple example with most of the required features. In general, all compute modules have the following sections:

• License at the top of the file
• #include “core.h”
• Variable table- contains inputs and outputs to the compute module
  • Vartype- options are SSC_INPUT, SSC_OUTPUT, or SSC_INOUT for things that are both an input and output to the function
  • Datatype- options are SSC_NUMBER, SSC_ARRAY, SSC_TABLE, SSC_MATRIX, SSC_STRING. For the most part, you should only use number, array, or string.
  • Name- the variable name that will show up externally to the compute module. This should be fairly descriptive.
  • Label- the description of the variable that will show up externally. This should be more descriptive.
  • Units- the units of the variable, ex “kW” or “%/yr”
  • Group- used in the user interface to sort variables. For the most part, this should be the name of the compute module.
  • Required_if- automatically parsed to determine if all required variables are supplied to a compute module.
    • “*” indicates a required variable
    • “?” or “” indicates an optional variable
    • “?=20” indicates an optional variable, that if a value is not supplied, will default to a value of 20
    • “variable_xyz=1” indicates that the current variable is required only if variable_xyz is equal to 1
  • Constraints- items that are automatically parsed to provide some level of input checking. You should utilize the constraints as much as possible. Possible options for variables of type SSC_NUMBER include INTEGER, BOOLEAN, POSITIVE, NEGATIVE, MIN=5, MAX=25, and for variables of type SSC_ARRAY can specify length with LENGTH=12, where all numbers are specified by the writer.
• Declaration of instance of compute_module class
• add_var_info function to add the variable table to the compute module
• exec() function as the main function that gets called when someone calls the compute module
  • Read in all inputs- make sure to perform any input checking that was not possible using the variable table constraints.
    • Inputs are usually read in as double x = (double) as_number(“input_variable_name”);. Other options include as_string, or as_array. The as_array function returns a pointer to an array and also requires an input to save the length of the array, used to check its length as needed.
  • Model calculations- can call out to external functions located in libraries or defined above the exec function in the compute module
  • Assignation of all outputs
    • Output assignations generally look like assign( “output_variable_name”, var_data(previously_calculated_variable) );
• Definition of compute module entry, including description of what the compute module accomplishes