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

# WAI Quantum documentation

Every command and code snippet on these pages runs in CI, and its output is
checked against the real output or its receipt (below). A page that cannot
run one says why.

## Start here

- **Learn:** [the circuits course](../course/README.md), from a first circuit
  through superposition, entanglement, interference, the standard algorithms,
  noise and its mitigation, error correction and fault tolerance to resource
  estimates. Each exercise is checked by the engine. It runs in the Studio and
  on the command line (`wai-quantum learn`), in English and in Simplified
  Chinese. Beside it, *Quantum, reconsidered*, a seven-module course on
  interference and learning, runs in the browser at
  <https://wai.transaction.science/quantum-learn>.
- **The command line:** [`wai-quantum`](../../wai-quantum-cli/README.md):
  run, check, draw, compile and estimate programs, verify receipts, and serve
  the tools to agents.
- **In the browser and on the desktop:** [the Studio](../../quantum-studio/README.md)
  and [the desktop app](../../wai-quantum-desktop/README.md).
- **From Python:** [`wai_quantum`](../../wai-quantum-py/README.md).

## The engine and its reference pages

- [The crate](../README.md): the simulator, the operational layer, the
  research tools and the receipts.
- [Verdicts](verdicts.md): how far the engine checked an answer, the intents
  and the repairs.
- [The compiler](compiler.md): the passes, the ε budget and the certificate.
- [Resource estimates](estimate.md): every number of an estimate and what it
  assumes.
- [Published architectures, re-estimated](published-architectures.md): published
  resource estimates through these estimators, each delta and why.
- [The reader's diagnostics](qasm-diagnostics.md) and
  [what it does with each construct](qasm-feature-matrix.md).
- [The job layer's refusal codes](job-refusals.md).
- [Other formats](formats.md): QIR under its profiles and jeff, read and
  written, each conversion checked.
- [Error correction and mitigation](qec.md): codes with their certified
  distances, the decoders, thresholds, and mitigation in a job.
- [Pulse and dynamics](pulse.md): pulse programs read into schedules on
  frames, integrated under a master equation with their error bounded and
  stated, the same bits everywhere, and what their receipts bind.
- [Energy-landscape jobs](landscape.md): an energy over variables of three
  states, run on a classical emulator of the settling model, every arrangement
  checked where it is small, the joules priced, and classical methods on the same
  instance at the same budget.
- [Energy to solution](landscape-energy-to-solution.md): that emulator against
  tuned simulated annealing, parallel tempering, tabu search and an exact
  solver, as the cost of a 99 in 100 chance of the lowest energy; operations
  counted, the host's seconds and joules measured, the priced joules apart.
- [Stage 0, the sampler against the exact law](landscape-stage0.md): that
  emulator's sampling kernel held to the Boltzmann law over every one of 3¹⁰ to
  3¹² states, with thresholds registered before the runs; an ideal sampler must
  pass and wrong kernels must fail, on the CPU and on the GPU members.
- [Variational algorithms and the algorithm library](variational.md): a
  job's parameters, exact gradients with their rounding bound, the
  optimisers, the variational eigensolver, QAOA, and programs for phase and
  amplitude estimation, an adder and QSVT, each checked against a reference.

## Other surfaces

- [The job service](../../wai-quantum-service/README.md), over HTTP and MCP:
  [running it yourself](../../wai-quantum-service/docs/self-host.md), as
  [a batch scheduler's resource](../../wai-quantum-service/docs/scheduler.md),
  and [what a result's provenance records](../../wai-quantum-service/docs/provenance.md).
- Views inside agent hosts: [the engine inside them](../../wai-quantum-views/README.md).
- The answer view layer, a draft extension: [its specification](../../extensions/quantum-answers.md).
- [Editors](../../tools/wai-quantum-editor/README.md): the language server,
  the debugger and the formatter.
- [Your own hardware](../../wai-quantum-qpu/bring-your-own-quantum.md) and
  [the provider crate](../../wai-quantum-qpu/README.md).
- [The workbench's specifications](../../wai-quantum-cli/discover/README.md).
- For agents: [the Agent Skill](../../wai-quantum-cli/skills/wai-quantum/SKILL.md)
  and [`llms.txt`](../../wai-quantum-cli/docs/llms.txt), generated from the
  servers' own tool lists.

## Changes between versions

- The changelog: [`wai/CHANGELOG.md`](../../CHANGELOG.md).
- What is stable, for how long, and how a change is announced, the schemas
  of every document included: [the version policy](../VERSIONING.md).
- Each item deprecated, the version that deprecated it and its replacement:
  [the deprecations page](../DEPRECATIONS.md).

## In other languages

Simplified Chinese: [this index](README.zh-CN.md), the
[command line's README](../../wai-quantum-cli/README.zh-CN.md), the
[Studio's](../../quantum-studio/README.zh-CN.md), the
[Python package's](../../wai-quantum-py/README.zh-CN.md), the
[crate's](../README.zh-CN.md), the course, the Studio's interface, and the
command line's own words (`--lang zh-CN`, or as `LANG` says). Each is a
machine-assisted translation, marked so, to be reviewed by a fluent reader.

## How these pages are checked

`wai/tools/quantum-docs/check_docs.py` reads every page named in its
`docs.json`. It runs each shell block marked `runnable` in a scratch
directory with the command line built from this checkout, runs the Python
blocks against the package and builds the Rust ones, and holds each shown
output to the real one. It verifies every receipt a block writes with
`wai-quantum verify`. A block that cannot run here (one that needs an
account, a server that does not return, or data the repository does not
hold) says so in its info string, and its commands must still name commands
and flags that exist. Every `wai-quantum …` in the prose must name a real
command, every relative link must reach a file, and every dependency a page
shows must be one this repository's version satisfies. A translation must
hold the same code as its English page. `.github/workflows/wai-quantum-docs.yml`
runs it, with the course's tests and the locale checks.