Graphs DSL
Graphs accepts a line-oriented text format for declaring nodes, positions, and edges. Paste a complete definition into the text editor on Graphs and click Apply. This page records the currently implemented syntax.
Differences from Chain DSL
The declaration format resembles Chain DSL, with these differences:
- Weights are arbitrary exact numeric values. Integers, fractions, decimals, zero, and negative values are accepted. They are not restricted to probabilities, and outgoing weights do not need to sum to
1. - Omitted weights default to
1, rather than Chain's0. - An undirected connection is one edge. No reverse edge is generated. Declaring both
edge A Bandedge B Ain an undirected graph is a duplicate. - There is no uniform-probability behavior. The parser currently accepts
uniformon nodes, but the Graphs model clears it when the graph is loaded. - Parameters have no live controls. Their values are resolved when text is applied.
- Polar parsing has no incremental placement-bound check. Coordinates still have to satisfy the integer, origin, and uniqueness rules below.
Complete example
This undirected Cartesian graph has three nodes and three weighted edges. Select Weighted to include weights in the editor's canonical text.
undirected
cartesian
param w 12
node A 0 0
node B 2 0
node C 1 2
edge A B w
edge B C 3/2
edge C A -2
Document structure
directed | undirected
cartesian | polar <interval-count>
param <single-letter-name> [=] <value>
node <name> <coordinate-1> <coordinate-2>
edge <from> <to> [weight] [straight]
- Declare exactly one graph mode and one coordinate mode, in either order, before nodes or edges.
- Declare parameters after both modes and before any nodes or edges.
- Nodes may appear after edges, provided every edge endpoint is declared somewhere in the document.
- The two mode declarations alone form a valid empty graph.
- Each nonempty line is one declaration. Blank lines are ignored.
- Commands and options are case-insensitive. Node and parameter names are case-sensitive.
Graph mode
directed
Each ordered source-destination pair may appear at most once. An edge from A to B and an edge from B to A are separate edges.
undirected
Each unordered pair may appear at most once. Declare a connection in either direction; the parser stores one edge and does not generate a reverse record. Parallel edges are not currently supported in either mode.
Coordinate mode
cartesian
Nodes use integer x and y coordinates. Negative coordinates are allowed; a node at the origin is optional.
cartesian
node Left -2 0
node UpperRight 2 3
polar <interval-count>
Nodes use an integer radius and interval index. The interval count must be an integer of at least 3. Index 0 lies on the positive x-axis; indices advance counterclockwise.
polar 12
node Origin 0 0
node Top 2 3
node Left 2 6
- Radius and interval index must be nonnegative integers.
- The origin must be written as
0 0. - Indices are reduced modulo the interval count. With
polar 12, indices1and13identify the same ray. - Two nodes cannot occupy the same normalized position.
- Coordinates and interval counts must be within JavaScript's safe integer range.
Parameters
param <single-letter-name> [=] <value>
A parameter name must be one ASCII letter and may be declared only once. Values are exact numeric constant expressions, with no probability range restriction.
directed
cartesian
param w = 12
node A 0 0
node B 2 0
edge A B w
edge B A 1-w
Edges may reference a parameter directly or use its complement in the exact form 1-w. General expressions involving parameters, such as w/2, 2*w, or 1 - w, are not supported. Parameter values cannot reference other parameters.
The optional equals sign is omitted in canonical output. Graphs has no live parameter sliders.
Nodes
node <name> <coordinate-1> <coordinate-2>
Names must be nonempty and unique. Positions must also be unique. Coordinates follow the selected coordinate mode.
The parser also accepts the trailing option uniform for compatibility with the existing declaration shape. It does not distribute weights in Graphs: the graph model clears this flag when loading the parsed graph, so it is omitted from the editor's subsequent output.
Edges and weights
edge <from> <to> [weight] [straight]
Both endpoints must match declared node names. Self-loops are allowed. Omitted weights default to 1.
Constant weights support integers, decimals, addition, subtraction, multiplication, division, parentheses or braces, and integer powers. LaTeX fractions, \cdot, and \times are also accepted. Evaluation uses exact rational arithmetic.
edge A B 12
edge B C 1 / 2^5
edge C A -3/2
edge A A
Negative exponents are accepted, for example 2^-5 or 2^{-5}. Nested powers, implicit multiplication, percentages, division by zero, and noninteger exponents are rejected. The exact-expression parser also enforces expression-length, exponent, and result-size limits.
Straight routing preference
Add straight after the optional weight to request straight routing. The option is retained if an obstruction requires automatic routing. Self-loops cannot use straight.
edge A B straight
edge B C 12 straight
Current graph-property calculations use edge presence and ignore weights. A zero-weight edge still participates in connectivity and cycle checks.
Names and comments
Enclose names containing whitespace, #, or a double quote in double quotes. Inside a quoted token, a backslash escapes the following character; use \" for a literal quote and \\ for a literal backslash.
node A_1 0 0
node "Waiting Room" 2 0
edge A_1 "Waiting Room" 12
A # outside double quotes begins a comment. Both full-line and trailing comments are accepted.
# One undirected connection
undirected
cartesian
node A 0 0
node B 2 0 # second node
edge A B
Validation and canonical output
The parser rejects missing, repeated, late, or malformed declarations; duplicate node names or positions; duplicate edges; unknown endpoints or commands; invalid coordinates or weights; malformed quoted tokens; and straight on self-loops. Parse errors associated with a declaration report its line number.
After applying text, the editor writes canonical output using the selected Weighted or Unweighted mode:
- Weighted: parameters and edge weights are included. Authored expressions and parameter references are retained with normalized whitespace. An omitted weight is written as
1. - Unweighted: parameter declarations and edge weights are omitted. Reapplying that text assigns
1to every edge. - Both modes retain graph and coordinate declarations, node names and positions, and straight-routing preferences.
- Nodes are written before edges. Names are quoted when they contain whitespace,
#, or a double quote. - Blank lines and comments are not preserved. No reverse edges are generated.