Super Network Drawings with GunnsDraw

See here for a review of super-networks.

Review the general workflow for super-networks with GunnsDraw here.

In Trick simulations, super-networks are configured by a Trick input file.

GunnsDraw can be used to create, modify & maintain a drawing representing an entire super-network, and export the Trick input file that configures it.

The general process is listed here, and each step is detailed below:

• Use supcreate.py to create a new super-network drawing with chosen sub-network contents.
• Edit the new super-network drawing in Draw.io to configure and connect sub-networks.
• Use supexport.py to export the Trick input file.
• Later, use supexport.py and editing in Draw.io to modify and maintain the drawing.

There are two ways to make connections between the sub-networks in a super-network drawing. Both methods follow the same general steps listed above, but the details are different:

1. The Super-Ports Method (the old, original method), whereby you override individual link ports to connect to nodes in another sub-network. The remainder of this wiki pages describes this method.
2. The Interfaces Method (the new method), whereby you set up interface groups in each sub-network and then connect those together. This method is described in another wiki page linked here.

Both of these methods have pros and cons. The Super-Ports method creates super-drawings that are very large and complicated, and Draw.io begins to bog down and get sluggish as these drawings become too big. The Interfaces method was developed to avoid that problem - it creates simpler, cleaner & faster drawings, at the cost of less visibility into the complete model.

Super-Ports Method

Here follows a description of how to create and update super-drawings using the original Super-Ports method:

Create a new Super-Network: supcreate.py

The Python script gunns/gunnsdraw/supcreate.py can be used to create a new super-network drawing. NOTE that it requires the Python Tkinter package -- see here for more information.

This script can't modify an existing drawing. Use Draw.io and the supexport.py script for that.

To use supcreate.py

• Start the script with:
  • $ python <path to your gunns/ folder>/draw/supcreate.py
• Look for the 'Super-Network Create' window to pop-up.
  • It might not pop-up in front of existing windows, or grab focus, so look for it.

• Click the 'Select project path' button:
  • This pops up a file browser dialog.
  • Navigate to and select the project path folder. This should be a common folder to which sub-network source drawings can be navigated from.
• For each type of sub-network you want to add:
  • Click the 'Add' button.
  • Navigate to and select the sub-network drawing file.
  • Click the '+' and '-' buttons to set how many instances of this sub-network type to add to the super-network.
  • Make sure you get the # of instances correct before you move on to the next sub-network type, as you can't change it once you've moved on. If you need to change a previous sub-network, close the window and start over.
• Click the 'Select output file' button:
  • Navigate to the desired output folder and enter the name of the drawing file to create.
  • Below is an example screenshot of the window with everything filled out and ready to create the drawing:

• Click the 'Create' button to create the super-network drawing.
  • The application will output information and indicate success or failure to the console. For example:

('Creating', '/Users/jharvey1/repos/gunns/sims/networks/fluid/test/ExampleSuperNetwork.xml', '...')
('  Including', 2, 'instances of', '/Users/jharvey1/repos/gunns/sims/networks/fluid/test/distributedIf/DistributedIfFluid.xml')
('  Including', 4, 'instances of', '/Users/jharvey1/repos/gunns/sims/networks/fluid/test/TestFluidNetwork.xml')
Complete!

• The initial output super-drawing will look something like this in Draw.io:

Edit the Super-Drawing in Draw.io

The initial super-network drawing requires editing in Draw.io before it can be exported.

• Edit the Super-Network container:
  • Name the container. This will be the name of the exported Trick input file and the prefix on functions within the file.
  • Optionally, set its SimVariable shape data to the simulation variable of the super-network object. This can help developers as a reference to where to find this super-network in the sim.
• Edit the sub-network containers:
  • Name each with a unique instance name:
    • These will be the names they are reference by within the exported Trick input file.
    • The order of arguments to the Trick input file match the initial order of the sub-networks as they are listed in the initial output of supcreate.py
    • Note that the order is changed if you 'To Front' or 'To Back' any of the sub-networks. Normally you shouldn't need to modify the order, so it is best to not arrange the Front/Back-ness of the sub-networks.
  • Expand and arrange the containers to your liking. They can be expanded or collapsed when exporting, but expanding them is necessary to create super-port connections, below. You will want to resize the Super-Network container to still wrap around and contain them all.
  • Optionally, set each sub-network's SimVariable shape data to its variable name in the sim.
• Create super-port connections between the sub-networks.
  • Open the GUNNS_Super.xml shape library and use the red Super Port connectors to connect nodes and links across sub-networks.
  • Just like regular ports, these must only connect nodes to links, and not nodes to nodes or links to links.
  • The super-port's label (0, 1, 2, etc.) controls which regular port's connection is overridden.
  • Note that a sub-network that has no connections to other sub-networks doesn't need to be in the super-network, and degrades super-network performance for no benefit.

Below is an example super-drawing after some editing (note this isn't the same as we created above):

Modify & Export a Super-Network: supexport.py

The supexport.py script is used to export the Trick input file that configures the super-network in the Trick sim. It also does some maintenance updates to the source super-network drawing.

• Run the supexport.py script by going into the gunns/draw/ folder, then do: $ python ./supexport.py
  • You can add the path/filename of the super-network diagram .xml file to the command line, else it will pop up a file selection browser for you to select the file.

Here are the options and arguments the script accepts:

• -h, --help: shows a help message and exits
• -d: looks in your ~/Downloads folder for a newer version of the drawing file.
  • This is handy when you run Draw.io in a web browser that only saves updates to the drawing in your Downloads folder.
  • If it finds a newer date/timestamp on the drawing in your Downloads folder than the file location you specify, it will pop-up a message asking if you want to use the Downloads version or not.
  • If you say yes, it will process the version from your Downloads folder and save the maintained version over the path/file that you selected.
• -m: Not implemented yet.
• -g: Not implemented yet.
• -u PROJECT_PATH: automatically updates all sub-network instances in the super-drawing with the latest contents of their source drawings:
  • add your absolute project path: the script appends the sub-network's source drawing relative path to this path to find the total path to each source drawing.
  • The script will only update from source drawings that have a newer time stamp than the super-network drawing. This allows you to control which sub-network types get updated. If he super-network file drawing is newer than one of the source drawings you want to update from, simply update the source drawing's time stamp with a linux touch command or similar.

Adding & Deleting Sub-Networks

Sub-networks can be added or removed from a super-network drawing after it has been created.

• To add, simply copy the entire network container box from the sub-network drawing and paste it into the super-network container box in the super-network drawing.
  • Make sure to give the new sub-network a unique name, and update its shape data as applicable.
  • You can also copy sub-networks from inside the super-network.
• To delete a sub-network, simply delete its network container box from inside the super-network container.
• When you next run supexport.py, the script will renumber the super-network nodes in the drawing, and update the new sub-networks shape data as needed.