open-standards/wai/quantum-conformance/qasm3/README.md

OpenQASM 3 conformance

OpenQASM 3 programs, each with what the reader (wai_quantum::qasm) must do with it: read it to an exact result, read it to the unitary of a reference program, or refuse it with a given diagnostic code.

Path	What
spec/	The OpenQASM 3 specification's example programs, unchanged (Apache-2.0, as the specification is published). Those that run are held to their results; those that cannot be run exactly are held to the code the reader refuses them with, which names the first construct it cannot hold (an extern, durationof, a while on measured bits with no bound) or the example's own error (arrays.qasm indexes past its array; cphase.qasm and defcal.qasm are fragments that declare no qubits).
lang/	A program for each construct the reader lowers, carries, preserves or refuses, and *.ref.qasm references written without the construct. stdgates.qasm applies every standard gate once; its reference writes each in U and CX alone.
import/	Programs written as the common toolkits export them (OpenQASM 3 and 2: generated gate definitions, physical qubits, if and switch blocks on measured bits, untyped loop variables, qelib1.inc's gates) and textbook algorithms (phase estimation, Bernstein–Vazirani, Grover, teleportation, repeat until success), each with its outcome probabilities derived by hand in its comments; and refuse_*.qasm, a program for each refusal such a program meets, with its code.
manifest.json	Each case: its file, what it covers, and its expectations (the manifest's expectations says what each kind means).
bundle.json	The manifest's cases with each program's text inline, for builds that read no files.

An expectation is one or more of: refused (a code), warns (the codes of every warning and note, sorted), deterministic (every shot's outcome), distribution (exact outcome probabilities, within 1e-9; for a program that branches on what it measured, every branch followed with its probability), expectations (exact Pauli expectation values), equivalent (the reference's unitary, up to a global phase, within 1e-9), exact (the bit-exact circuit takes it, or refuses it with a code), outputs, timing and calibrations.

Native

cd wai/wai-quantum
cargo test --release --features full --test qasm3_conformance

Two tests: every case against its expectations, and the bundle held equal to the files. After changing a program or the manifest, write the bundle:

WAI_QASM3_BUNDLE_WRITE=1 cargo test --release --features full --test qasm3_conformance the_bundle_is_the_corpus

WASI (the edge)

CARGO_TARGET_WASM32_WASIP2_RUNNER='wasmtime run -W nan-canonicalization=y -W relaxed-simd-deterministic=y' \
  cargo test --target wasm32-wasip2 --features full --test qasm3_conformance

The cases come from the bundle compiled into the test.

Browser

wai-web's wasm32 tests (--features quantum_engine, under wasm-bindgen-test-runner) read every case of the bundle through the page's engine: each refusal's code, each program's warnings, and each program with one outcome run to it.

CI: wai-quantum-lang.yml (native and wasm32-wasip2) and wai-web-wasm.yml (the browser build).