{{>toc}}

This is a quick overview of the files you typically need to create to run a GUNNS network in a Trick sim:

A C++ class, typically auto-generated by a design GUI such as GunnsDraw. It contains a GUNNS solver and all the links, nodes, spotters, and other miscellaneous objects used to make a single GUNNS network of that particular aspect. It has various methods to be called from Trick jobs:

• Initialize (or similar) method, called from a Trick initialization job.
• Update (or similar) method, called from a Trick scheduled job.
• Restart (or similar) method, called from a Trick restart job (optional — not needed if you don’t need checkpoint/restart)

This class can be extended by hand to add custom features. We did this for several ISS networks in TS21.

With Trick 10 onwards, Trick jobs are defined in a Sim Object class, usually defined in a .sm file. We typically define all our network’s Trick jobs in such a .sm file. You can arrange multiple networks in a single .sm or each have their own – the arrangement is up to you. In TS21 we typically had one .sm for each aspect (fluid, electrical, thermal) for each vehicle system (ECLSS, TCS, EVAS, etc.), which would contain all the networks of that aspect in that system. But you don’t have to follow that pattern. Here is an example of what a .sm containing one GUNNS network looks like:

##include "sims/networks/fluid/test/TestFluidNetwork.hh"

class TestSimObject: public Trick::SimObject
{
    public:
        TestFluidNetwork           fluid;                                    /**< (--) GunnsDraw-generated fluid network */

        TestSimObject()
            :
            fluid("testSimObject.fluid")                                     // Network instance name is a constructor arg
                                                                             // so it can identify itself in H&S messages
        {
            // These are the method args required by GunnsDraw-generated networks.  We recommend a
            // similar design if you don't use GunnsDraw, but that is up to you.  The GUNNS solver
            // requires a time-step in its step method ("scheduled" job).
            ("initialization")      fluid.initialize("testSimObject.fluid"); // Same instance name as constructor
            ("restart")             fluid.restart();                         // Only needed for checkpoint/restart
            (ECLSS_LO, "scheduled") fluid.update(ECLSS_LO);                  // A time step arg is required
        }
        virtual ~TestSimObject() { /* nothing to do */ }

    private:
        // Copy constructor unavailable since declared private and not implemented.
        TestSimObject(const TestSimObject&);
        // Assignment operator unavailable since declared private and not implemented.
        TestSimObject operator = (const TestSimObject&);
};

TestSimObject testSimObject;                                                 // Instantiate the sim object here or in S_define

In a typical sim environment these .sm files will be placed in the sim/S_modules/ folder, and within subfolders to organize them as appropriate.

The Trick S_define includes all of the pieces that you need to run your GUNNS network:

• #defines for time steps, etc. These can be in their own #include.
• Health & Status sim objects
• Default Trick sim object
• GUNNS network sim objects
• Sim Bus sim objects

Here is an example of the S_define that includes the above .sm:

// Rates and phase initialization priorities
#include "../S_modules/CommonRates.sm"
// Needed for sim bus multithreading

#include “../S_modules/ChildThreadHandler.sm”
// Sim bus setup

#include “thread_safe_bus/thread_map.sm”

#include “thread_safe_bus/simbus_simobj.sm”
// Default Trick stuff

#include “sim_objects/default_trick_sys.sm”
// Health and status sim object

#include “../S_modules/hs.sm”
// ICD stubs

#include “icd_stubs.sm”
// Model sim object (GUNNS networks, etc)

#include “../S_modules/Test.sm”

GUNNS outputs all important messages to the Health & Status system, so it is a very good idea to have this in your sim for debugging. We typically create a logs/ folder in the SIM folder (you must create the folder, H&S won’t create it for you), and configure H&S to place its log outputs there. The actual location is up to you. This location is configured in sims/Modified_data/hsconfig.txt.

More information on the H&S system here .

