Structure

The header declares every data item with a <key> element. The <graph edgedefault="directed"> element then contains graph-level <data> items, <node id="..."> elements, and <edge id="..." source="..." target="..."> elements. Node and edge identifiers must be unique; every edge endpoint must name an existing node.

Each key declaration includes a default. If a <data> element is absent, the reader uses that key's declared default; if the key itself is absent, it uses the fallback described below. Empty optional values are normally omitted by the writer. Files produced by older versions are accepted for the legacy edge types normal and constraint, which mean requirement.

The writer declares only the keys meaningful for the selected network type. STN, STNU, OSTNU, CSTN, CSTNU, CSTNPSU (also called FTNU), PCSTNU, and PSTN are supported. Thus, the absence of a key can be intentional: for example, an STN has Value, while a CSTN has LabeledValues instead.

Graph keys

The count keys describe the file and are written by the tool. When producing a file yourself, keep them consistent with its contents.

Stored outcomes

CheckOutcome and DispatchabilityOutcome are assertions made by the program that saved the file; they are independent. The first records a consistency or controllability result, while the second records a dispatchable or minimal representation. Both are used only when OutcomeFingerprint is present, has a supported version, and matches the network as read. If the network was changed, the fingerprint is unknown, or it does not match, the tool silently ignores both values and loads the network normally.

The tool writes CheckOutcome when a check completes, whether the verdict is positive or negative, and writes DispatchabilityOutcome whenever it produces a dispatchable or minimal representation. Both are dropped as soon as the network is modified. So their absence never means “false” — it means “not known”: no completed check backs a claim about this network as it currently stands. Do not write either key by hand without also computing a matching OutcomeFingerprint; a stale or hand-written pair that happens to match would be believed.

Node keys

Edge keys

In labels, juxtaposition means conjunction and ¬ negates a proposition. The empty set is {}; the empty label is ⊡. The reader also accepts the historical triple order (label, nodeName, integer) for upper- and lower-case maps, but new files should use the order shown in the table.

Contingent links

A contingent link (A, x, y, C) is not one edge. It is a pair of directed, contingent edges: the lower-case value is on A → C, and the upper-case value is on C → A. In initialized form, write LC(C):x on A → C and UC(C):-y on C → A. The node named in both case labels is the contingent endpoint C.

The reader also accepts the initial (not yet initialized) form: Value y on A → C and Value -x on C → A. Both edges are required in either form. Do not put both halves on one edge, and do not reverse the endpoints: this is the most common source of malformed STNU files.

Complete examples

These are real repository instances, shortened only to their essential complete GraphML content. They were selected from CstnuTool/Instances/stn01.stn, src/test/resources/testGraphML.stnu, and CstnuTool/Instances/ex2C_checked_DC.cstn.

<?xml version="1.0" encoding="UTF-8"?>
<graphml xmlns="http://graphml.graphdrawing.org/xmlns/graphml">
  <!-- The declarations make omitted data use these defaults. -->
  <key id="NetworkType" for="graph"><default>CSTNU</default></key>
  <key id="Name" for="graph"><default></default></key>
  <key id="x" for="node"><default>0</default></key>
  <key id="y" for="node"><default>0</default></key>
  <key id="Type" for="edge"><default>requirement</default></key>
  <key id="Value" for="edge"><default></default></key>
  <graph edgedefault="directed">
    <data key="NetworkType">STN</data>
    <data key="Name">stn01.stn</data>
    <node id="A1"><data key="x">259.0</data><data key="y">214.0</data></node>
    <node id="X1"><data key="x">372.0</data><data key="y">465.0</data></node>
    <!-- A directed requirement bound from A1 to X1. -->
    <edge id="eA1-X1" source="A1" target="X1">
      <data key="Type">requirement</data><data key="Value">-1</data>
    </edge>
  </graph>
</graphml>

<?xml version="1.0" encoding="UTF-8"?>
<graphml xmlns="http://graphml.graphdrawing.org/xmlns/graphml">
  <key id="NetworkType" for="graph"><default>CSTNU</default></key>
  <key id="x" for="node"><default>0</default></key>
  <key id="y" for="node"><default>0</default></key>
  <key id="Type" for="edge"><default>requirement</default></key>
  <key id="LabeledValue" for="edge"><default></default></key>
  <graph edgedefault="directed">
    <data key="NetworkType">STNU</data>
    <data key="nContingent">1</data>
    <node id="X"><data key="x">0.0</data><data key="y">0.0</data></node>
    <node id="Y"><data key="x">0.0</data><data key="y">0.0</data></node>
    <!-- X is A and Y is C: lower bound x = 2. -->
    <edge id="XY" source="X" target="Y"><data key="Type">contingent</data><data key="LabeledValue">LC(Y):2</data></edge>
    <!-- The reverse edge carries the negated upper bound -y = -5. -->
    <edge id="YX" source="Y" target="X"><data key="Type">contingent</data><data key="LabeledValue">UC(Y):-5</data></edge>
  </graph>
</graphml>

<?xml version="1.0" encoding="UTF-8"?>
<graphml xmlns="http://graphml.graphdrawing.org/xmlns/graphml">
  <key id="NetworkType" for="graph"><default>CSTNU</default></key>
  <key id="Obs" for="node"><default></default></key>
  <key id="Label" for="node"><default>⊡</default></key>
  <key id="LabeledValues" for="edge"><default></default></key>
  <key id="Type" for="edge"><default>requirement</default></key>
  <graph edgedefault="directed">
    <data key="NetworkType">CSTN</data>
    <!-- A? observes proposition a; ⊡ means it is always present. -->
    <node id="A?"><data key="Obs">a</data><data key="Label">⊡</data></node>
    <node id="n1"><data key="Label">¬a</data></node>
    <!-- This edge has value 4 when a is false. -->
    <edge id="e0" source="A?" target="n1"><data key="Type">requirement</data><data key="LabeledValues">{(4, ¬a) }</data></edge>
  </graph>
</graphml>

Filename extensions

GraphML is the file content regardless of the extension. Common extensions are .stn, .stnu, .cstn, .cstnu, .cstnpsu (FTNU/CSTNPSU), .pcstnu, .ostnu, and .pstn; use the extension matching the declared NetworkType. A generic .graphml file is also valid, but does not communicate the intended network kind to a person or to file-selection filters.

Luke's plain format and converters

Luke Hunsberger's plain text format is useful for exchanging STN, STNU, and CSTN instances with tools that expect its section-based text representation. It does not preserve GraphML presentation data such as coordinates, routes, or annotations. Luke2GraphML converts supported plain STN, STNU (including ESTNU), and CSTN files to GraphML; GraphML2Luke exports an STNU GraphML file as .plainStnu. Use GraphML for editing and complete round trips, and the plain format when interoperating with software that specifically requests it.