Skip to content

Link_Dynamic_Node_Mapping

Jump to bottom
Jason Harvey edited this page Feb 19, 2021 · 1 revision

{{>toc}}

Link Dynamic Node Mapping

By “Node Mapping” we mean which nodes a link is connected to. Most links can change which nodes they’re connected to in run-time. This can be very useful:

  • Jumpers use this feature when they disconnect from and connect to different sockets,
  • You can manually move links around for various debug & tuning purposes,
  • You can keep spare links off to the side and hook them into a network when needed.

The Node Map

The link’s mNodeMap array shows which nodes it is currently connected to. You can display this array on Trick View. The link’s mNumPorts defines how many nodes the link connects to, and therefore how big the mNodeMap array is. So to view the link’s node map on Trick View, select array offsets from 0 to mNumPorts minus 1.

Whenever you change a link’s node connections, they’ll be reflected in mNodeMap.

Some links can change their node map automatically (in particular: Jumpers). But you can also change them yourself as desired. You can’t set mNodeMap directly. Rather, every link has special controls you can use via Trick View to move them around. The controls and how to use them are detailed below.

Manually Moving a Link

Via Trick View, you can manually change a link’s node map one node at a time. Every link has 3 terms you use to move it, which you set in this order:

  1. Set mUserPortSelect: This specifies which of the link’s ports you are moving. The ports number from 0 to mNumPorts – 1, just like mNodeMap. Most link’s ports have a specific purpose. For instance, most fluid conductors (valves, pumps, etc) are 2-port links, and Port 0 corresponds to their inlet and Port 1 to their exit. This value defaults to -1, and returns to -1 after a command attempt.
  2. Set mUserPortSelectNode: This specifies which node to move the selected port to. This can include the network’s Ground node. The nodes range in number from 0 to mNodeList.mNumNodes – 1, which mNumNodes – 1 being the network’s Ground node. You can skip setting this if you are using the GROUND or DEFAULT commands below. This value defaults to -1, and returns to -1 after a command attempt.
  3. Set mUserPortSetControl: This is the “fire” command. It is an enumerated type that has these possible values:
    • READY: this is the default value, and also indicates successful completion of a move.
    • EXECUTE: setting this causes the link to attempt to move its specified port to the specified node. This term will then change to either READY or FAILED depending on the result.
    • GROUND: setting this causes the link to attempt to move its specified port to the network’s Ground node. This command is a shortcut so you don’t have to set mUserPortSelectNode to the Ground node’s number. This term will then change to either READY or FAILED depending on the result.
    • DEFAULT: setting this causes the link to attempt to move its specified port to its default node. The default nodes are the original nodes the link is connected to when the network is initialized. This command is a shortcut so you don’t have to set mUserPortSelectNode to the default node’s number. This term will then change to either READY or FAILED depending on the result.
    • FAILED: this value indicates a failed move attempt. Link’s will fail to move if you give them invalid mUserPortSelect, or mUserPortSelectNode values. The link will also output a detailed message of why the command failed to the Health & Status log.

Verifying the Move

There are 3 ways to verify that a manual move attempt was successful:

  • The link’s mUserPortSetControl term will change back to READY after successfully completing the move.
  • The link’s mNodeMap array position for the commanded port will change to the node number you commanded.
  • The link will output an INFO message to the Health & Status log describing which port was moved to which node, and that it was a user-commanded move.

When a move fails, the link remains attached to the same node it had before. A failure doesn’t break or disable the link, so you can try again with different inputs.

Examples

Here I am setting up the controls to move a link called tank. These are the default values when I first call up the terms in Trick View. The link has 2 ports, and they’re currently mapped to Nodes 1 and 2:

I want to move this tank’s Port 0 over to Node 0, so I set the terms and select EXECUTE like so:

Hers is the successful result on Trick View:

…and the success message in the Health & Status log:

INFO | GUNNS        | +000 00:00:01 | 2015-07-24T16:42:00Z | GunnsBasicLink.cpp:407 setPort() |
 testSimObject.fluid.tank user moved port 0 from node 1 to node 0.

Here I am setting the controls for a move that will fail:

And the results indicating failure:

WARN | GUNNS        | +000 00:00:02 | 2015-07-24T18:23:10Z | GunnsBasicLink.cpp:500 checkPortDuplication()  |
 testSimObject.fluid.tank aborted setting a port: ports cannot share the same non-boundary node 0.

See Also

More_On_Link_Node_Mapping – defaults, checkpointing, troubleshooting, etc.

Clone this wiki locally