# wai-quantum-qpu

Quantum processors as members of the [wai-quantum](../wai-quantum) fabric: clients for the services that run circuits on them, and the person's own providers, brought without a client written for them ([Bring your own quantum](bring-your-own-quantum.md)).

For every circuit, a `QpuSampler`:

1. reads the device's native gates and connectivity from the service;
2. compiles the circuit to them exactly, with `wai_quantum::quantum_toolchain::native`, and checks the program against the circuit by simulation before anything is sent;
3. submits it, waits for the job, and reads the counts back onto the circuit's qubits: logical qubit `i` is measured into classical bit `i`, which is bit `i` of the counts' index, whatever physical qubit it ended on.

A queue can outlast any wait, so `job::start` records a job before it is sent (`ledger`), and `job::check`, `job::follow` and `job::cancel` come back to it by its record, from any process. Running out of patience leaves the job where it is. `job::run` keeps no record, so it cancels what does not finish within its bound.

`QpuSampler::member` certifies the device statistically against the exact distribution of every circuit of a corpus, as the fabric certifies any sampler. Its certificates carry the device's provenance: silicon for a processor, a simulator for a service's simulator. Placement ranks a simulator after silicon.

## Services

| Module | Protocol | Native gates | Angles on the wire |
|---|---|---|---|
| `sampler_v2` | Sampler V2 jobs: an IAM bearer token, one OpenQASM 3 circuit per job, placed by the backend's published calibration (its properties) and refused when it ran under another; on a free plan free, with what is left of its limit, and each job's charge sealed in quantum seconds | `rz`, `sx`, `x`, `cz` on physical qubits `$p`; with the setting `basis=rzsxxczrxrzz`, also `rx` and `rzz` where the backend lists them (each angle between two qubits one `rzz`) | radians |
| `prx_circuits` | circuit jobs of native instructions on named qubits, one measurement key per classical bit, each job pinned to the calibration set it was compiled against and placed by that set's quality metrics; on a star device, `move` into and out of its computational resonator | `prx`, `cz`, `move` | radians |
| `native_turns` | circuit jobs in a native gateset that runs as written: each backend read from the service (its status, its gates, its characterization's pairs), a simulator with device noise models and a seed; results read from shot records (their leakage flags sealed), the service's counts or its probabilities; cancel, and an estimate held to the rate card | `gpi`, `gpi2`, and `zz` or `ms` as the backend (or the noise model's device) runs | turns, so every dyadic angle is exact |
| `cloud_tasks` | quantum tasks on your own cloud account: OpenQASM 3, a verbatim box on a processor, requests signed with your keys, results in your own bucket | a processor's `prx` `cz`, `gpi` `gpi2` `zz`, or `prx` `xx` `rz` (each `cz` as one `xx(pi/2)`); `rz` `v` `x` `cz` on a simulator | multiples of pi, written exactly |

Each module's `BASE` constant is the endpoint it is written against. Each client is configured from the environment (`from_env`) or in code. Keys and tokens are held in `Secret`, which never prints:

| Module | Variables |
|---|---|
| `sampler_v2` | `WAI_QPU_SAMPLER_API_KEY`, `WAI_QPU_SAMPLER_CRN`, `WAI_QPU_SAMPLER_BACKEND` |
| `prx_circuits` | `WAI_QPU_PRX_TOKEN`, `WAI_QPU_PRX_QC` |
| `native_turns` | `WAI_QPU_TURNS_KEY`, `WAI_QPU_TURNS_BACKEND` (default `simulator`), `WAI_QPU_TURNS_NOISE` |
| `cloud_tasks` | the account's usual key variables, `WAI_QPU_TASKS_REGION`, `WAI_QPU_TASKS_DEVICE`, `WAI_QPU_TASKS_BUCKET`, `WAI_QPU_TASKS_PREFIX` (default `wai-quantum`), `WAI_QPU_TASKS_BASIS` (a simulator only: compile to a processor's basis) |

```rust compile crate=wai-quantum-qpu
use wai_quantum_qpu::{QpuSampler, check_probe, probe_circuit, transport::Curl};
use wai_quantum_qpu::native_turns::NativeTurns;

let sampler = QpuSampler::new(NativeTurns::from_env(Curl::new(120))?)?;
// The first job on any service: an X on qubit 0, whose counts must land on index 1.
let (counts, job) = sampler.run(&probe_circuit(3), 1000)?;
check_probe(&counts, 0.95)?;
```

## Bring your own quantum

A device needs no client written for it here: it speaks the [open provider protocol](../extensions/quantum-providers.md), `wai.quantum.provider/1`, over HTTP or as a local process, and the person lists it in their registry. [Bring your own quantum](bring-your-own-quantum.md) is the guide.

| Module | What it is |
|---|---|
| `open_provider` | the protocol's client: `Http` (through `curl`; a credential only over https or to this machine) and `Process` (one JSON line each way; the credential in the program's environment, never its command line), and `OpenProvider`, a `Provider` over either |
| `reference` | the reference provider: the protocol around this crate's exact simulator, served over HTTP or standard input and output, taking energy-landscape jobs of both versions on the extension's reference too (`--no-landscape` for none, `--landscape-protocol 1` or `2` for one version alone, `--qubits 0` for those alone); the tests run against it, and it is the template to copy |
| `conformance` | the checker, and its vectors in [`conformance/provider-v1.json`](conformance/provider-v1.json) with the reference's counts pinned |
| `registry` | the person's list of providers (`~/.config/wai/quantum-providers.json`, holding no credential), and the credential stores: the keychain (the system `security` tool on macOS, `secret-tool` on Linux), else a file only its owner reads, labelled so |
| `job` | the dry run (the exact compile, the check by simulation, the provider's estimate and billing unit), the refusal of a run that is not free until it is confirmed, and the seal of its counts by the engine (`wai_quantum::engine::provider`), labelled `measured` from a processor and `simulated` from a simulator, with the counts' source and the `execution` each client states from the very request it sends |
| `landscape` | an energy-landscape job (`wai.quantum.landscape/1`, or `wai.quantum.landscape/2` where the request names it) on a provider whose description offers them, in a version it lists ([the protocol's §11](../extensions/quantum-providers.md#11-energy-landscape-jobs)): the job's operations and memory counted as the extension counts them before anything is asked, the provider's estimate held to that count, a run that is not free refused until it is confirmed, and the answer checked by the extension's §5.4, as the job's version reads it, and by its program before it is sealed, naming the provider, its job and its cost; a job of a version the device does not list is refused before anything is sent |

`Provider` gains `details` (the protocol, the calibration snapshot, the billing), `device_target` (the device's errors in its service's own form, read as a target), `estimate`, a seeded `submit_seeded` and `cancel`, each with a default, so a client that has none keeps working: its cost is then unknown, and a run on it is never taken to be free.

When a client reads its device's errors itself (`device_target`: `prx_circuits` reads the quality metrics its service publishes for the calibration set the device is under), or a provider's `describe` states its calibration (errors per qubit or per pair) and is read as one, the program is placed on the qubits and routes most likely to succeed (`wai_quantum::engine::targets::layout`). It is still in the device's own gates and checked against the circuit before it is sent. The plan and the receipt's `compiled.placement` say how it was placed, with the target's hash and what it was read from. A device whose service publishes no errors keeps the compiler's own layout, and the placement says why.

`prx_circuits` sends each job pinned to the calibration set whose architecture it compiled against (`calibration_set_id`), so a recalibration between the read and the run is either refused by the service, with an error that says so, or run as planned; it sends the service's modes as it wants them (dynamical decoupling disabled, heralding none, move validation strict, move frame tracking full); the result names the calibration set the service says it compiled the job against, and one other than the pin is refused, by the client that sent it and by any later process that collects the job from its record; and it cancels a job (`POST /jobs/{id}/cancel`).

The command line carries it all: `wai-quantum providers add|list|remove|describe|test|free|reference` and `wai-quantum run --provider NAME [--dry-run] [--yes]` ([its README](../wai-quantum-cli/README.md)).

## The command

```text norun=usage
wai-qpu device  <service>                          # the device: qubits, basis, provenance
wai-qpu probe   <service> [--qubits N] [--shots N] [--yes] # the bit-order probe
wai-qpu certify <service> [--shots N] [--cases N] [--report FILE] [--yes]
wai-qpu reference --stdio | --http ADDR [device options]   # the reference provider
```

`<service>` is `sampler-v2`, `prx-circuits`, `native-turns` or `cloud-tasks`, configured from its variables above. A certification runs every circuit of the corpus in both gatesets as a job. On a device whose provenance is silicon, or one the service does not state is free, a job spends the service's quota or the person's money, so a probe and a certification there run only with `--yes`. `--report` writes each certificate with its hash, and every job, as JSON.

## Transport

`transport::Curl` runs `curl` as a program, so the crate carries no TLS stack. Headers, keys and tokens included, go in a curl configuration file that only this user can read, removed when the request ends. The body goes on curl's standard input. Nothing secret appears on a command line. `transport::Scripted` answers from a function, for tests.

## What is checked here, and what only a service can check

The tests run each client against a service that follows that provider's published contract. The fake parses the submitted program in the provider's own format, runs it on the crate's simulator, and answers in the provider's result shape and bit order. A client whose request, units or bit order departs from the contract reads back the wrong distribution, and the tests fail. A probe test shows that a service using the other bit order is caught.

A real service settles its own conventions. The first job on each should be `probe_circuit`, checked with `check_probe`, before any other result is trusted.

`prx_circuits` has a second fake of its own (`tests/prx_circuits.rs`), built from the service's published request and response models and stricter than the service: a member the models do not name, a mode outside its values, a calibration set id that is not a UUID, a gate on a locus its calibration set does not list (a `cz` in either order, a `move` the qubit first) are each refused; a job pinned to a calibration set the service does not run is taken and fails at compilation (`Calibration set not found`), and a cancel of a job that has ended is refused `403 illegal_job_status`, as the service's mock answered them on 2026-11-12. Against it: a recalibration between the read and the submission, the job pinned and compiled against the set it was planned on; a service that says it compiled against another, refused; a retired set, failing the job; a job past its wait cancelled; the quality metrics placing a Bell pair on the best pair and readouts; `providers test`; and the token read from the credential store and sent as a bearer over curl. On the service's mock quantum computer (2026-11-12), the pinned request and its modes were taken, the job's record named the pinned set as the one it compiled against, a cancel stopped a running job, and the calibration's quality metrics read as a target; no processor has run a job of it.

Two device shapes are checked against fakes only, as every client is. A processor of `prx`, `xx` and `rz` (`cloud_tasks`): its fake reads the service's `prx(θ, φ)` and `xx(θ) = exp(−iθ/2·X⊗X)` and refuses an angle outside the ranges such devices take (`xx` 0 to π/2, `prx` 0 to π), so each `cz` reaches it as one `xx(pi/2)`. A star device (`prx_circuits`): five qubits round a computational resonator, one moving into it; its fake holds the resonator to its turns and runs each `move` as the exchange with a phase the device leaves undefined, which only the move back cancels. Whether a real service of either shape takes these programs as written is settled by its probe.

The open protocol is tested end to end (`tests/providers.rs`): every operation against the reference provider as a process and over HTTP; the conformance vectors over both, in each basis, and on the reference as an `xx` device and as a star (`--star`: its qubits round one resonator, `describe`'s `resonators` and `moves`); the reference's pinned counts; the registry with its credential in a file only its owner reads (and, on macOS, the keychain in a keychain file made for the test); a run that is not free refused until it is confirmed; receipts that verify with the engine's verifier; and no credential in anything a run returns. Nothing there spends money: the priced runs are the reference's.

The work runs at the service, so every run is unmetered here. An energy figure the service reports, such as a per-job estimate, is kept in the job record as the service's figure (`JobRecord::service_kwh`). It is never recorded as a measurement.

Every circuit a certification runs is a job on the service, and spends that service's quota.

## Versions

The open provider protocol is `wai.quantum.provider/1` ([the extension](../extensions/quantum-providers.md), section 10); its messages, program and answers are a JSON Schema, [`schemas/provider.v1.json`](schemas/provider.v1.json), which every message the client sends and every answer the reference provider gives is held to. What is stable in this crate and the protocol, and how a change is announced: [the policy](https://git.transaction.science/Transaction-Science/open-standards/src/branch/main/wai/wai-quantum/VERSIONING.md); what is deprecated: [the deprecations](https://git.transaction.science/Transaction-Science/open-standards/src/branch/main/wai/wai-quantum/DEPRECATIONS.md).

## Licence

Apache-2.0.