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`](../wai-quantum/src/engine/mod.rs)), 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](https://git.transaction.science/Transaction-Science/open-standards/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/`](release/), `.github/workflows/wai-quantum-cli-release.yml`), and writes the Homebrew formula and the Scoop manifest for them.

## Running a program

```sh
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 `input`s, `const`s 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:

```sh
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.

```sh
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

```sh
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
```

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

## Critique, equivalence and improvement

```sh
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`
- `list_methods`

Runs happen on this machine and are signed with this user's key; nothing is sent anywhere. In an MCP client's configuration:

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

## 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.