# 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. |
| `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), `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 \
  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).