Skip to content

Computing Tensors

A ZXW diagram represents a linear map (a tensor). The editor can evaluate that tensor for you: click Compute in the toolbar and the diagram is contracted into a matrix (or a scalar), which is shown in a dialog. The computation runs entirely in your browser via a Rust-compiled WebAssembly engine — there is no server.

  1. Build a diagram. To get a matrix rather than a scalar, add input and output boundary vertices and wire them to the diagram — these declare the open legs of the result.
  2. Click the Compute button (the calculator icon) in the toolbar, or press ⌘/Ctrl+Enter.
  3. A dialog opens showing Contracting and a progress bar. The first run of a session pauses briefly while the WASM engine is fetched and instantiated; subsequent runs are fast.
  4. Closing the dialog mid-computation cancels it (the result is discarded).

Before the contraction starts, the editor runs a structural check of the graph on the main thread. Problems — duplicate vertex ids, dangling edge references, boundary degree, H-box arity, W topology — are caught immediately, with no WASM round-trip: the offending vertices light up on the canvas with a red glow and a short message underneath, and the result dialog shows a red error card instead of a progress bar. Fix the highlighted vertices and recompute. (The only structural error that surfaces mid-contraction from the engine is degree overflow; see Errors.)

The dialog adapts to the shape of the result, starting with a one-line shape summary:

  • Scalar (no boundary vertices, or a closed diagram): the dialog reports Constant and the complex value, e.g. 2 — value 1.0000 + 1.0000i.
  • Matrix (the common case, when there are input/output boundaries): a summary such as 4 × 4 matrix (2 outputs × 2 inputs) followed by a table. With n inputs and m outputs the result is a 2^m × 2^n matrix — rows are outputs, columns are inputs. Row and column headers are computational-basis bit labels in big-endian order (e.g. 00, 01, 10, 11); the top-left corner reads out\in.
  • Large or irregular tensors: a matrix with more than 64 cells is truncated to the first 8 × 8 block with a note; tensors with extra open legs (beyond the boundaries) are shown as a flat list instead of a table.

Each cell is a complex number: pure-real values show just the real part, pure-imaginary values show ±N i, and values near zero are shown as 0.

The row/column ordering follows the boundaries’ order numbers: input with order 0 pins the first column, output with order 0 the first row, and so on (inputs and outputs order independently). See Vertex Types § Boundary order — reorder a boundary in the property panel and recompute to permute the axes.

If a spider or box label fails to parse as a phase, the compute does not fail: the offending vertex is treated as phase 0 and a yellow Warnings (N) panel appears in the dialog. Expand it to see which vertex produced the warning — a single typo never blocks an otherwise-fine computation.

Graph-structure problems abort the computation with a red error card and, where possible, a hint about what to fix. These are caught before the computation starts, by a frontend validator that also highlights the offending vertices on the canvas (red glow + message) so you can see exactly what to fix:

Problem Cause
duplicate node id Two vertices on the canvas share an id (usually a corrupted file).
vertex not found An edge references a vertex id that isn’t on the canvas (usually a sign of a corrupted file).
boundary degree An input/output vertex has more than one neighbour (degree must be 0 or 1).
H-box arity An H box must have exactly two neighbours.
W topology A W node must have exactly 1 input and at least 2 outputs.
degree overflow A vertex has more edges than it has tensor legs (e.g. too many edges on an empty node). Fires mid-contraction from the Rust engine — the only structural error that isn’t pre-checked.
version mismatch / load failed The bundled WASM is stale or missing — rebuild it (pnpm build:wasm) and refresh.

The first five are graph-structure errors you fix by editing the diagram; degree overflow is the one structural error that comes from the engine itself (it can only be detected mid-contraction, on intermediate state); the last is an environment problem (it should not happen on the deployed app). Note that an edge directly connecting two boundary vertices (input → output) is not an error — it is treated as an identity wire.

The toolbar takes a snapshot of the current graph, keeps only the graph-theoretic slice (types, labels, edges — not positions or rotations), and hands it to a Web Worker. The worker lazy-loads the WASM engine, contracts the graph edge-by-edge, and streams back progress and the final tensor. For the full architecture, see the compute-layer dev doc.

Next: Keyboard Shortcuts.