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

wai-quantum-qpu

Quantum processors as members of the 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).

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

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, wai.quantum.provider/1, over HTTP or as a local process, and the person lists it in their registry. Bring your own quantum 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; the tests run against it, and it is the template to copy
conformance	the checker, and its vectors in 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

Provider gains details (the protocol, the calibration snapshot, the billing), 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 provider's describe states its calibration (errors per qubit or per pair), the description is read as a device target, and 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. A description that states no errors keeps the compiler's own layout.

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

The command

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]
wai-qpu reference --stdio | --http ADDR [device options]   # the reference provider

<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 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; 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, section 10); its messages, program and answers are a JSON Schema, 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; what is deprecated: the deprecations.

Licence

Apache-2.0.