94fabb574d
Feature 12 of the co-design report: a convergence monitor.
- engine::converge:
- history: for each version the person made after a model proposed,
its structural distance from the proposals in its line of work (the
whole proposal) and the model's share of its gates; converging when
most of the program is the model's or the last versions come closer
each time, with why; versions noted "organic exploration" (the
assistant-off probes) set beside the rest;
- cohort: the Vendi score over 1 - distance (Jacobi eigenvalues), each
program's distance to the centroid of the gate-token bags, the medoid
and the outlier, and with times the score in windows and a narrowing;
- call for hosts. novelty::bag is shared.
- The command line: converge history | cohort (a file's time from its
history, else the file's).
- MCP: converge_cohort and converge_history.
- The Studio: "Your own way" under Versions, and "Explore on my own for a
while": the assistant only asks and offers no program, Explore and Ask
the model wait, the person's versions are noted; End lets the model
propose again.
- Bindings: engine_converge in the page, converge in the desktop app.
- CI: wai-web's native engine tests count 13.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
334 lines
22 KiB
Markdown
334 lines
22 KiB
Markdown
# 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. Wider than that, it tries to rewrite one program followed by the other's inverse to nothing, each rewrite checked on the qubits it touches (`rewrites`, below): when that works it is a proof at any width, with any gates. Otherwise, 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)
|
||
- `novelty_qasm` and `discover_novelty` (what is new, below)
|
||
- `rewrite_qasm` (rewrites, below)
|
||
- `converge_cohort` and `converge_history` (convergence, below)
|
||
- `taste_rank` and `taste_next` (your taste, 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:
|
||
|
||
```json
|
||
{ "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.
|
||
|
||
```sh
|
||
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.
|
||
|
||
```sh
|
||
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 person's rules for proposals
|
||
|
||
A proposal (a model's, an agent's, an engine rewrite) must keep the person's rules, and the engine checks it change by change:
|
||
|
||
- **Held blocks**, marked in the program itself: the lines from a `// @lock` comment to the next `// @unlock`, the markers included.
|
||
- **The other rules**, in `prog.locks.json` beside the program:
|
||
|
||
```json
|
||
{ "gates": ["h", "cx", "rz"], "qubits": true, "avoid_gates": ["t"], "avoid_text": ["reset"], "region": [4, 9] }
|
||
```
|
||
|
||
- `gates`: the only gates a change may add;
|
||
- `qubits`: hold the qubit declarations;
|
||
- `avoid_gates` and `avoid_text`: what no change may add;
|
||
- `region`: the lines a rewrite must keep to.
|
||
|
||
```sh
|
||
wai-quantum locks check prog.qasm theirs.qasm # each change, and the rules it breaks (exit 1 if any)
|
||
wai-quantum locks brief prog.qasm # the rules as a model is told them
|
||
```
|
||
|
||
What the person types is theirs to change; the rules bind proposals. Only what a change adds is judged, so a gate the program already uses is never a proposal's breach.
|
||
|
||
- **The history:** `history changes` names each change's breaches. `history propose` refuses to accept a change that breaks a rule, `--accept all` takes only the changes the rules allow, and the version records the rest as blocked.
|
||
- **For agents:** through `wai-quantum mcp`, `history_commit` refuses an agent's edit that breaks a rule, with the rule, and `history_changes` shows each change's breaches and the rules as sentences.
|
||
|
||
## What is new
|
||
|
||
`wai-quantum novelty` says what is new in a program, and what is a known construction found again:
|
||
|
||
```sh
|
||
wai-quantum novelty mine.qasm # its nearest known construction, and what it is found to be
|
||
wai-quantum novelty mine.qasm --against draft.qasm # compared with your own programs too
|
||
wai-quantum novelty gen.qasm --input n=6 --reference ref.qasm --weigh depth,two_qubit
|
||
wai-quantum discover novelty ghz-all.json e12 # one entry of an archive, against the others
|
||
```
|
||
|
||
- **The known constructions** are GHZ by a chain of CNOTs, by doubling and by fan-out from one qubit, the uniform superposition, and the quantum Fourier transform, each built at the program's width (to 12 qubits). `--against` adds programs to compare with; `discover novelty` compares an entry with the archive's other elites.
|
||
- **The distance** is structural: each gate a token (its kind, and its qubits relative to its first), two programs compared as multisets of those tokens and of consecutive pairs of them. It is 0 when they are built alike and 1 when they share nothing. It says nothing about what a program does.
|
||
- **Found again:** when the engine proves a program does what a known construction does (the same state from |0…0⟩ for a preparation, the same circuit otherwise), it names it. Built unlike it (a distance of 0.5 or more), it is **a different route to a known result**, the case worth a second look. A program that is itself one known construction is not a different route to another.
|
||
- **Strengths not asked for:** with `--reference`, the measures it beats the reference on that `--weigh` does not name.
|
||
- **An aberration:** in the workbench, a candidate that breaks only the specification's rules (its gates, its connectivity) and would be verified without them. It is never kept. `discover eval` and `discover submit` say what it would cost and which rule it breaks, as a reason to revise the rule.
|
||
|
||
A high distance is a reason to look, not a claim that nobody has built it: the engine knows the constructions above and the programs it is given, not the literature.
|
||
|
||
## Rewrites
|
||
|
||
`wai-quantum rewrite` makes an optimisation one checked step at a time:
|
||
|
||
```sh
|
||
wai-quantum rewrite options prog.qasm # every rewrite it admits, each with its id, in words
|
||
wai-quantum rewrite apply prog.qasm merge:6,7 # the program with that one made
|
||
wai-quantum rewrite simplify prog.qasm # every rewrite to a fixed point: the steps, then the result
|
||
wai-quantum rewrite explain prog.qasm theirs.qasm # how one becomes the other, as a chain
|
||
```
|
||
|
||
- **The rules propose; the engine decides.** A gate and its inverse cancel; two rotations about one axis merge, and `t`, `s` and `z` add up; a gate between two Hadamards becomes its conjugate (`h x h` is `z`, and `cx` between two `h` on its target is `cz`); a gate that does nothing is dropped; a gate is carried past gates it commutes with to cancel or merge with its partner; and two gates that commute trade places.
|
||
- **Each rewrite is checked** on just the qubits it touches, by their tableaus or on every basis state. Replacing a few gates by others with the same unitary keeps the whole circuit's, so a chain of rewrites proves two programs equal at any width and with any gates.
|
||
- **Each option is an edit to the program's own lines.** A merge writes `rz(0.25 + 0.5)`, comments and the other lines stay as they are, and the result is read back and compared gate for gate before it is offered. A generator is rewritten as the circuit it writes out.
|
||
- **`explain`** simplifies both programs and compares what is left. The steps are a readable account of why an optimisation is the same circuit.
|
||
|
||
## Convergence
|
||
|
||
`wai-quantum converge` says whether your designs are converging on a model's, and how diverse a set of designs is:
|
||
|
||
```sh
|
||
wai-quantum converge history prog.qasm # along its history: how far your versions are from a model's proposals
|
||
wai-quantum converge cohort designs/*.qasm --input n=6 # the Vendi score, the centroid, and the score over time
|
||
```
|
||
|
||
- **Along a history:** for each version you made after a model proposed, its structural distance from the proposals in its line of work, and the share of its gates in a model's hand. It is converging when most of the program is the model's, or when your last versions come closer to its proposals each time.
|
||
- **On your own:** versions noted `organic exploration` (the Studio's "Explore on my own") are the assistant-off probes. Their distance from the proposals is set beside the rest.
|
||
- **A cohort:** programs for one task, a group's or yours over months. The Vendi score is the effective number of distinct designs, from 1 when they are all built alike to the number of programs. Each program's distance to the centroid is given, with the medoid and the one built least like the rest. With times (a history's last version, or the file's), the score is taken in windows, and a narrowing is named.
|
||
|
||
Everything is read from the files given, and nothing is sent anywhere.
|
||
|
||
## Your taste
|
||
|
||
`wai-quantum taste` learns your taste in circuits from your own choices:
|
||
|
||
```sh
|
||
wai-quantum taste choose mine.qasm theirs.qasm --part clarity # you prefer mine: recorded once the engine proves them equal
|
||
wai-quantum taste show # what it has learned, and how many of your choices it predicts
|
||
wai-quantum taste rank a.qasm b.qasm c.qasm --novelty 0.5 # ranked by your taste, each with its typicality
|
||
wai-quantum taste next --spec ghz-all.json # the pair of an archive's elites it is least sure of
|
||
```
|
||
|
||
- **Only between equals.** A choice is recorded only when the engine proves the two programs the same circuit (or, with `--task prepares`, the same state from |0…0⟩). So a choice is about taste, never about correctness.
|
||
- **Decomposed.** `--part` says what a choice was about: economy, clarity, insight, precision or utility. Each part is learned from its own choices, and a ranking says where a part, or the cost, puts another program first.
|
||
- **Plural and personal.** `--profile NAME` keeps several (for teaching, for one device). They live in `quantum-taste.json` beside your key (`--taste FILE` for another), and nothing pools them.
|
||
- **Typicality is shown, never learned.** Each program in a ranking shows how near the known constructions it is built. The profile never learns it. `--novelty` (−1 to 1) blends the order by your taste with the order by novelty: 0 is your taste alone, and either end orders by novelty alone.
|
||
- **Measured.** `show` says how many of your choices it predicts, each from the ones before it and each held out from the rest. `rank` says whether its first three are built more alike than the first three by cost.
|
||
|
||
The model is a Bradley–Terry logistic over differences of what the engine measures: the gate counts and depths, the modelled error, and the program's text (its statements, its kinds of gate, how much repeats, its comments). It is fitted with a ridge penalty, so the same choices give the same weights everywhere. Through `wai-quantum mcp` an agent can rank programs by your profile (`taste_rank`) and ask which pair to show you next (`taste_next`), but it cannot record a choice: only you choose.
|
||
|
||
## 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.
|