Trace Compounds (TC) provides an efficient way to model the concentration & transport of trace amounts of many different chemical compounds in and around a fluid network, without having to model all of their fluid properties like we do with the bulk fluids. This saves a lot of computer memory and processing time. Reasons to model TC’s are:

• Many TC’s in a spacecraft environment are toxic to crew members, so their concentrations must be actively controlled by scrubbing equipment. They are introduced by off-gassing from equipment and human metabolics, or various equipment failures.
• TC’s represent impurities in a bulk fluid that can adversely affect various spacecraft systems. For instance, too much water present in an ammonia coolant loop can freeze and build up a line blockage. Too much helium in a fuel cell’s oxygen supply can degrade its performance, and so on.

The detrimental effects of TC’s usually occur before they reach high enough concentration in the bulk fluid to significantly affect the bulk fluid properties. Therefore the assumption is that TC’s are always in such low concentration in the bulk fluid that their contribution to the bulk fluid properties can be ignored. Then the only properties of a TC that we need to model are:

• Mass in the bulk fluid. Mass of the TC is added & removed by various types of links, and then we can show conservation of mass of the compound as it flows & mixes around in a network.
• Mole fraction (concentration) relative to the bulk fluid. TC’s are modeled so that the equipment & processes that produce & control their concentrations can be modeled.
• Molecular weight of its chemical compound, in order to relate the TC’s mass to its mole fraction.

Any of the chemical compounds in the ChemicalCompound class can be used as a TC in a fluid network. The list can be seen in the GUNNS repo at: ms-utils/properties/ChemicalCompound.hh. The present list as of v19.3 is shown below, and we may add more in the future:

        ////////////////////////////////////////////////////////////////////////////////////////////
        /// @brief    Enumeration of the types of Chemical Compounds.
        ///
        /// @details  This enumeration is used to index the array of Defined Chemical Compounds.
        ////////////////////////////////////////////////////////////////////////////////////////////
        enum Type {
            CH2O        = 0,  ///<  Formaldehyde
            CH2CL2      = 1,  ///<  Methylene chloride (Dichloromethane)
            CH4         = 2,  ///<  Methane
            CH4O        = 3,  ///<  Methanol (Methyl alcohol)
            C2H4O       = 4,  ///<  Acetaldehyde
            C2H6O       = 5,  ///<  Ethanol
            C3H6O       = 6,  ///<  Acetone
            C3H10OSI    = 7,  ///<  Trimethylsilanol
            C4H4O       = 8,  ///<  Furan
            C4H10O      = 9,  ///<  1-Butanol
            C6H6        = 10, ///<  Benzene
            C6H18O3SI3  = 11, ///<  Hexamethylcyclotrisiloxane
            C7H8        = 12, ///<  Toluene
            C8H10       = 13, ///<  o-Xylene
            CO          = 14, ///<  Carbon monoxide
            CO2         = 15, ///<  Carbon dioxide
            H2          = 16, ///<  Hydrogen
            H2O         = 17, ///<  Water
            H3PO4       = 18, ///<  Phosphoric Acid
            H           = 19, ///<  Monatomic Hydrogen
            LIOH        = 20, ///<  Lithium hydroxide
            LIOHH2O     = 21, ///<  Lithium hydroxide monohydrate
            LI2CO3      = 22, ///<  Lithium carbonate
            NH3         = 23, ///<  Ammonia
            NH42HPO4    = 24, ///<  Di-Ammonium hydrogen phosphate
            O2          = 25, ///<  Oxygen
            OH          = 26, ///<  Hydroxyl
            O           = 27, ///<  Monatomic Oxygen
            He          = 28, ///<  Helium
            NO_COMPOUND = 29, ///<  Invalid or number of compounds - Keep this last!
        };

Note that some of these compounds can also be actual fluid types in a network (O2 compound can also be the fluid constituent GUNNS_O2). In general, a compound can be both a fluid constituent and a TC in a network, but some links may not allow it.

TC’s aren’t a fluid themselves and have no fluid properties other than described above. They have no phase, and can be inside any gas or liquid fluid object.

You can also add custom Trace Compounds to your network, described in detail below. This is handy when a compound you need isn’t in the above list.

The Trace Compounds capability in v19.3 includes:

• Specify which TC’s are in a network and their initial concentrations in nodes via GunnsDraw (same as fluid constituents)
• Initial conditions override via input file (same as initial fluid states)
• Transport & mixing of TC’s around a network in bulk fluid flows, updating mass & concentrations in nodes
• TC’s introduced by human metabolics with the GunnsFluidMetabolic2 link
• TC’s introduced or removed as a boundary flow source with the GunnsFluidSourceBoundary link. Use this to model off-gassing of TC’s from vehicle equipment.
• TC’s absorbed by the GunnsFluidAdsorber link
• Exchange of TC’s between fluid networks in the external supply/demand, shadow & similar links
• Create or add to network Trace Compounds configuration via the input file.

