open-standards/wai/wai-quantum/docs/compiler.md

Compiling with a certificate

wai_quantum::engine::compile takes an OpenQASM program through named passes, checks each pass where it acts, and writes one certificate per compile: what every pass did, how it was checked, and how far the output is from the program. With the basis clifford_t (the gate set it compiles to) every rotation becomes a Clifford+T word within a stated budget ε, so the compiled circuit runs on the bit-exact method.

wai-quantum compile prog.qasm --epsilon 1e-6 > prog.ct.qasm   # passes and budget on standard error
wai-quantum compile prog.qasm --level 2 --json > cert.json     # the sealed certificate
wai-quantum verify cert.json                                   # its signature, as for any job
wai-quantum run prog.qasm --compile 1e-6 --shots 1000          # compiled first, then run bit-exact

The same compile is POST /v1/compile on the job service (sealed with the service's key), the MCP tool compile_qasm on both servers, QuantumEngine.compile in a page and compile in the desktop app. The Studio's compile lens shows each pass with its counts and check and draws the circuit after any pass. A job request with "compile": {"epsilon", "level", "basis"} runs its program compiled, and its result's compiled says how far that is from the program.

Passes

Pass	What it does	How it is checked	Verdict
lower	every gate in h x y z s sdg t tdg cx cz swap rz; a rz at a multiple of π/4 written as the named gates it is	each kind of gate against its decomposition, on its own qubits, by their dense matrices	exact
simplify	the engine's rewrites: a gate and its inverse cancel, rotations merge, Hadamards conjugate, a gate is carried past what it commutes with	each rewrite on the qubits it touches, by tableau or on every basis state	exact
phase_fold	phase gates on the same parity (the same XOR of path variables) merged into the first of them; T gates on one parity become S or vanish	the phase polynomial recomputed: the same gates once the phases are taken out, and the same total angle on every parity	proof when every angle is a multiple of π/4 (the comparison is in whole eighths of a turn), else exact
resynth_1q	each run of one-qubit gates written again when that is cheaper: a run of Clifford+T gates in its Matsumoto–Amano normal form (the fewest T of any word for it), any other run as one rotation	Clifford+T runs multiplied out in exact ring arithmetic; others on their 2×2 matrices	proof or exact
resynth_2q	each block of gates on one pair of qubits written again by the KAK decomposition, at most three CNOTs, when that uses fewer	each block against its replacement on their 4×4 matrices	exact
approximate	every rz off the multiples of π/4 written as a Clifford+T word within its share of the budget (Ross–Selinger)	each word multiplied out in exact arithmetic over Z[1/√2, i], and its distance to the rotation recomputed from the word in fixed point and rounded up	approximate, with the distance
twirl (asked for with a seed)	each cx, cz and swap framed by a seeded random two-qubit Pauli P before it and its image G P G† after it: the same gate, and on average its noise made a Pauli channel	each distinct framed gate (gate and frame) against the bare gate by the equivalence ladder on its two qubits, a tableau each; then the whole circuit by the ladder where it decides	proof
dd (asked for with a sequence, xx or xy4)	in each window where a qubit idles, between its first gate and the end of the circuit, for at least as many layers as the sequence has pulses, the sequence's pulses spread across the window; each qubit's gates keep their order	the sequence against nothing by the ladder (a tableau), and the whole circuit by the ladder where it decides	proof

twirl and dd run after the level's passes, twirl first, only when a request names them ("twirl": SEED, "dd": "xx" or "xy4"; on the command line --twirl SEED and --dd xy4). The same seed gives the same frames on every host. A twirled circuit is the program exactly (up to a global phase): what changes is how a device's noise acts on it, averaged over seeds, which a noiseless simulation cannot show. Decoupling suppresses coherent noise on idle qubits; the engine's noise models act after gates, so in its own simulations the pulses only add gates, and the record says so.

A pass whose check fails is not applied: its record says rejected, and the program goes on as it was. A pass that does not run (the rewrites past 20 000 gates) says skipped and why.

Levels

Level	clifford_t	standard
0	lower, approximate	lower
1 (default)	simplify, lower, simplify, phase_fold, lower, approximate, phase_fold, simplify, lower	simplify, lower, simplify, phase_fold, simplify
2	level 1 with resynth_2q and resynth_1q before the approximation, and resynth_1q after it	level 1 with resynth_2q, lower and resynth_1q

lower comes again before the approximation and last because a rewrite may write h·rz·h as rx. For clifford_t the resynthesis passes weigh rotations first (each costs about 3·log₂(1/ε) T gates), then CNOTs, then T gates; for standard, CNOTs then gates.

Reading ε

ε bounds the operator-norm distance up to a global phase, min_φ ‖U_out − e^{iφ}·U_program‖. It is a budget the compile spends:

• the approximation pass divides what is left of it (after the distances of the passes before) evenly among the rotations it writes: epsilon.each;
• every word comes within its share, measured from the word itself;
• the passes' distances add up by the triangle inequality to epsilon.bound, which is never more than epsilon.budget.

From bound alone, for every input state: the output distribution is within bound of the program's in total variation (so is each outcome's probability), and an observable's expectation within 2·bound·‖O‖. Amplitudes agree up to one global phase.

