Chain Generator DSL | Markov Labs

Complete example

This directed Cartesian chain has two states and four transitions.

directed
cartesian

node Sunny -1 0
node Rainy 1 0

edge Sunny Sunny 3/4
edge Sunny Rainy 1/4
edge Rainy Sunny 0.4
edge Rainy Rainy 0.6

Each nonempty line is one declaration. Blank lines are ignored. The graph mode and coordinate mode must appear before every node or edge.

Document structure

A chain definition begins with one graph mode and one coordinate mode, in either order. Nodes and edges follow both declarations.

directed | undirected
cartesian | polar <interval-count>
node <name> <coordinate-1> <coordinate-2> [uniform]
edge <from> <to> [weight]

Declare exactly one graph mode.
Declare exactly one coordinate mode.
Declare nodes and edges after both modes.
Nodes may be declared after edges, but every referenced node must exist somewhere in the document.
Nodes and edges are optional; the two mode declarations alone form a valid empty graph.
Commands and options are case-insensitive. Node names are matched exactly as written.

Graph mode

`directed`

Edges have an arrow from the source state to the destination state. Each ordered pair may be declared at most once.

`undirected`

The graph displays connected states without arrowheads, but transition probabilities remain directional. If an edge is declared in only one direction, the parser creates the missing reverse edge. Its weight is 0, unless the reverse source node is uniform. Declare both directions when they need distinct nonzero probabilities.

undirected
cartesian
node A 0 0
node B 2 0
edge A B 1

Applying this definition produces both A → B with weight 1 and B → A with weight 0.

Coordinate mode

`cartesian`

Cartesian nodes use integer x and y coordinates. Coordinates may be negative, and no node is required at the origin.

cartesian
node Left -2 0
node UpperRight 2 3

`polar <interval-count>`

Polar nodes use an integer radius followed by an integer interval index. The interval count must be at least 3. Index 0 lies on the positive x-axis, and 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.
Interval indices are reduced modulo the interval count. With polar 12, indices 1 and 13 describe the same ray.
Two nodes cannot occupy the same normalized polar position.
After the first polar node, each new node must remain within the generator's placement bounds around the nodes already parsed.

Nodes

node <name> <coordinate-1> <coordinate-2> [uniform]

A node name identifies the state in later edge declarations. Names and positions must be unique.

Uniform outgoing probabilities

Add uniform to divide probability equally across every edge leaving the node. Edges from a uniform node must not include weight tokens.

directed
cartesian
node Start 0 0 uniform
node Heads 2 1
node Tails 2 -1
edge Start Heads
edge Start Tails

Here each outgoing edge from Start has effective probability 1/2. Adding or removing an outgoing edge changes the uniform probability automatically.

Edges and weights

edge <from> <to> [weight]

Both endpoints must match declared node names. Self-loops are allowed. Each directional source-destination pair may appear only once.

A non-uniform edge weight may be a decimal or fraction from 0 through 1, inclusive. Percentages and arithmetic expressions are not accepted. If the weight is omitted, it defaults to 0.

edge A A 1/3
edge A B 0.5
edge A C

Individual weights are range-checked when the text is applied. The Probability Checker separately determines whether all outgoing weights from each state sum to exactly 1.

Names and comments

Names containing whitespace or # should be enclosed in double quotes. The canonical serializer leaves names containing only letters, numbers, underscores, periods, and hyphens unquoted; it adds double quotes around other names.

node A_1 0 0
node "Waiting Room" 2 0
edge A_1 "Waiting Room" 1

Inside a quoted name, write \" for a literal double quote and \\ for a literal backslash.

A # outside double quotes begins a comment. Full-line and trailing comments are both accepted.

# Two-state absorbing chain
node Active 0 0
node Absorbed 2 0 # terminal state
edge Absorbed Absorbed 1

Validation and canonical output

The parser rejects a definition when it contains:

a missing, repeated, late, or malformed mode declaration;
an unknown command, node option, or extra token;
a duplicate node name or position;
a duplicate directional edge or an edge referencing an unknown node;
a coordinate that is not an integer or violates the selected coordinate mode;
an invalid edge weight or an explicit weight on an edge from a uniform node.

The editor uses the same shared parser and serializer as saved chains and embedded chain diagrams. After a definition is applied, the text editor may rewrite it into canonical form: declarations are normalized, names are quoted when required, fractions are reduced, and generated reverse edges in undirected graphs are made explicit.