Stuff that doesn’t work yet:

• Use of TC’s in chemical reactions in the GunnsFluidReactor & similar links
• Free molecular diffusion of TC’s in the GunnsFluidHatch link
• Reporting of TC concentration by the GunnsFluidSensor link
• TC mass balance and other stats in the GunnsFluidIslandAnalyzer, GunnsFluidFlowIntegrator, GunnsFluidNetworkConservationError & similar spotters
• TC mass & concentration editing capability in GunnsFluidTank & similar
• Transport of TC’s in miscellaneous special flows, such as the condensed water in the GunnsFluidCondensingHxSeparator link, etc

Just like the normal fluid constituents, the set of TC types in the network is defined in the GunnsDraw network drawing. The presence of TC’s is entirely optional. By default, a fluid network will not have any TC’s in it. TC’s are added to a network via the Trace Compounds Config shape:

Setting this up is very similar to adding the Fluid Config object. After you place the Trace Compounds Config object into the network:

• You can change the object name, but we recommend leaving it as the default “netTcConfig”.
• Edit the data rows to list the compounds types you want to be in this network.
  • The available compounds you can use are defined in gunns/ms-utils/properties/ChemicalCompound.hh, in the Type enumeration of the ChemicalCompound class. See Trace_Compounds#tc-types above.
  • The picture above shows an example of adding 3 trace compounds to the configuration.
• Only add one Trace Compounds Config shape to a drawing. Do not add one if you don’t want to model any TC’s at all.

Once you’ve specified the network’s internal Trace Compounds Config, you’ll need to create one or more Trace Compounds States to initialize things like the initial concentrations of TC’s in nodes, how links interact with them, and so on. These Trace Compounds States are given to other objects in their Shape Data, described below. In general, Trace Compounds States are optional for any object that can receive them as shape data.

After you place a Trace Compounds State into the network:

• Name this state object. Each state object must have a unique name among all the objects in the network.
• The left-most column are labels, and the right column is values.
• Edit the COMPOUND_# labels to match the same list of compounds from the Trace Compounds Config object, and in the same order.

Now once the Trace Compounds State object has been created, you need to set its Shape Data:

The shape data can represent different things depending on which object it is given to. For Fluid States, this shape data represents the mole fraction of each TC relative to the bulk fluid. For the GunnsFluidAdsorber link, it defines the absorption efficiency for each TC compound. There are other uses — see the link help pages for more info. This is why we have the Units/Comments field in the shape data to help remind you what a particular state is for. In the example shown here, we intend this state to define the initial TC mole fractions for the network’s fluidTank Fluid State, so it represents mole fractions. You can change the comment in the Shape Data window if desired. Enter a value for each TC type in the Shape Data.

Fluid States contain an optional Trace Compounds State in their TC State shape data. You can add initial trace compounds concentrations by modifying this field with the address of one of the Trace Compounds State object in the network. In the example shown below, we’ve added the above tcTank trace compounds state to the network’s fluidTank fluid state:

The Trace Compounds State is optional; you can leave the field 0, and this will cause that Fluid State to initialize with zero mass and concentration of all TC’s.

Some link & spotter classes have shape data for specifying a Trace Compounds State to configure how that link or spotter interacts with the TC’s in the network. Their shape data fields work just like the Fluid State’s shape data shown above. These fields are usually optional; when left 0, that link or spotter won’t interact with the TC’s. Or you specify the address of the Trace Compounds State you want to use, just like with the Fluid State above. Refer to the link’s help page for more info on how to configure its Trace Compounds States.

Here is an example of the shape data for a GunnsFluidAdsorber that has been configured to absorb TC’s:

The Trick Input File lets you override the initial values of the Trace Compounds States in a network when needed, just like with the initial Fluid States.

In the example above, say we want to override the initial mole fractions in the tcTank Trace Compounds State. The values of the Trace Compounds State are in the network’s input data object (netInput), in a union called Values, so in this case, tcTankValues. Just like with initial fluid states, the union is of an array and individual scalars, and it is most convenient to set the scalar value for each TC type as needed. In Trick View, they look like this:

And those are the same terms you would override in the input file, like so:

# Override initial mole fractions of TC's in the tank:
testSimObject.fluid.netInput.tcTankValues.scalar.CH2O     = 1.23e-4
testSimObject.fluid.netInput.tcTankValues.scalar.CH4O     = 5.67e-9
testSimObject.fluid.netInput.tcTankValues.scalar.C3H10OSI = 4.2e-5

