Layout functions

layout and layout-sequence are top-level functions exported by lib.typ, not members of a public layout module. Their generated entries come from the shared layout.typ implementation and use the public export names.

Concepts

Placements

graph.pos creates a first-class placement. The default mode: "pin" turns a coordinate into a fixed layout constraint and, for x/y, a drawable position. Use mode: "start" when the coordinate should only seed the layout, or use graph.pin(value) / graph.start(value) to choose a mode for one axis:

#let g = build({
  node(<a>, pos: graph.pos(x: -2, y: 0))
  node(<c>, pos: graph.pos(ref: <a>, dx: 4, dy: 0))
  edge(source(<a>), <a-c>, sink(<c>), pos: graph.pos(x: 0, y: 1.2))
})

Auxiliary z is force-layout depth in the same numeric layout units as x/y, not a Typst length or a rendered coordinate. Both graph.build and graph.map accept graph.pos(z: graph.pin(2)) for a hard raw-depth pin and graph.pos(z: graph.start(2)) for a movable initial depth. A bare graph.pos(z: 2) follows mode, defaulting to "pin":

#let g = graph.map(g,
  node: node => (pos: graph.pos(z: graph.pin(2))),
  edge: edge => (pos: graph.pos(z: graph.start(-1))),
)

A z-only placement leaves XY coordinates, constraints, and partial-position flags alone, including automatic edge midpoint seeds. Omitting z preserves existing depth metadata during unrelated XY patches. ref, dx, and dy affect XY only; z groups, relative depth references, dz, and non-finite z values are not supported.

Node and edge statements expose "pos-z" as finite numeric text and "pos-z-mode" as "pin" or "start". These describe the supplied raw pin or seed; output pos remains a two-coordinate x/y record. The force solver multiplies raw depth by a global scale that flattens to zero: a hard raw pin remains fixed even when its effective depth is zero. Other layout backends do not use z. Auxiliary depth does not change draw order or provide an over/under rendering layer.

graph.group links one XY coordinate across several nodes or edge control points. A side of “+” keeps the coordinate positive, and “-” keeps it negative. Use start to seed the shared coordinate without fixing it. Matching node and edge groups are one degree of freedom during force and annealing layouts, so repulsion and springs act on their combined force rather than being reconciled afterward. If several members supply starts for one group, their mean initializes the shared coordinate. GammaLoop external-edge columns use this to keep incoming and outgoing external legs on opposite sides while pairing rows by a shared y group:

#let edge-items = (
  edge(
    source(<right-ext>),
    sink(<center>),
    pos: graph.pos(x: graph.group("right", side: "+", start: 4), y: graph.group("edgee0")),
  ),
  edge(
    source(<center>),
    sink(<left-ext>),
    pos: graph.pos(x: graph.group("left", side: "-"), y: graph.group("edgee0")),
  ),
)

Raw DOT input uses the same placement model through the pos attribute. The standard Graphviz subset is preserved: pos="x,y" is a starting coordinate and pos="x,y!" is pinned. Linnest extends the value with explicit id references and axis entries. In axis entries, ! belongs to that axis: numeric entries without ! are starting coordinates, numeric entries with ! are fixed constraints, and grouped entries must use ! because groups are constraints.

digraph {
  a [id=0 pos="0,0!"]
  b [id=1 pos="ref(node:0)+4,0!"]
  a -> b [id=0 pos="ref(node:1)+0,1!"]
  b -> c [id=1 pos="ref(edge:0)+1,0!"]
  c [id=2 pos="x:2!"]
  d [id=3 pos="x:2!,y:1"]
  ext -> a [id=2 pos="x:@-left!,y:@edge0!"]
}

The DOT grammar is intentionally id-based: ref(node:0) uses a node id and ref(edge:0) uses an edge id. Bare names and implicit edge order are not placement references. The @ syntax denotes grouped coordinate constraints; @+name and @-name keep the grouped coordinate on the positive or negative side respectively.

pos="x,y"                   // start x and y
pos="x,y!"                  // pin x and y
pos="x:<coord>"             // start numeric x
pos="x:<coord>!"            // pin x
pos="y:<coord>!"            // pin y
pos="x:<coord>!,y:<coord>"  // pin x, start numeric y
pos="x:<coord>,y:<coord>!"  // start numeric x, pin y

Layout Model

layout starts from a traversal-tree placement, then optimizes the positions of graph nodes and edge control points. The initial tree spacing is

,

