open-standards/wai/wai-quantum-cli/README.md

wai-quantum

The command line of the WAI quantum stack. It runs OpenQASM programs on this machine, planned and run by the same engine as the quantum job service (wai_quantum::engine), so a job gives the same result here as there. It also sends programs to the service, checks and draws them, verifies receipts, and serves its tools to agents over MCP.

Installing it

Where	How
Any platform with Rust	cargo install wai-quantum-cli (installs the wai-quantum binary)
macOS or Linux, with Homebrew	brew tap transaction-science/tap https://git.transaction.science/Transaction-Science/homebrew-tap then brew install wai-quantum
Windows, with Scoop	scoop bucket add transaction-science https://git.transaction.science/Transaction-Science/scoop-bucket then scoop install wai-quantum
Anywhere	a prebuilt archive from the releases tagged wai-quantum-cli-v…

The prebuilt archives are:

• macOS for Apple silicon and for Intel, with the GPU state vector;
• Linux for x86_64 and arm64, linked statically, so any distribution runs them;
• Windows for x86_64.

Each archive has a .sha256 file beside it (shasum -a 256 -c). A tag wai-quantum-cli-v<version> builds them on the project's own runners (release/, .github/workflows/wai-quantum-cli-release.yml), and writes the Homebrew formula and the Scoop manifest for them.

Running a program

wai-quantum run bell.qasm --shots 1000
wai-quantum run prog.qasm -o "Z0 Z1" -o "0.5 X2" -a 000 -a 111
wai-quantum run prog.qasm --noise depolarizing_2q=0.01 --noise readout=0.02
wai-quantum run prog.qasm --method mps --option max_bond=128
cat prog.qasm | wai-quantum run --json > job.json

A program is OpenQASM 3, or the OpenQASM 2 forms in common use. The reader accepts:

• registers, and a gate applied to a whole register;
• the standard gates;
• ctrl and negctrl modifiers;
• gate definitions;
• measurement and reset anywhere, and if on measured bits;
• generators: integer inputs, consts and for loops, so one program describes a family of circuits.

It refuses while, inv and pow, giving the line of each.

A generator takes its inputs with --input, which every command accepts, and instance writes the circuit out:

cat > ghz.qasm <<'QASM'
OPENQASM 3.0;
input uint n;
qubit[n] q;
h q[0];
for uint i in [0:n-2] { cx q[i], q[i + 1]; }
QASM
wai-quantum run ghz.qasm --input n=40 --shots 100
wai-quantum instance ghz.qasm --input n=3

--method auto (the default) picks the strongest method the program admits:

Method	Takes
exact	dyadic angles; the state vector, the same bits on every machine
statevector	any angle
stabilizer	Clifford circuits, to tens of thousands of qubits
mps	matrix product states
pauli	Pauli dynamics, for expectation values
tensor_network	amplitudes
cutrank	a Clifford circuit with a layer of rotations
density_matrix, trajectories	noise

wai-quantum methods lists each method's reach in a job's memory here (--memory-gb, default 16).

Each result names:

• its method, and why that method was chosen;
• its accuracy class;
• the counts, expectation values or amplitudes asked for;
• its receipt.

Receipts

Every result is signed over the request and the result in their canonical JSON. The service signs with its key; this tool signs with this user's key:

• --key FILE, or $WAI_QUANTUM_KEY, names a file holding the key;
• otherwise the key is $XDG_CONFIG_HOME/wai/quantum-key, or ~/.config/wai/quantum-key. It is made from the system's random source on first use and is readable by its owner only.

wai-quantum key prints the key's did:key. --demo-key signs with the published demo key. Its receipts show only that a result is unaltered, not who signed it.

wai-quantum run prog.qasm --json > job.json
wai-quantum verify job.json              # VALID, and the signer's did:key
wai-quantum submit prog.qasm --json > svc.json
wai-quantum verify svc.json              # the same check on the service's receipt

A receipt shows that this key signed this request and this result, and anyone can rerun the request to compare. It does not say who holds the key.

Checking and drawing

wai-quantum lint prog.qasm               # ok, with its shape, or the line of the first problem
wai-quantum plan prog.qasm               # the method and why, the memory and work, without running
wai-quantum draw prog.qasm --width 80

q0: ─────H─────●──M0──────
               │
q1: ───────────⊕──●───M1──
                  │
q2: ──Rz(π/4)─────⊕───M2──

Critique, equivalence and improvement

wai-quantum critique prog.qasm               # its measures, a modelled fidelity, and its smells with their lines
wai-quantum equivalent a.qasm b.qasm         # the same circuit? exit 0 the same, 1 different, 2 unchecked
wai-quantum improve prog.qasm > better.qasm  # its smells fixed; what changed, and the check, on standard error
wai-quantum shortcuts prog.qasm              # each exact classical route to simulating it, and its cost here

The critique's figures are computed, not estimated: gates by kind, two-qubit gates, depth and two-qubit depth, the T count, and whether the program is a Clifford circuit. Its fidelity is a model at reference error rates, and says so. Its smells are gates that cancel, rotations that merge or do nothing, idle qubits, and qubits acted on but never measured.

equivalent compares two programs up to a global phase. Clifford circuits are compared by their tableaus at any size, and others on every basis state up to 8 qubits. Between 8 and 22 qubits it compares them on random product states, which is evidence, not proof. Beyond that it answers unchecked, with the reason. improve rewrites only statements alone on their lines, and prints a rewrite only when the check does not find it different.

shortcuts lists every exact classical route the engine knows for simulating the program, each with its memory and operations, and names the cheapest. The routes:

