Skip to content

Graph3 Format

Graph3 (.graph3) is a line-based, plain-text encoding of an undirected multigraph (multiple edges between the same pair of vertices, and self-loops, are allowed). Each declaration line names one or two vertices and, when two are named, a number of parallel edges between them; an optional type suffix annotates the line’s vertex or its edges.

  • A file is a sequence of lines. Lines are separated by \n or \r\n; a lone \r counts as ordinary whitespace, not as a line separator.
  • Everything from a # to the end of the line is a comment and is stripped before parsing (so 1 2 # note reads as the line 1 2).
  • After comment stripping, a line consisting only of whitespace is blank and is ignored. Leading/trailing whitespace on a line is ignored.
  • What remains is one declaration:
    declaration ::= numbers [ ':' type ]
    numbers ::= hex [ ws hex [ ws hex ] ]
    where ws is one or more spaces/tabs and type is a single whitespace-free token.
  • A hex token is one or more digits from 0-9 and a-f / A-F (case-insensitive). No 0x prefix, no sign, no other characters.
  • The : splits the line at its first occurrence. Whitespace around the : is free (1:Z(0), 1 : Z(0), and 1: Z(0) are all valid), but the type itself must be one whitespace-free token (Z (0) is invalid).
  • Every hex token on a line names a vertex. Labels are numeric values, not strings: two tokens denote the same vertex if and only if they are equal as integers — case-insensitive digits, leading zeros ignored.
    • a, A, 0a, 00a all denote the same vertex (hex a = decimal 10).
    • 01 and 1 denote the same vertex.
  • The canonical form, used for de-duplication, is lowercase with no leading zeros (0 stays 0).
  • The vertex set is exactly the set of labels that appear somewhere in the file. No other vertices are implied, even if their labels fall numerically between two mentioned labels.

Type strings are matched case-insensitively (h = H, z(1) = Z(1)).

Vertex types (temporary; may change later)

Section titled “Vertex types (temporary; may change later)”
  • NC — the default type: a black dot.
  • X(n) — an X spider with phase n * \pi / 4.
  • Z(n) — a Z spider with phase n * \pi / 4.
  • H — a Hadamard node.

The number n inside X(...) / Z(...) is a plain decimal integer, written without a sign; leading zeros are allowed (x(0008)). It is reduced modulo 8, so Z(10) means Z(2) and Z(8) means Z(0).

  • NC — the default edge type.
  • H — a Hadamard edge.

Let a, b, c be hex integers and t a type string. For lines with two or three hex numbers, omitting the type suffix means the NC edge type; for a single-token line, omitting the suffix makes no type declaration (the vertex keeps any type an earlier line gave it).

Tokens Meaning
a Declare vertex a (isolated unless another line mentions it).
a b Declare vertices a and b, and one NC edge between them.
a b c Declare vertices a and b, and c parallel NC edges between them.
a : t Declare vertex a and set its type to t.
a b : t Declare vertices a and b, and one edge of type t between them.
a b c : t Declare vertices a and b, and c parallel edges of type t between them.
  • c is itself hex: f means 15, 10 means 16, and so on.
  • c = 0 declares the two vertices but adds no edge.
  • Self-loops are allowed: a a and a a c describe an edge (or c edges) from a vertex to itself.
  • Edges: an edge’s endpoints form an unordered pair, so a b and b a are the same connection. When several lines mention the same pair, multiplicities are summed per (pair, type); lines of different types on the same pair coexist as separate groups of parallel edges:

    1 2 3 → 3 edges between 1 and 2
    2 1 → now 1 more edge between 1 and 2 (total of 4)
  • Vertex types: when a vertex’s type is declared more than once, only the last declaration counts. A mention without a type suffix never resets the type.

  • Changing a vertex’s type never removes edges already declared on it.

The whole file is rejected, with the offending line’s number in the error, if any line (after comment stripping) contains:

  • a multiplicity c greater than 10 000 (decimal), or a pair whose summed multiplicity across all lines and types exceeds 10 000 — a parser safety ceiling;
  • an unknown type string — types are validated against the vertex universe on single-token lines and the edge universe otherwise;
  • any other malformed syntax: no hex token at all (e.g. a line starting with :), four or more hex tokens, a token that is not a valid hex integer, or a type suffix that is empty or contains whitespace.
1 2 2
2 3 : H
1 : Z(0)
1 3
3

Declares vertices 1, 2, 3 and these edges: two NC edges between 1–2, one Hadamard edge between 2–3, and one NC edge between 1–3. Vertex 1 has type Z(0); vertices 2 and 3 have the default type. The lone 3 on the last line is redundant — the vertex is already declared by its edges — but harmless.

Import. Vertices of type NC become black dot vertices. Vertices of type H become Hadamard vertices. Vertices of type X(n) or Z(n) become spider vertices with the corresponding phase (phase is n * \pi / 4). Each NC edge becomes a default-kind edge. H edges are imported as the dashed_blue kind as a temporary stand-in (Graphboard has no Hadamard edge kind yet). The multiplicity of edges is preserved. Imported vertices are laid out on a circle around the centre of your view; they carry no text label.

Export (the inverse). Black dot → NC, Hadamard → : H, X/Z spiders → X(n) / Z(n) with n the phase in π/4 steps (mod 8); default edges → NC, dashed_blue edges → : H. Parallel edges are consolidated into one line per (pair, type) with a hex multiplicity, and vertices get fresh hex labels 1, 2, … in canvas order. Anything the format cannot express — other vertex types, spider phases not in π/4 steps, dashed_red / dashed_light edges — is skipped, with the skips counted in # skipped ... header comments; edges touching a skipped vertex are skipped with it.