with horizontal spacing ${𝜏}_{𝑥}𝐿$ and vertical spacing ${𝜏}_{𝑦}𝐿$. Here $𝜆$ is length-scale, $𝑊$ is viewport-w, $𝐻$ is viewport-h, ${𝜏}_{𝑥}$ is tree-dx, and ${𝜏}_{𝑦}$ is tree-dy. These fields set the geometry scale for both layout modes. Isolated subgraph layout uses the number of selected incident nodes for $𝑛$; other layouts use the full graph node count.

For deterministic, non-iterative placement, use layout-algo: "tree" or layout-algo: "dot". "tree" places a traversal forest by levels. "dot" uses a directed layered placement for acyclic inputs, falling back to tree placement when the selected edges contain a cycle. Both modes also work on a subgraph:

#let g = parse("digraph partial { a -> b; b -> c; c -> d; d -> a }").at(0)
#let tree = graph.forests(g).at(0)
#let g = layout(g, layout-algo: "tree", subgraph: tree)
#draw(g)

Only nodes touched by the selected subgraph are placed. Edge control points are then resolved from the current node positions, so edges outside the selected subgraph are drawn as straight lines unless their own position constraints say otherwise.

layout-algo: "force" and layout-algo: "anneal" also accept subgraph. The default solver.subgraph-mode: "fixed-boundary" keeps nodes and edge control points outside the selection fixed while retaining their spring, repulsion, centroid, and crossing interactions. Set solver: (subgraph-mode: "isolated") to omit unselected half edges, nodes, control points, and labels from those interactions. Selected halves of otherwise paired edges become dangling boundaries of the isolated solver domain. Complement coordinates and labels remain unchanged, and an empty selection is a no-op. An isolated selection cannot split a grouped coordinate; expand the selection or remove that group.

Set layout-nodes: "fixed" to keep every node at its current pos for this layout pass and move only edge control points. With subgraph, only edges in the selected subgraph are moved; all other edge control points keep their current positions. The fixed-node policy is temporary; the returned graph stores the resulting coordinates as pos, but it does not turn them into persistent pin constraints. This is useful after one node-placement pass when a later pass should route or relax selected edges without disturbing the node layout:

#let g = parse("digraph partial { a [pos=\"0,0\"]; b [pos=\"4,0\"]; c [pos=\"8,0\"]; a -> b; b -> c }").at(0)
#let first = subgraph.bits(g, (true, true, false, false))
#let g = layout(g, layout-algo: "tree", layout-nodes: "fixed", subgraph: first)
#draw(g)

Related controls can be supplied as shallow semantic records. These records only name graph-layout concepts; they do not select a drawing domain or style:

#let common = layouts.options(
  spring: (strength: 8, length: 0.5),
  repulsion: (edge-node: 0.05, dangling: 2),
  constraints: (side-strength: 5),
  labels: (steps: 0),
  solver: (algorithm: "force", steps: 50),
)
#let spacious = layouts.options(
  base: common,
  spring: (length: 0.7),
  repulsion: (dangling-centroid: 3),
)
#let g = layout(g, ..spacious)

layouts.options performs a sparse update: the second spring record above changes length without losing the inherited strength. Grouped fields override their corresponding flat arguments. Flat arguments remain useful for numerical experiments and controls that do not have a semantic grouping.

The shared spring/charge model uses the following coefficients:

The Typst parameter names are beta for $𝛽$, gamma-ev for ${𝛾}_{\text{ev}}$, gamma-ee for ${𝛾}_{\text{ee}}$, g-center for ${𝑔}_{\text{center}}$, gamma-dangling for ${𝛾}_{\text{dangling}}$, and gamma-dangling-centroid for ${𝛾}_{\text{dangling-centroid}}$. The spring stiffness $𝑘$ is k-spring, and the softening constant $𝜀$ is eps.

In layout-algo: "anneal", linnest minimizes an energy:

.

Here $𝑣$ is the mean node position. The centroid term pushes every dangling endpoint away from that mean; its equal-and-opposite reaction is shared over the nodes so it introduces no net force. ${𝑝}_{\text{cross}}$ is crossing-penalty and ${𝑁}_{\text{cross}}$ is the number of detected edge crossings. The quadratic center term pulls nodes toward the origin at every radius. temp, step, seed, steps, epochs, cool, accept-floor, step-shrink, and incremental-energy belong to this simulated annealing mode. crossing-penalty is also anneal-only; force mode does not currently add a crossing force.

In layout-algo: "force", linnest applies the direct forces corresponding to the same vertex-vertex, edge-vertex, incidence spring, local edge-edge, dangling-edge, dangling-centroid, and center terms. step is the integration step, delta clamps per-step movement, steps and epochs set the iteration budget, and cool shrinks the step after each epoch. early-tol can stop the run when movement is small only after the effective depth scale reaches zero; small movement or a cooled-to-zero step cannot skip flattening.

