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.
Lexical rules
Section titled “Lexical rules”- A file is a sequence of lines. Lines are separated by
\nor\r\n; a lone\rcounts 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 (so1 2 # notereads as the line1 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:
wheredeclaration ::= numbers [ ':' type ]numbers ::= hex [ ws hex [ ws hex ] ]
wsis one or more spaces/tabs andtypeis a single whitespace-free token. - A
hextoken is one or more digits from0-9anda-f/A-F(case-insensitive). No0xprefix, no sign, no other characters. - The
:splits the line at its first occurrence. Whitespace around the:is free (1:Z(0),1 : Z(0), and1: Z(0)are all valid), but the type itself must be one whitespace-free token (Z (0)is invalid).
Vertex labels
Section titled “Vertex labels”- Every
hextoken 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,00aall denote the same vertex (hexa= decimal 10).01and1denote the same vertex.
- The canonical form, used for de-duplication, is lowercase with no leading
zeros (
0stays0). - 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 phasen * \pi / 4.Z(n)— a Z spider with phasen * \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).
Edge types (temporary; may change later)
Section titled “Edge types (temporary; may change later)”NC— the default edge type.H— a Hadamard edge.
Line semantics
Section titled “Line semantics”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. |
cis itself hex:fmeans 15,10means 16, and so on.c = 0declares the two vertices but adds no edge.- Self-loops are allowed:
a aanda a cdescribe an edge (orcedges) from a vertex to itself.
Resolution rules
Section titled “Resolution rules”-
Edges: an edge’s endpoints form an unordered pair, so
a bandb aare 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 22 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.
Errors
Section titled “Errors”The whole file is rejected, with the offending line’s number in the error, if any line (after comment stripping) contains:
- a multiplicity
cgreater 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.
Example
Section titled “Example”1 2 22 3 : H1 : Z(0)1 33Declares 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.
How Graphboard maps it
Section titled “How Graphboard maps it”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.