This Wiki is a work in progress, and we will add detail and organize in the future.

What is Draw.io?

What is GunnsDraw? - Summary of current capabilities and future plans

GunnsDraw Dependencies

The GunnsDraw Workflows

TBD - Making GunnsDraw Networks in Draw.io

The GunnsDraw Shape Libraries

Exporting GunnsDraw Networks - gunns/draw/netexport.py

Custom User Shapes and Libraries

Migrating GunnShow/Visio Drawings to GunnsDraw - gunns/draw/gsmigrate.py

Super-Network Drawings with GunnsDraw - gunns/draw/supcreate.py and gunns/draw/supexport.py

Summary of the usual workflow:

• Use the Draw.io app to create & modify drawings, and save them in your model file space. More notes on Draw.io below.
• In a separate shell, run the gunns/draw/netexport.py script to generate the run-time network code from the drawing. More notes on that below.

• In Draw.io, select Device > Open Existing Diagram, then navigate to a drawing, such as gunns/draw/drawings/DrawElect.xml.
• Open our shape libraries by: File > Open Library From > Device, then navigate to the .xml files in gunns/draw/libraries/.
• In the Diagram settings pane on the right-hand side, we recommend turning off this Option: Connection Arrows. We don't need this feature since we use our own custom connector lines, and enabling the feature makes it harder to grab & move shapes around without creating & connecting unwanted duplicate objects.
• Draw.io can output the diagram .xml in either compressed or decompressed formats, and we can use either format. When you use File > Save, it outputs the compressed format. The only way to output the uncompressed format is to use File > Export as > XML, then un-check Compressed. For either option, select to save it to your device.
  • The browser app will download it to your browser's default downloads location, so you may have to then move the file to your model folder.
  • The desktop app saves the file to the same location you opened it from.
• You can start with a blank drawing in Draw.io, but we have an empty network drawing that'll save you some time. See _gunns/draw/drawings/EmptyNetwork.xml.
• NOTE that new versions of draw.io default new saved filenames with the .drawio extension, but our scripts require an .xml extension to operate on. Just make sure to change your drawing filenames to have a .xml extension.

• Make connections between links and nodes using the "Link Port" lines from the GUNNS_Generic.xml shape library. Don't use regular draw.io connectors, as they are ignored by the network export scripts.
• Each Link Port connection specifies which of the link's ports it connects to via its numerical label (the light-blue number on the line). Change this to the desired port number by selecting the connector line and typing the number.
• Although our link shapes sometimes imply a certain port is at a specific place in the shape, you can connect Link Port lines to anywhere in the shape because the Link Port line's label specifies the actual link port # that it connects to.
  • We provide pre-configured connector lines for ports 0 through 3 in the GUNNS_Generic.xml shape library. Once on the drawing, you can change the port # by simply selecting the connector line and typing in the new number. You can use this to make port numbers 4 or higher.

• To set or change a shape's label, simply select the shape and start typing. The label is used as the instance name in the exported network code, so this must be a valid C variable name.
  • By default, most shapes will have an empty label. They must be given a network-unique name in order for the network code to generate and build.
  • Node numbering: You should try to ensure that the drawing has a continuous set of node numbers starting at zero. The network export script will renumber the nodes if it finds missing or duplicated node numbers in the sequence. This can cause problems for you if you have spotters or other objects looking at specific node numbers. So we recommend inspecting the drawing and making any corrections necessary after a renumbering from the export script.

• In GunnsDraw, the network is represented by a network container shape. This serves several purposes:
  • It holds the name of the network class and the solver config data.
  • It allows control over which objects are to be included in the exported network -- only those objects that are children of the network container are included.
  • It allows easy copy of the network, and all of its contents, between network drawings and into super-network drawings. This can be done in draw.io by selecting the network container shape and then copying & pasting it. This also makes it easy for our super-network creation script supcreate.py to create a super-network drawing with many instances of sub-networks in it. Both kinds of operations copy all the network's children.
  • The network containers are collapsible, and this can be useful for arrangement and readability in super-network drawings.

• When you have a GUNNS shape (node, link, etc.) that is a child of a network container, if you copy & paste that object, draw.io doesn't make the newly pasted copy a child of that network, even though it may appear contained in the network container's box. This leaves the new shape not a child of the network, and it won't be included in the exported network, or copied along with the network when you copy & paste the network.
  • We don't know if this is a bug or 'feature' of draw.io.
  • The netexport.py script will warn of such excluded objects.