The force-only depth-scale (default 1.0) and flattening-end (default 0.5) control auxiliary depth. depth-scale must be finite and non-negative; flattening-end must be finite and in 0..=1. They can be supplied as flat arguments or in solver: (depth-scale: 1.0, flattening-end: 0.5); grouped values override flat ones. The old depth-spring controls are not aliases.

Effective depth is scale * raw-z. The integrator starts with auxiliary raw depths to break overlaps and smoothly reduces scale from depth-scale to zero over the initial flattening-end fraction of the total steps × epochs iteration budget. For normalized progress u from 0 to 1 over that interval, the smoothstep scale is depth-scale * (1 - u)^2 * (1 + 2 * u). The remaining iterations relax projected overlaps with effective depth exactly zero, so repulsion cannot be satisfied by invisible separation. flattening-end: 0 or depth-scale: 0 starts in 2D; flattening-end: 1 still evaluates the final iteration on the exact plane.

There is a single original iteration budget and cooling schedule: flattening neither adds a second phase nor restarts step. Unpinned raw depths stay bounded by the initial spread and supplied depth magnitudes; hard raw-depth pins remain fixed even after their effective depth has flattened to zero. XY pins, shared coordinates, and fixed subgraph boundaries apply throughout; label layout runs only after this single graph pass. Output positions remain 2D, and auxiliary z does not alter draw order. Flattening is exact, while force convergence remains limited by the iteration budget and movement tolerance.

directional-force is applied in both modes as an extra bias derived from pin/port direction constraints.

After either graph layout mode, labels are relaxed separately. If ${𝐿}_{𝑙}$ is the label target distance and ${𝑞}_{𝑙}$ is the label repulsion strength, then ${𝐿}_{𝑙}={𝛼}_{𝑙}𝐿$ and ${𝑞}_{𝑙}={𝛽}_{𝑙}{𝐿}^2$. The Typst names are label-length-scale for ${𝛼}_{𝑙}$ and label-charge for ${𝛽}_{𝑙}$. label-spring is the spring constant pulling each label toward its target. label-layout: "normal" uses a perpendicular offset target. With label-layout: "dangling-tangent", paired edges still use that perpendicular target, but dangling half-edge labels are offset along the edge direction away from the attached node. With label-layout: "fixed-length", relaxation keeps the label at distance ${𝐿}_{𝑙}$ from the edge point and only rotates it under repulsive forces. label-steps, label-step, label-early-tol, and label-max-delta-scale control the label relaxation iteration.

graph.style measures node and label sizes before layout; those sizes enter repulsion during label relaxation. For labels with measured width and height, a subsequent box-collision pass starts from the relaxed positions. It keeps each position when its box clears node boxes and previously placed label boxes, otherwise searching nearby candidates. This correction may change the distance from the edge point, including in "fixed-length" mode.

Repulsion considers edge layout points, and box correction considers nodes and labels; neither guarantees clearance from complete edge curves or drawing layers such as momentum arrows. Attached path labels may also be positioned again during drawing, as described above.

Qualified aliases

The exported layouts module exposes the same implementations for callers that prefer qualified access; these aliases link back to the canonical top-level entries below.

layouts.layout

Use layout for the shared signature and parameter reference.

layouts.sequence

Use layout-sequence for the shared multi-pass reference.

#let common = options(
  spring: (strength: 8, length: 0.5),
  repulsion: (edge-node: 0.05, dangling: 2),
  solver: (algorithm: "force", steps: 50),
)
#let spacious = options(
  base: common,
  spring: (length: 0.7),
  repulsion: (dangling-centroid: 3),
)
#let g = layout(g, ..spacious)

#let g = graph.parse("digraph partial { a -> b;a -> b;a:s -> b:s; b:s -> c:s; c:s -> d:s; d:s -> a:s }").at(0)
#let south = subgraph.compass(g,"s")
#let gf = layout(layout(g, layout-algo: "force"), layout-algo: "tree", layout-nodes: "fixed",subgraph:south)
#let ga = layout(g, layout-algo: "force")
#let gt = layout(layout(g, layout-algo: "tree",layout-roots: (2)), layout-algo: "anneal", layout-nodes: "fixed",gamma-ee:0.1,gamma-ev:.75,beta:5,length-scale:0.4)
#grid(columns: 3, gutter: 2cm, draw(gf), draw(ga), draw(gt))

#let g = graph.parse("digraph partial { a -> b; b -> c; c -> d; d -> a }").at(0)
#let tree = graph.forests(g).at(0)
#let g = layout(g, layout-algo: "tree", subgraph: tree)
#graph.edges(g).map(edge => edge.pos)