{{>toc}}

See sims/SIM_simbus_example in your gunns/ repo. This is an example Trick sim that uses the Thread-Safe Sim Bus. This page will go through all the relevant files that set it up and make it work.

This sim is identical to sims/SIM_test except that it assigns the different networks to separate threads and adds a thread-safe simbus interface between a couple of objects in different networks. See notes on multi-threading between aspects here.

To demonstrate the use of the sim bus, we are transferring the temperature of a tank’s shell from a thermal aspect (the capacitor link in the sims/networks/thermal/gunnshowThermalTest/GunnShowThermalTest network) to its fluid aspect (the tank link in the sims/networks/fluid/test/TestFluidNetwork network). The aspect diagram below helps visualize what we’re doing:

Let’s examine the relevant files that the sim bus uses:

By default, the sim tries to build the sim bus from source code in the icd-tools repository. The path to this is set in the S_overides.mk script below.

See sims/icd/TEST_ICD.txt. This is an example of an “ICD .txt” file — files such as this define all the variable-to-variable transfers (reads & writes) that your simbus will do. Here are the contents of our example file. Notice how it writes the thermal.capacitor.mTemperature to its internal tankShellT variable, which is then read by fluid.tank.mShellTemperature.

PUI     SYS     BUS     SUBSYS  VAR_NAME        ACTION  RATE            SIM_OBJECT                      SIM_VAR_NAME                    TYPE    UNITS   COMMENTS 

# Exchange tank shell temperature and heat flux between thermal & fluid networks:
xxxx    gunns   simbus  test    tankShellT      WRITE   ECLSS_LO        TestSimObject testSimObject     thermal.capacitor.mTemperature  double  (K)     Tank shell temperature
xxxx    gunns   simbus  test    tankShellT      READ    ECLSS_LO        TestSimObject testSimObject     fluid.tank.mShellTemperature    double  (K)     Tank shell temperature

See /sims/icd/icd_generate. This python script describes which ICD .txt files to include in the build for each sim. See these two sections: this example builds our SIM_simbus_example sim using just the TEST_ICD.txt file. This icd_generate script is invoked by the S_simbus.mk makefile below.

#########################################################################
##     Common ICD lists can be placed here                             ##
##     Note: please be careful when adjusting these lists, they may    ##
##           be referenced in multiple places below                    ##
#########################################################################
example_icds = [
   rdir+'/TEST_ICD.txt',
]

#########################################################################
##     Specific calls to tools go here                                 ##
##     Note: Developers are free to adjust the calls below to meet     ##
##           their needs                                               ##
#########################################################################
#-----------------------------------------------------------------------
# SIM_simbus_example
icds = [

] + example_icds
icd_generate(icds, 'SIM_simbus_example')

This file assigns sim objects or their components (i.e. GUNNS networks) to execution threads. This ensures that all the simbus writes/reads to/from a particular network happen before/after that network executes, in the proper order in each thread.

Although this file causes extra Trick child threads to be created, it does not assign the threads to different CPU’s. By default, Trick runs all threads on the same CPU and it takes additional set-up to change that, not covered here.

See /sims/SIM_simbus_example/S_overrides.mk. This is a general make overrides file that Trick always looks for when building a sim. It can contain nothing, or all kinds of sim build customizations. We include stuff to build the Sim Bus in here.

The first statement defines an environment variable ICD_HOME that holds the location of the folder containing your ICD .txt and icd_generate files, described above. In our example, this is at gunns/sims/icd:

The second statement defines where your Sim Bus source code is (described above). In our example, since we’re using the icd-tools git repository, we point to it:

The rest of this makefile invokes the S_simbus.mk makefile (described below) and sets up some Trick include paths that the Sim Bus build needs.

See /sims/SIM_simbus_example/S_simbus.mk. This makefile actually controls how the Sim Bus is made, the various make targets, etc., using the defined ICD_HOME and SIMBUS_HOME environment variables from S_overrides.mk.

See /sims/S_modules/Test.sm. We call these “Sim Object” or “.sm” files, and they define a sim object class. This is where we ensure that we execute the networks in the same threads that we defined for the sim bus in the simobj_to_thread_mapping.txt file above.

The sim object class constructor has arguments to pass in the thread ID’s for each separate thread being used by the sim object and its components (networks), and passes these to Trick when setting up the Trick run jobs.

See /sims/SIM_simbus_example/S_define_. The Sdefine does two important things related to our use of the sim bus.

First, we include the built Sim Bus and thread definition code into our sim:

// Needed for sim bus multithreading
#include "../S_modules/ChildThreadHandler.sm"
#include "thread_safe_bus/thread_map.sm"

// Simbus sim object
#include "thread_safe_bus/simbus_simobj.sm"

Building the Sim Bus puts all of its generated code into the sim’s thread_safe_bus/ folder (the folder is generated too if it doesn’t already exist).

Secondly, we instantiate the model sim object with arguments for its needed thread ID’s:

// Test sim object.
#include "../S_modules/Test.sm"
TestSimObject testSimObject(CTH.getThreadId(gtestSimObject_fluid_Thread),
                            CTH.getThreadId(gtestSimObject_basic_Thread),
                            CTH.getThreadId(gtestSimObject_thermal_Thread));

These are files that are generated into the SIM_ folder during the Sim Bus build process:

This is a report output by the build process. It will report success or error messages that may help in troubleshooting.

Same thing as as alloc_simbus.out, above. For a successful build, these will look pretty close to identical. For build errors, these files may give status on different areas of the build.

The Sim Bus build process creates a thread_safe_bus folder in the SIM_ folder. These are some of the files created in here:

This file is important because it defines the global string names for the thread ID’s that are use as arguments in the sim object constructors (see S_define above). It is included in the sim’s S_define file. Note that it has a “.sm” file extension but it’s not really a true sim object.

The format of the string names is always: g_Thread. The “g” stands for “global”.

%{
// Bind global simobject thread variables to logical thread names.
std::string gtestSimObject_fluid_Thread = "FLUID_THREAD";
std::string gtestSimObject_basic_Thread = "ELECT_THREAD";
std::string gtestSimObject_thermal_Thread = "THERMAL_THREAD";
%}

This is the real meat of the Sim Bus — the sim objects and related classes that actually move the data around in run-time. It is included in the sim’s S_define file.