# 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

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

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

## WASI (the edge)

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