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.
Running a computation
Section titled “Running a computation”- Build a diagram. To get a matrix rather than a scalar, add
inputandoutputboundary vertices and wire them to the diagram — these declare the open legs of the result. - Click the Compute button (the calculator icon) in the toolbar,
or press
⌘/Ctrl+Enter. - 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.
- Closing the dialog mid-computation cancels it (the result is discarded).
Pre-flight validation
Section titled “Pre-flight validation”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.)
Reading the result
Section titled “Reading the result”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
Constantand the complex value, e.g.2 — value 1.0000 + 1.0000i. - Matrix (the common case, when there are
input/outputboundaries): a summary such as4 × 4 matrix (2 outputs × 2 inputs)followed by a table. Withninputs andmoutputs the result is a2^m × 2^nmatrix — 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 readsout\in. - Large or irregular tensors: a matrix with more than 64 cells is truncated to the first
8 × 8block 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.
Warnings
Section titled “Warnings”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.
Errors
Section titled “Errors”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.
How it works (brief)
Section titled “How it works (brief)”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.