In the Trick environment, we currently use the Thread-Safe Sim Bus to move data between GUNNS networks and other aspect models. This is essential for multi-network and multi-threaded sims. The generic sim bus code resides in the icd-tools repo.

Here is a detailed Sim Bus User's Guide for GUNNS.

More information on the thread-safe sim bus here .

A quick summary of the files you need to implement are:

• One or more model ICD files – these define the reads/writes between model variables. Here is an example of what such a file looks like. This is example shows the transfer of one supply pressure value between two fluid networks:

PUI     SYS     BUS     SUBSYS  VAR_NAME                        ACTION  RATE            SIM_OBJECT              SIM_VAR_NAME                            TYPE    UNITS   COMMENTS
xxxx    iss     sim_bus eclss   toAcsO2Al_SupplyPressure        WRITE   ECLSS_10HZ      EclssSimObject eclss    cabin.fluid.toAcsO2Al.mSupplyPressure   double  (kPa)   Supply pressure to AcsO2 network airlock
xxxx    iss     sim_bus eclss   toAcsO2Al_SupplyPressure        READ    ECLSS_10HZ      EclssSimObject eclss    acs.o2Fluid.fromCabinEl.mSupplyPressure double  (kPa)   Supply pressure to AcsO2 network airlock

• One icd_generate script, which tells icd-tools how to build the sim bus for your sim. Here is an example of an icd_generate script. Each of the .txt files listed is one model ICD file, described above:

# Create a list of ICD files
icds = [
       'iss/icd/ENV.txt',
       'iss/icd/MECH.txt',
       'iss/icd/ISS_CS.txt',
       'iss/icd/PTCS_fsw_stub.txt',
       'iss/icd/PTCS_eps_stub.txt',
       ]
icd_generate(icds, 'SIM_eclss')  # Generate the thread-safe sim bus for the SIM_eclss sim
icd_stubs_generate(icds, 'SIM_eclss') # Generate the sim bus stubs for the SIM_eclss sim

The Trick “Input File” is a very powerful and flexible tool. Refer to the Trick documentation for more info. Here are the ways we typically use it for GUNNS:

1. Network is constructed when the sim is started, default values (from GunnsDraw drawing shape data) are set into all object’s config & input data.
2. Input files are called to override default config & input data values and set some things that can’t be set in GunnsDraw.
3. Network initialization job is run, initializes the network with config & input data including overrides from input files. All run-time GUNNS objects validate their config & input data and throw exceptions and H&S messages on errors. In some sim environments such as TS-21, any such error deliberately kills the sim.
4. Sim is moded to run, network scheduled job starts.

The Trick “Default Data” concept is normally implemented in GunnsDraw as the various object’s shape data — these data get exported and assigned in the network’s constructor when the sim comes up. So we don’t actually use a Trick “Default Data” job because the constructor does the same thing.

The Input File can be used to further override the default data as needed, prior to network initialization. This is optional — GunnsDraw-exported networks can usually be run without requiring any input file overrides. But sometimes you’ll want to set something in the input file. These are typical reasons:

• This can be used to initialize networks to different sets of initial conditions than what is in the default data.
• You can override a mistake in values in the GunnsDraw drawing, without having to update the drawing and re-build the sim. This is sometimes very convenient as a temporary fix or work-around.
• Some link’s shape data are designed to be set from the input file instead of in the drawing. More information here.
• There are some modes and configurations that can only be initialized via the input file, such as the solver’s Solver Mode and Island Mode, etc.

The Trick Input File is typically implemented as one or more python scripts, organized at the user’s discretion. The Trick’s Input Processor runs the scripts, and honors encapsulation, so the Input File can normally only access GUNNS attributes that have a public interface (public class attributes & access methods, etc). GUNNS attributes that are intended to be settable from the input file are public or have public accessors. This includes all config & input data, malfunctions and some other special attributes.

The python syntax for setting a GUNNS term is simply = . Here are some typical examples:

