{{>toc}}

A super-network is a special network object that aggregates multiple network instances into a combined system of equations and set of nodes.

Here’s the main reason why we developed this capability. Say you have separate drawings for (systems, subsystems or vehicles) that you’ve already drawn up and have been running in your sim as separate systems. Later, these systems need to be combined and flow between them. A classic example is the cabin atmosphere network of separate vehicles that need to be combined because they’ve docked and a hatch is opened between them. Some of these kinds of interfaces will be stable, others will be unstable.

Here’s a list of typical interfaces that will be unstable if combined this way:

• hatches between cabin volumes in separate networks
• flow loops split across separate networks, such as air ventilation or coolant loops connected between docked vehicles
• electrical circuits, like cross-ties between docked vehicles without power converters

Prior to super-networks, our only real option is to create a new network drawing that combines both of the tightly-coupled systems into a single network:

This incurs a development cost to draw up the new network. It also incurs an ongoing maintenance cost to ensure that the circuitry details of the system in its multiple drawings don’t diverge over time in future updates.

The super-network leaves the original separate system networks intact, so a combined drawing & network is not needed. Instead, the super-network provides a common solver, nodes set and simultaneous system of equations for the sub-networks’ links & spotters to act on. This allows the separate systems to be connected by their own links, since they now share a common nodes set:

• Can use this to break up an exceedingly large & unwieldy drawing into smaller, more manageable drawings with no change in run-time speed
• More flexibility: can be used in a modular & dynamic sim architecture, with individual networks for lower-level components, combined as needed at run-time
• No duplication of a system in multiple drawings, less risk of the system’s circuit details diverging between different drawings

• The main thing you lose when using super-networks instead of the big conglomerate drawing is that drawing’s big-picture view of the combined system. There’s no graphical representation of super-networks since they’re just set up in the input file.
• Super-networks use more computer memory than the old solution. The super-network creates a new solver and a new set of nodes to orchestrate all the sub-networks’ links & spotters. The sub-networks still instantiate their own nodes & solver. These aren’t used but still take up some memory.

• The super-network is basically a container of pointers to other network instances.
• Networks can be added to a super-network in the Trick input file. These are then called “sub-networks”
• The super-network provides a common set of nodes for all its sub-networks to share, and a common solver to orchestrate them.
• The sub-network’s own internal nodes & solver are not used.
• The sub-network’s Trick jobs do nothing; the super-network takes over their init, restart & scheduled job calls.
• Each sub-network stores an offset # that indicates where its old node numbers start in the super-network’s node list.
  • This term is netSuperNodesOffset, and is returned by the network’s getNodeOffset() method.
  • The first sub-network has an offset of zero.
  • If a link in a network normally connects to node 37 in the drawing, and the sub-network’s netSuperNodesOffset is 10, then the link will instead connect to node 47 in the super-network.
• The sub-networks in the same super-network can be inter-connected by their links, by manually overriding 1 or more link’s initial node map in the input file. See More On Link Node Mapping:The _mInitialNodeMap_ Input Data for how to do this.
• The super-network adds no extra links, spotters, or nodes. To connect the sub-networks together you need to have a link in one of them that you can move to connect nodes from the originally separate networks.
• All fluid sub-networks in a super-network must have identical fluid configurations (which fluid types and in what order).
  • This also applies to Trace Compounds.
• There are two classes of super-network: one for basic (electrical and thermal) and one for fluid aspects. These are GunnsBasicSuperNetwork and GunnsFluidSuperNetwork, respectively. These are what you instantiate in your sim object.
  • Don’t add sub-networks to a super-network of the wrong type.
  • Don’t add both electric and thermal networks to the same basic super-network.

• Add the normal network instances to the sim objects like normal. They should have the normal 3 Trick jobs. Until they get added to a super-network, they’ll run like normal. This is called a “stand-alone network”.
• Add a super-network to a sim object.
  • It has the same 3 kinds of Trick jobs as a normal network.
  • It can be defined before or after the normal networks: order doesn’t matter here.
• The sub-networks can be in the same or different sim object than the super-network. However for sim bus timing and threading, it’s best if they all run in the same thread. Learn about managing sim bus threads here.

Here’s an example of a sim object that contains 2 instances of a normal network class, and a super-network that will contain them:

##include "myNetworkDrawings/MyNetworkClass.hh"    // your network class
##include "core/network/GunnsFluidSuperNetwork.hh" // the super-network class

class MySimObject: public Trick::SimObject
{
    public:
        int                    threadIdFluid;      /**< (--) Thread ID for the fluid networks */
        myNetworkClass         networkA;           /**< (--) GUNNS fluid network */
        myNetworkClass         networkB;           /**< (--) GUNNS fluid network */
        GunnsFluidSuperNetwork superNetwork;       /**< (--) GUNNS fluid super-network */

