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

# wai-quantum-qpu

Quantum processors as members of the [wai-quantum](../wai-quantum) fabric: clients for the services that run circuits on them.

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.

`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 | `rz`, `sx`, `x`, `cz` on physical qubits `$p` | radians |
| `prx_circuits` | circuit jobs of native instructions on named qubits, one measurement key per classical bit | `prx`, `cz` | radians |
| `native_turns` | circuit jobs in a native gateset that runs as written; a simulator with device noise models | `gpi`, `gpi2`, `zz` | turns, so every dyadic angle is exact |

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

```rust
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)?;
```

## The command

```text
wai-qpu device  <service>                          # the device: qubits, basis, provenance
wai-qpu probe   <service> [--qubits N] [--shots N] # the bit-order probe
wai-qpu certify <service> [--shots N] [--cases N] [--report FILE] [--yes]
```

`<service>` is `sampler-v2`, `prx-circuits` or `native-turns`, 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 that spends the service's quota, so it runs 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.

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.

## Licence

Apache-2.0.