XML Schema of GunnsDraw Links - nasa/gunns GitHub Wiki

As an example, here is the XML for the gunns/aspects/thermal/GunnsThermalHeater link:

<object label="" About="Thermal Heater" Ports="0+ =nodes" c00.tuningScalar="1.0" c01.fluxDistributionFractions="0" i00.malfBlockageFlag="false" i01.malfBlockageValue="0.0" i02.demandedFlux="0.0" i03.malfFluxOverrideFlag="false" i04.malfFluxOverrideValue="0.0" id="dIVudQ8zmGPw1ia1FTpI-4">
  <gunns type="Link" subtype="aspects/thermal/GunnsThermalHeater" numPorts="0" reqPorts="0"/>
  <gunnsShapeData source="c00" target="double cTuningScalar"/>
  <gunnsShapeData source="c01" target="vector*double cFluxDistributionFractions"/>
  <mxCell style="verticalLabelPosition=bottom;align=center;fillColor=none;html=1;verticalAlign=top;strokeColor=#000000;strokeWidth=1;shape=stencil(1VZdb8IgFP01fayhYGv3uLivJ7Nk2Q9gelW2Cg1F6/79KOAmfkTSmOCSJuWe2x4ONyfkJGTcLGkNCUa0qWGqEvKQYLyhktGPSsNYd5YWzIYDNLIIpyuw4PP7ZPKmkSx9FVLpxQtQBdJ+1igpvqBlM+UoGF+CZMp2W0eLUFeTxwTda7R7yHgqONdqmOCN19nra3LKuPLUiLXjrvU2K+iEGBxZdOt2tNW36w1yUz8dSNDIORVkPBcSFlKs+eykvIpx+BSM68q8zEb28+Otdj/VtBvTUWPXXokN7J2h9A4xGiBy6hg+BZVTvaioXECq1+m8ogtvQNKx37nSsZduRKhpAeq93zJvrmToypRuWZNKoWg3O28Hx/hrpavIzZCvd1dfkFsEy83wVfViXy4OUotjqe053WhmyA7kBo03R7Hk9ppuHs0Nfbw7LP+Xd+OZoZd3i/CL7Ba8W0RzQx/vFuH32E14N5oZ+mWGMvwiC8s4XfT6o3fhMpDDhL4zMUwHZZNmTwbFozhoUJusDfAD);fontSize=12;fontColor=#000000;" vertex="1" parent="1">
    <mxGeometry x="20" y="20" width="80" height="20" as="geometry"/>

Here is a description of all that stuff:

• object – this is the outermost tag for a custom shape in draw.io, and for all GUNNS links. All of the attributes of this element except for label and id are displayed in the pop-up tooltip box when you hover over the shape.
  • label – this attribute holds the text that is displayed next to the shape, and we use that as the link’s instance name in the exported code.
  • About – this attribute indicates to the user what kind of link this is.
  • Ports – this provides hints to the user about the link’s intended port connections.
  • c## – these attributes hold the link configuration data values. These correspond to the arguments in the link’s ConfigData constructor, not including the name and nodes arguments. When draw.io displays the pop-up tooltip box, it displays all these elements in alphabetical order. We use these ## number fields to control the displayed order and to correctly the order the values are given to the link constructor in the exported code.
  • i## – these attributes hold the link input data values. These correspond to the arguments in the link’s InputData constructor.
  • id – this attribute is a drawing-unique identifier used by draw.io. Every shape (object or mxCell) in a drawing must have a unique id, or draw.io won’t render the drawing. Whenever a new shape is placed on a drawing, draw.io gives it a unique value. Shapes use these id fields to know which other shapes they have relationships with, like child/parent or connector lines, etc.
• gunns – this element tells our GunnsDraw scripts how to handle the shape.
  • type – this attribute tells our scripts what kind of GUNNS object this is: link, node, spotter, etc. For links, this is always ‘Link’.
  • subtype – this attribute identifies the kind of link this is. It is used by the GunnsDraw scripts to find this link’s shape master in the shape libraries, and is also used in the #include statement for the link’s class in the exported code.
  • numPorts – this attribute tells how many ports the link has. For fixed-numbered port links, this value is > 0. For variable-port links, this is 0.
  • reqPorts – this attribute tells which ports are required to be connected to a node shape by a Port connector line. This is a comma-separated list, e.g. ‘0,1’ or ‘0,1,2’. For variable-port links, since every link must always have at least one port, there must be at least one port number in this list (usually 0).
  • variant – this is an optional attribute that identifies this shape as a unique variant for the given subtype. This is used to define alternate shape data for links that support multiple variants. An example of a link that has variant shapes using this feature is GunnsElectPvArray.
• gunnsShapeData – these elements tell our GunnsDraw scripts about any ‘c##’ or ‘i##’ attributes on the object element that have to be handled differently than normal. This happens for link config or input data that are vectors, or have variable names that don’t follow the standard naming convention. Links may have zero or more of these gunnsShapeData elements, as needed. Most links will have not have any.
  • source – this attribute tells our scripts which c## or i## attribute holds the value for the target destination.
  • target – this attribute tells our scripts where the source values go and which syntax to use in the exported code. Both options are present in the example XML above. These are:
    • ‘type name’ – the default naming convention in GUNNS is to start class variables with an ‘m’, and then the next character is upper-case, in the camel-hump style. GunnsDraw assumes that all c## and i## attributes are arguments to the link’s config & input data constructors that follow this convention. This field is used to tell GunnsDraw that the target variable name in the link’s class has a different name. For example, the i00.malfBlocksageFlag argument goes to mMalfBlockageFlag in the link’s input data class. This matches the convention, so that argument doesn’t need this gunnsShapeData element for it. But c00.tuningScalar goes to a variable named cTuningScalar in the link, which doesn’t follow convention.
    • ‘vector*type name’ – this is special syntax for link config or input data that is a pointer to a vector of values. For instance in the above example, the target variable for the c01.fluxDistributionFractions value is declared in the link’s config data class as std::vector cFluxDistributionFractions. The GunnsDraw scripts handle the conversion from the supplied pointer argument to the non-pointer class attribute in the exported network code.
• mxCell – this is draw.io’s element for holding information about how to render the shape. Most things in here are formatting information like line color & fonts, which we won’t detail here. Here are a few things that are important for us in a custom link:
  • shape – this field in the style attribute has the actual shape graphics. This will either be a function call to a built-in draw.io shape, or a compressed blob for a custom shape. Most of our GUNNS links are custom shapes and appear as these compressed blobs. More on that below.
  • parent – this attribute identifies the parent object of this link in the drawing. This will always be the network container that the link is placed in.
• mxGeometry – this is draw.io’s element for placement & scaling information of the shape in the diagram.
  • x & y – these are the default x & y coordinates of the shape, measured from the top left.
  • width & height – these are the default dimensions of the shape. It is important that the ratio of these values matches the ratio of the ‘w’ and ‘h’ values in the Edit Shape window (more on that later), or the shape will appear squished in one direction.