        MySimObject(int thread_id_fluid = 0)
            :
            threadIdFluid(thread_id_fluid),
            networkA("mySimObject.networkA"),
            networkB("mySimObject.networkB"),
            superNetwork("mySimObject.superNetwork")
        {
            ("initialization") networkA.initialize();     // Note the name string is no longer
            ("initialization") networkB.initialize();     //   required for initialize!
            ("initialization") superNetwork.initialize();
            ("restart")        networkA.restart();
            ("restart")        networkB.restart();
            ("restart")        superNetwork.restart();
            CthreadIdFluid (DT, "scheduled") networkA.update(DT);
            CthreadIdFluid (DT, "scheduled") networkB.update(DT);
            CthreadIdFluid (DT, "scheduled") superNetwork.update(DT);
        }

• Even though a network’s Trick jobs don’t do anything if it’s a sub-network, it’s a good idea to still set up its jobs in case you want to run it as a stand-alone network in your sim later.

• Add each desired network to a super-network by passing their names to the super-network, like so:

mySimObject.superNetwork.addSubNetwork(mySimObject.networkA)
mySimObject.superNetwork.addSubNetwork(mySimObject.networkB)

• Don’t add a network instance to the same super-network more than once.
• Don’t add a network instance to more than one super-network.
• Multiple instances of a network class can be added to the same super-network.

• Only after all sub-networks have been added, then finalize the super-network by calling this method:

mySimObject.superNetwork.registerSuperNodes()

• The super-network’s solver should be configured with its config data.
  • Solver config data is described here.
  • Set the super-network’s solver config data via the input file. The config data object is always called netSolverConfig in the super-network.
  • Keep in mind that your standalone networks may have had different solver config data — you’ll need a config for the super-network solver that is compatible with all the subnetworks.
• For example:

mySimObject.superNetwork.netSolverConfig.mConvergenceTolerance      = 1.0e-3
mySimObject.superNetwork.netSolverConfig.mMinLinearizationPotential = 1.0e-4
mySimObject.superNetwork.netSolverConfig.mMinorStepLimit            = 10
mySimObject.superNetwork.netSolverConfig.mDecompositionLimit        = 20

• You can have a super-network object with jobs but with no sub-networks added to it.
  • It’s jobs will just do nothing.
  • This way, you can add super-networks to sim objects and set up their jobs in case they’re needed, and then you can activate them simply via input file — no re-compile needed.

• Finally, move the initial node assignments of whatever links you want to connect between the sub-networks to their new nodes in the super-network. See More On Link Node Mapping:The _mInitialNodeMap_ Input Data for how to do this. For example:

# Get each sub-network's node offset # in the Super-Network:
networkA_offset = mySimObject.networkA.getNodeOffset()
networkB_offset = mySimObject.networkB.getNodeOffset()

# Declare and have Trick allocate memory for a new array, in this example an int[2]:
initialNodeMap = trick.alloc_type(2, "int")

# Override the initial node map in the super nodes.  In this example we're connecting one
# of networkA's links between node 1 of networkA to node 42 in networkB:
initialNodeMap = [1 + networkA_offset, 42 + networkB_offset]

# Assign the link's shape data pointer to the array:
mySimObject.networkA.netInput.theLink.mInitialNodeMap = initialNodeMap

• As of right now, only GunnsDraw-export networks, or GunnShow networks exported from GunnShow v17.0.0 or later can be added to a super-network.
• To be able to use an old GunnShow network in a super-network, simply re-export it from the new version of the GunnShow install.

Added for GUNNS release v17.1 is the ability to nest super-networks within each other. This allows multiple levels of super-networks for better model organization.

During sim init, nested super-networks simply pass their sub-networks up to the higher level. As a result, during run-time the intermediate-level super-networks are actually empty & don’t do anything, and the top-level super-network actually orchestrates all the sub-networks added from below. This is illustrated so:

In this example, super-networks AB, ABC & DE are intermediate-level so they end up empty and don’t do anything during run, and super-network ABCDE has the actual node set & solver that orchestrates all of the sub-networks.

Super-networks now output additional info messages to the H&S log of which sub-networks they end up with at the end of initialization. This should help you verify & remember where all the sub-networks end up in a complicated arrangement.

Setup of nested super-networks is very similar in concept to the non-nested case:

• Nested super-networks are instantiated and given Trick jobs in the sim object just like non-nested super-networks.
• If you know for sure that a particular super-network will only ever be an intermediate-level and not a top-level super-network, then you can omit its Trick jobs completely. However just like with non-nested super-networks, it’s a good idea to go ahead and assign their jobs just in case.
• Nested super-networks can be defined in any order relative to each other in the sim object.

• The syntax for adding a super-network to another super-network is just like adding a sub-network. Add each desired network to a super-network by passing their names to the super-network, like so:

mySimObject.superNetworkABCDE.addSubNetwork(mySimObject.superNetworkABC)
mySimObject.superNetworkABCDE.addSubNetwork(mySimObject.superNetworkDE)

• You can add both normal networks and super-networks to a super-network.
• Just like when adding normal networks, only finalize the super-network after all sub-networks & sub-super-networks have been added to it. You use the same registerSuperNodes() method as before.
• The registerSuperNodes() call is optional for intermediate-level super-networks. It can be omitted, but it doesn’t hurt to call it anyway.

Here’s an example input file that would set up the nesting from the above picture:

# Set up super-network AB before adding it to ABC:
mySimObject.superNetworkAB.addSubNetwork(mySimObject.networkA)
mySimObject.superNetworkAB.addSubNetwork(mySimObject.networkB)
mySimObject.superNetworkAB.registerSuperNodes() # optional

# Set up super-network ABC before adding it to ABCDE:
mySimObject.superNetworkABC.addSubNetwork(mySimObject.superNetworkAB)
mySimObject.superNetworkABC.addSubNetwork(mySimObject.networkC)
mySimObject.superNetworkABC.registerSuperNodes() # optional

# Set up super-network DE before adding it to ABCDE:
mySimObject.superNetworkDE.addSubNetwork(mySimObject.networkD)
mySimObject.superNetworkDE.addSubNetwork(mySimObject.networkE)
mySimObject.superNetworkDE.registerSuperNodes() # optional

# Set up & finalize super-network ABCDE:
mySimObject.superNetworkABCDE.addSubNetwork(mySimObject.superNetworkABC)
mySimObject.superNetworkABCDE.addSubNetwork(mySimObject.superNetworkDE)
mySimObject.superNetworkABCDE.registerSuperNodes() # NOT optional!