• the stabilizer tableau, for Clifford circuits;
• the cut-rank sum, for a Clifford circuit followed by one layer of one-qubit gates;
• an exact matrix product state, at a bond bounded across each cut by the operator Schmidt ranks of the gates that cross it;
• the light cone of a one-qubit expectation value;
• a tensor-network contraction, with --thorough, which also searches longer for a cut-rank order;
• the state vector.

A cheap route proves a design classically easy. None being cheap proves nothing about hardness: other methods, approximate ones above all, may cost far less.

The service

wai-quantum submit sends a job to https://wai.transaction.science/quantum-jobs, or to --service URL (also read from $WAI_QUANTUM_SERVICE). It waits for a long job to finish, then prints the result just as run does.

For agents

wai-quantum mcp is a Model Context Protocol server on standard input and output. Its tools are:

• run_quantum_circuit
• plan_quantum_circuit
• lint_qasm
• critique_qasm
• check_equivalent
• improve_qasm
• classical_shortcuts
• draw_circuit
• verify_quantum_result
• discover_evaluate, discover_submit and discover_archive (the workbench, below)
• history_commit, history_changes, history_blame and history_log (a program's history, below)
• list_methods

A tool that takes a program also takes a generator, with its inputs' values in inputs. Runs happen on this machine and are signed with this user's key; nothing is sent anywhere. In an MCP client's configuration:

{ "mcpServers": { "wai-quantum": { "command": "wai-quantum", "args": ["mcp"] } } }

The workbench

wai-quantum discover searches for cheaper circuits that provably do the same job. A specification (JSON) says:

• what a family of circuits must do: the same unitary as a reference generator (equivalent), or the same state from |0…0⟩ (prepares);
• the sizes to check it at;
• the gates and connectivity a candidate may use;
• what it costs: weights on the engine's measures (depth, two-qubit gates, T count …), summed over the sizes;
• the two measures the archive is laid out on.

Proposers write generators: you, an agent through wai-quantum mcp, or the built-in search. The engine checks each one at every size, never a model's judgement. The archive keeps the cheapest verified generator in every cell of the two axes, with its parent, proposer and note, so different ideas mature side by side.

cd discover                                    # the shipped specifications
wai-quantum discover new ghz-all.json          # the archive, seeded with the reference
wai-quantum discover search ghz-all.json       # the built-in search: blind, seeded edits
wai-quantum discover submit ghz-all.json mine.qasm --note "doubling layers"
wai-quantum discover show ghz-all.json         # what was spent, the best, the front
wai-quantum discover verify ghz-all.json       # every sealed verdict

Each kept generator is sealed with your key. Its receipt binds the specification, the source, its proposer and the engine's verdict at every size. A search reports what it spent: evaluations, seconds and, on macOS, the joules its own process used as the kernel counts them. So the result is a cost per verified improvement, not just a best circuit.

The built-in search is the baseline any proposer should beat. On ghz-all.json, 1,500 blind edits took 4.6 s and 24 J: 139 were verified and 29 kept, and none beat the reference. The doubling tree, which a person or a model writes in a few lines, costs 25 against the reference's 49.

A program's history

wai-quantum history keeps a program's versions in a file beside it (prog.qasm → prog.history.json): who made each change, how, and whose hand each line and gate is in.

wai-quantum history start prog.qasm                    # the program as it is: the first version
wai-quantum history commit prog.qasm --note "a third qubit"
wai-quantum history changes prog.qasm theirs.qasm      # what another program would change, numbered
wai-quantum history propose prog.qasm theirs.qasm --accept 1 --name qwen
wai-quantum history log prog.qasm                      # every version: who, how, when, what it changed
wai-quantum history blame prog.qasm --input n=5        # each line's author, and the gates in each hand
wai-quantum history merge prog.qasm v4 v6              # the file as two lines of work brought together
wai-quantum run prog.qasm --history prog.history.json --json > job.json
wai-quantum verify job.json --history prog.history.json

• Who: each version is made by the person, the assistant (a model), an outside agent, the engine (a rewrite or the blind search), or where the program came from before the history began. --by and --name say which.
• A proposal is reviewed change by change. propose keeps only the changes accepted and writes the result to the program. The version keeps the whole proposal and which changes were taken, so the rejected ones stay readable.
• Whose hand: a line keeps its author until someone changes it. A model's or an agent's line that the person then edits is in both hands. An edit back to an earlier program (an undo) keeps that program's authors. The gates follow their lines, and a generator's are counted at --input.
• The chain: each version's digest covers its parents' digests, its source, who made it and how, and each is sealed with this user's key. history verify checks every digest, seal and review.
• On the receipt: run --history (and submit --history) puts the head's account in the job's request: its digest, and the gates and lines in each hand. The receipt binds it, so a changed count fails the signature. verify --history recomputes the account from the history, and checks that the job ran that version's program.

Through wai-quantum mcp, an agent's edits (history_commit) are recorded as an outside agent's, under the name its client gave when it connected. An agent cannot record a change as the person's.

The research tools

wai-quantum lab … holds the research tools:

• algorithms from the catalogue, OpenQASM and QIR export, and receipts over them;
• error correction at circuit level;
• qLDPC memory;
• fault-tolerant resource estimates and architectures;
• DMRG, TDVP and molecules;
• neural quantum states;
• Gaussian boson sampling;
• optimisation;
• the compute fabric;
• information and transport.

wai-quantum lab help lists them. wai-quantum verify also checks the receipts they sign.

Builds

• Default: submit, over HTTPS.
• --features metal: the single-precision state vector on the GPU (--method statevector_single), on macOS.
• --no-default-features --target wasm32-wasip2: a WASI component without submit. It gives the same output under any WASI runtime.

wai-quantum completions zsh (or bash, fish, elvish, PowerShell) prints shell completion.