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.

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

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

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.