• To make sure the copied objects are children of the network, drag them over the network container boundary until the boundary highlights blue, before moving them to their final locations. By dragging them over the network container boundary, this causes draw.io to set it as their parent like we want.
• You can check whether a shape is a child of the network container by selecting it. If it is a child of the network, the network container's boundary will be outlined with a dashed blue line.

• When you run the netexport script, it changes the source drawing .xml file -- uncompresses it, does maintenance updates, etc. The export script will tell you if it made any significant content changes to the xml file.
• After you've done this, next time you try to save updates to the drawing from the draw.io app, it will detect that the source file has changed and whether you want to 'overwrite' or 'syncrhonize'.
  • Overwrite saves your new changes in the app to the .xml file -- if you've made changes to to the drawing that you want to keep, make sure to use this option. The maintenance updates from the export script can easily be remade by re-exporting it afterwards.
  • Synchronize abandons your changes in the app and reloads from the source .xml file, so you'll lose your changes. You only want to use this option if you want to see the maintenance changes to the .xml file from the export script, and don't have any changes in the app that you don't mind losing.
• So, it's always best to export your drawing after each time you save it from the app, then synchronize the app to the new .xml before you start making more changes in the app. The netexport script will tell you when it's made any significant content changes from maintenance that you'd want to synchronize the app to. So unless you see that message from the netexport script, there's no need to synchronize.

• Hovering over a shape will display the shape data in the tooltip pop-up window.
• Right-click on a shape and select Edit Data to edit the shape data. The shape data contains these properties:
  • ID this is a unique identifier used by draw.io that you can't change.
  • About this is the shape name it came from in the library, so you don't lose track of which kind of shape this is.
  • Ports this is a handy reference of what port numbers are needed for the link and their function (input & output, etc.)
    • GunnsDraw implements the concept of 'optional ports'. Some links have optional ports, which if left unconnected, default to the Ground node. This makes it easier to draw links that always have a Ground connection, like fluid & thermal capacitors. If the Ports field doesn't indicate a use for a certain port #, that means it is optional and you can leave that port # unconnected.
  • c## these are the Configuration Data fields.
  • i## these are the Input Data fields.
  • You can add more properties, such as notes fields, etc. These will be ignored by the network auto-code generator. However don't add any with the above names, or label or tooltip.

• See GunnsDraw Data Table
  • These are used for things like the battery link's Soc/Voc table, etc.
  • This gets turned into a TsLinearInterpolator object in the network. This is a linear table lookup/interpolator.
  • Values in the data rows must be integer or floating point format, no strings, as these are loaded into the table lookup interpolator.

• See GunnsDraw Socket List
• Our design allows any custom link to have a jumper plug function on any port. In the link shape XML, add the attribute plugs="#" to the element, where # is a comma-separated list of the link's port numbers that are to be plugs. Then also add configuration data fields to the link's shape data named Plug#="0", where # is the port number, for each plug. These have to be c## config items, but can be anywhere in the c## items order. For example, this makes ports 0 & 1 of this link into jumper plugs:
  • <object label="" About="Custom Link" c00.conductance="0.0" c01.Plug0="0" c02.Plug1="0" c03.otherConfigItem="0.0" ... >
  • <gunns type="Link" subtype="path/file" numPorts="2" reqPorts="0,1" plugs="0,1"/>

• in GunnsDraw, the links are ordered by their To Front/To Back arrangement on the drawing.
• This is controlled in the Arrange tab of the Format Panel.
• Draw.io renders objects in the order they appear in the XML file, so the last object appears in front of previous objects, etc. Our export script orders the links in the same order they appear in the XML file; therefore links that appear in the back are first in the list and get initialized first.
• To make a link init first, simply send it To Back.
• To make a link init last, then send it To Front.

• The export script ignores any objects that aren't in the original drawing layer.
  • By default this layer is called "Background".
  • In some of our drawings we rename this layer to "Network". The name doesn't matter, but it has to be the original layer.
• Make sure to put the network container in this layer.
• All your other network pieces (links, nodes, spotters, lists, tables, etc) have to be in the network container in order to be exported.
• This means that all your network pieces are in the same layer.
• You can use other layers to hide/show comments and other non-essential graphics for the network export, as these will be ignored by the export anyway.
  • See examples of this in the drawings in gunns/draw/drawings/.

• We only support 1 page per drawing. Anything on any other pages beyond the first is ignored.