Up to 8 qubits the whole output is also measured against the whole program on their dense unitaries (whole.distance, computed to about 1e-15), and the compile is refused if that measurement exceeds the bound by more than 1e-9 (the allowance for rounding). Wider programs rest on the composition of the passes' own checks.

A rotation is approximated to an ε between 1e-15 and 0.5; a budget too small for the rotations sharing it is refused with the share it would leave. The T count of a word is close to 3·log₂(1/ε): about 20 at 1e-2, 60 at 1e-6, 100 at 1e-10, 150 at 1e-15, each found in a few milliseconds. On small ε the exhaustive test (every Clifford+T operator with at most 11 T gates) finds the word's T count at the optimum in 21 of 24 cases and one above it in the rest.

The certificate

For h q[0]; rz(0.3) q[0]; cx q[0], q[1]; ry(1.1) q[1]; at --epsilon 1e-4 (level 1), abridged:

{
  "format": "wai.quantum.compile/1",
  "basis": "clifford_t",
  "level": 1,
  "source": { "hash": "3088646d…", "qubits": 2,
              "counts": { "gates": 4, "cnots": 1, "t_count": 0, "rotations": 2, "depth": 4, "…": "…" } },
  "output": { "hash": "65e0c256…",
              "counts": { "gates": 200, "cnots": 1, "t_count": 78, "rotations": 0, "depth": 200, "…": "…" } },
  "epsilon": { "budget": 0.0001, "rotations": 2, "each": 5e-05, "bound": 7.453429548248133e-05 },
  "passes": [
    { "pass": "simplify", "before": { "…": "…" }, "after": { "…": "…" },
      "check": { "how": "rewrites, each checked on the qubits it touches by tableau or on every basis state", "verdict": "exact", "steps": 0 } },
    { "pass": "lower", "…": "…",
      "check": { "how": "each kind of gate against its decomposition, on its own qubits", "verdict": "exact", "checked": 1, "distance": 5.551115123125783e-17 } },
    { "pass": "approximate", "…": "…",
      "check": { "how": "each rotation's Clifford+T word multiplied out in exact ring arithmetic, and its operator-norm distance to the rotation recomputed from the word in fixed point and rounded up",
                 "verdict": "approximate", "rotations": 2, "epsilon_each": 5e-05, "t_count": 78, "distance": 7.453429548248133e-05 } },
    { "pass": "phase_fold", "…": "…",
      "check": { "how": "the phase polynomial recomputed: … in whole eighths of a turn", "verdict": "proof", "merged": 41 } },
    { "…": "…" }
  ],
  "rotations": [
    { "angle": 0.3, "t_count": 38, "distance": 3.77439802702028e-05, "k": 20 },
    { "angle": 1.1, "t_count": 40, "distance": 3.679031521227853e-05, "k": 20 }
  ],
  "whole": { "how": "the dense unitaries of the whole program and the whole output", "distance": 7.123665880156653e-05, "verdict": "approximate" },
  "verdict": "approximate",
  "reading": "The output equals the program up to a global phase to within 7.453429548248133e-5 in the operator norm (the budget was 1e-4). …"
}

Each rotation came within its share (3.8e-5 and 3.7e-5 against 5e-5), the two add to the bound 7.5e-5, and the whole output measured against the whole program is 7.1e-5, inside it. k is the denominator exponent of the operator found: its entries are in Z[ω] over √2^k.

• counts take each gate as lower would write it: cnots counts a swap as three, t_count counts the T gates of the Clifford+T lowering (an rx(π/4) is one), rotations the rz gates left at angles off the multiples of π/4.
• verdict is the weakest of the passes': approximate if anything was approximated, else exact if anything was compared to the rounding of doubles, else proof.
• source.hash is BLAKE3 of the program as read, written out as OpenQASM 3; output.hash BLAKE3 of the output text.
• The compile result is {"ok", "options", "qasm", "certificate"}, sealed in a job's form ({"request", "result"}, the receipt in the result), so wai-quantum verify, POST /v1/verify and engine_verify check it. With "stages": true in the request it also holds stages, the circuit after each pass, in order (sealed with the rest, not part of the certificate).
• A compiled job's result carries compiled: the basis, level, budget, distance (the bound), verdict, counts before and after, and certificate, the BLAKE3 of the certificate's RFC 8785 canonical JSON, which wai-quantum compile prints as its digest.

Determinism

The compile is the same bytes everywhere: the synthesis is integer and fixed-point arithmetic (320 fractional bits), the decompositions use only + − × ÷ √ and the crate's own trigonometric functions, the eigen-solvers are fixed-order Jacobi and QL iterations, and no output depends on map order or a clock. CI compiles one program natively and as a WASI component and compares the sealed bytes, and the browser build's tests compile one request to the native build's pinned digest.

What it does not do

• Programs that measure in the middle, reset after a gate or act on measured bits are refused.
• There is no layout or routing onto a device here; the exact native compile to a processor's basis and coupling map is quantum_toolchain::native, and Clifford routing certificates are quantum_compile.
• A multi-qubit rotation is approximated through its lowering (each rz it lowers to, separately), not synthesised as one.