And voila!

You can use the input file to add compounds to a network’s Trace Compounds Config. You can either add an existing compound type (from the TC Types list above), or you can create a custom compound type.

• To add an existing TC type, call the network Trace Compounds Config’s addCompound() method like so:

# Add ChemicalCompounds::LIOH to the network:
testSimObject.fluid.netConfig.netTraceCompounds.addCompound(trick.ChemicalCompounds.LIOH)

• To add a custom TC type, call the network Trace Compounds Config’s addCompound() method like so:

# Add custom trace compound type "SMOKE" with molecular weight 10,000 (g/mol) to the network
# and don't associate it with any FluidProperties fluid types:
testSimObject.fluid.netConfig.netTraceCompounds.addCompound(10000.0, "SMOKE", trick.FluidProperties.NO_FLUID)

• To add a custom TC type that you also want to associate with an existing FluidProperties type, call the network Trace Compounds Config’s addCompound() method like so:

# Add custom trace compound type "HFE7100" with molecular weight 250 (g/mol) to the network and
# associate it with the FluidProperties type GUNNS_HFE7100:
testSimObject.fluid.netConfig.netTraceCompounds.addCompound(250.0, "HFE7100", trick.FluidProperties.GUNNS_HFE7100)

There are a couple of things to note when adding to the Trace Compounds Config:

• you must reset all of its Trace Compounds State objects to reflect the new array size for the number of compounds in the config.
• if you transfer TC’s between networks via external supply & demand links, you must change the trace compound array size in the sim bus ICD.

From the input file, you can add TC’s to a network whose GunnsDraw drawing had never defined any TC Config or States at all.

# TODO use this as an example of how to add TC's to the sub-networks, defined entirely in the
# input file when their GunnsDraw drawings have no TC config or state at all:
#
# First dynamically create a new TC Config object and load it with the desired compounds:
tcConfig = trick.GunnsFluidTraceCompoundsConfigData(None, 0, "test")
tcConfig.addCompound(trick.ChemicalCompound.CH2O)
tcConfig.addCompound(1000.0, "SMOKE", trick.FluidProperties.NO_FLUID)

# Next create one or more TC State objects:
tcState = trick.alloc_type(2, "double")
tcState = [1.0e-8, 1.0e-3]
tcInput = trick.GunnsFluidTraceCompoundsInputData(tcState)

# Add the new TC Config to the network's internal fluid config:
testSimObject.fluid.netInternalFluidConfig.mTraceCompounds = tcConfig

# Add the new TC States to the network fluid's initial fluid states, and link config & input
# data as needed:
testSimObject.fluid.netInput.fluidDefault.mTraceCompounds = tcInput

You can also use this technique to completely replace the TC Config that was specified by the drawing.

In the Trick sim, you may want to observe the masses & concentrations of the TC’s as they flow & mix around in the network and are introduced or removed by links. A good way to look at them is in the node’s fluid contents. Here we are looking at the node that was given the tcTank state in the example above:

You can see the initial mole fractions we changed in the input file, and the resulting masses of the TC’s in the node. Mole fraction is the same thing as “parts per one”, so to convert mole fraction to a more standard concentration value like parts per million (ppm), simply multiply the mole fraction value by a million.

It is important to remember that the TC’s in a fluid do not contribute to the fluid’s bulk properties, like pressure, density & temperature. You could get your TC mole fractions up to significant levels, say 0.1, which would normally be 10% of the total fluid pressure. Adding this amount to the fluid would realistically cause a 10% increase in pressure, but our TC’s won’t do that and you won’t see any change in pressure at all. It is up to you to decide at what point you’d rather have the effects show up in the bulk fluid properties. If you want fluid properties to be affected, then you have to use the real fluid constituents and not the TC.

Caution: the TC capability is designed to be optional, with no refactoring impact to legacy networks that don’t want to use them. In order to achieve that, we designed all the TC code to use pointers: all TC states and configs in network objects like nodes, fluids, links & spotters are pointers. In Trick View (TV), one must be careful when looking at pointers. Watch out for the following:

• Pointers always appear like arrays in TV, and if you give TV a bad array index to a pointer, it will usually kill your sim with a segmentation fault. This is a known Trick limitation. In the example above, mTraceCompounds[ 0 ] is such a pointer. Always only use array index 0 when looking inside it. Here’s what the array index selector would look like when grabbing the 3 mass terms from the above example, showing where you should leave the pointer index 0, highlighted in yellow:

• In networks that don’t use TC’s, the TC class attributes (pointers) are still visible in TV, and they are NULL pointers (value 0). TV will still let you attempt to look inside them, but you’ll get <Invalid Reference< warnings bleeding all over your TV screen.