Overriding _link_’s config data value in network (the link’s “shape data” in the GunnsDraw drawing) is shown below. All link’s config data objects reside in the network’s config data object called netConfig:

simObject.network.netConfig.link.configTerm = value

Likewise, overriding _link_’s input data:

simObject.network.netInput.link.inputTerm = value

You can override single terms or multiple terms in any combination.

In addition to overriding a link’s config & input data default values, you can also set anything that python has public access to. This includes things like malfunctions that aren’t in the input data (some malfs are in the input data, others aren’t). All malfs are always initially off by default. Here we’re initializing an accumulator bottle’s bellows stuck malfunction. We set it directly in the link rather than in the input data, since this class doesn’t expose its malfunctions in the input data:

simObject.network.accumulator.mMalfBellowsStickFlag = True

Class functions can be called with arguments. For instance, setting a network solver’s Island Mode looks like this. The “trick.Gunns.SOLVE” is Trick/SWIG syntax for the enumeration Gunns::SOLVE defined in Gunns.hh. More on Island Mode here.

simObject.network.netSolver.setIslandMode(trick.Gunns.SOLVE)

Nodes are initialized with a PolyFluidInputData object (gunns/aspects/fluid/fluid/PolyFluid.hh) that is defined in the GunnsDraw drawing (the blue “Fluid State” boxes). One of these states can be used to initialize multiple nodes (typically what we do), or you can have an individual state dedicated to each node. The default state of this box can be overridden, which changes the fluid contents initial condition of all nodes that are initialized with that box. In this example, our Fluid State box was named fluidDefault:

simObject.network.netInput.fluidDefault.mTemperature  = 294.261
simObject.network.netInput.fluidDefault.mPressure     = 101.325
# mFlowRate and mMass are not used, can leave with defaults...
# Now override the massFractions (see below...)

There are several ways to override the mass fractions. Choose whichever works best for you:

1. Every Fluid State box creates a PolyFluidInputData object called and a union called Fractions. The union is of an array of mass fractions with a struct full of individual scalars for each constituent mass fraction. The array part of the union is given to the PolyFluidInputData during network initialization. You can set either the union’s scalars individually, like so:

# Override mass fractions union by scalars:
simObject.network.netInput.fluidDefaultFractions.scalar.GUNNS_O2  = 0.2
simObject.network.netInput.fluidDefaultFractions.scalar.GUNNS_O2  = 0.79
simObject.network.netInput.fluidDefaultFractions.scalar.GUNNS_H2O = 0.01
# ...etc.  Make sure all scalars sum to 1.0 !

2. …or you can set the union’s array, like so:

# Override mass fractions union by array:
simObject.network.netInput.fluidDefaultFractions.array[0] = 0.2
simObject.network.netInput.fluidDefaultFractions.array[1] = 0.79
simObject.network.netInput.fluidDefaultFractions.array[2] = 0.01
# ...etc.  Make sure all array positions sum to 1.0 !

3. Another way is to bypass the Fractions union completely and point the PolyFluidInputData mass fractions to your own array. In the Trick environment, you can do this in the Trick input file like so (more on initializing arrays here):

# Override mass fractions by pointing to a new array (make sure the array sums to 1.0 !):
massFractions = trick.alloc_type(3, "double")
massFractions = [0.2, 0.79, 0.01]
simObject.network.netInput.fluidDefault.mMassFraction = massFractions

Not all thermal aspect networks come from GunnsDraw; they can also be exported from the Thermal Desktop tool and/or built from a Thermal Registry tool. Rather than exporting C++ network classes like GunnsDraw does, these instead export the entire network configuration as input files and .xml files that are read in by the Trick input processor. This is the pattern primarily used by the TS-21 project, and we don’t fully support it in ER yet. We’ll have more information on that when we absorb it back into our GUNNS releases. More info here: Thermal_Desktop_and_Thermal_Registry_Networks_TS21.