# The circuits course

A course from a first circuit through superposition, entanglement and
interference, the standard algorithms (Deutsch–Jozsa, Bernstein–Vazirani,
Grover, the quantum Fourier transform and phase estimation), noise and its
mitigation, error correction and fault tolerance, to resource estimates.
Each lesson is a short text and an exercise the engine checks. It is written
in English and in Simplified Chinese.

The course is data, read by the engine (`wai_quantum::engine::course`), so it
runs alike in the Studio's **Course** pane, in the desktop app and on the
command line:

```sh runnable
wai-quantum learn                                     # the lessons, and your progress on this machine
wai-quantum learn show bell                           # a lesson: its text, its exercise and the starter
wai-quantum learn start bell my-bell.qasm             # the starter program, to edit
wai-quantum learn check bell my-bell.qasm             # exits 1: the starter does not pass yet
wai-quantum learn hint bell my-bell.qasm              # the next hint, and where the engine says to look
wai-quantum learn why bell my-bell.qasm               # what went wrong, in words
wai-quantum learn --lang zh-CN                        # in Simplified Chinese (or as LANG says)
```

## How an exercise is checked

An exercise states what the program must do as an *intent*, the engine's
own (`docs/verdicts.md`):

- an exact distribution of the measured bits, within a tolerance;
- the same circuit as a program of the exercise's, up to a global phase;
- the same state from |0…0⟩ as one;
- or samples held to a distribution by a stated statistical test.

A generator's exercise is checked in several cases, one for each set of its
inputs (`input uint err;` at err = 0, 1 and 2), each with its own verdict.
The check runs the program with its intent, as a job that asks for a
verdict, under the exercise's noise when it has some, and passes when every
case's intents hold, checked as proof or as evidence. The exercise's
*constraints* are measured on the program too: the gates it may use, how
many of a gate, its T count, the critique's smells it must not have, and the
resource estimate's counts.

**What went wrong?** says, in the reader's language, what the reader's
diagnostics (the line and code where it stopped), the verdict (the outcome
furthest from the distribution, the input on which two circuits part) and
the critique found, with the engine's own words beside them. **Hint** gives
the lesson's hints one at a time, from gentle to specific, with the engine's
pointer toward where to look. In the Studio, a connected model can be asked
for a hint too; it is told not to write the program, and a program in its
answer that passes the exercise is held back. None of these shows the
solution.

Progress (which lessons passed, how many checks and hints) is kept only
where the learner is: in the browser's storage for the Studio, and in
`$WAI_QUANTUM_LEARN`, `$XDG_CONFIG_HOME/wai/quantum-learn.json` or
`~/.config/wai/quantum-learn.json` for the command line. Nothing is sent
anywhere.

## The files

- `course.json`: the course's units in order, each with its lessons, and the
  companion courses ([its schema](../schemas/course.v1.json)).
- `lessons/<id>/exercise.json`: the exercise ([its schema](../schemas/exercise.v1.json)):
  its title, task and hints in each locale; the starter program; the job it
  runs as; its intent, or its cases; its constraints; a solution; and known
  wrong answers, each with why it fails.
- `lessons/<id>/lesson.en.md` and `lesson.zh-CN.md`: the lesson's text.
- `locales/en.json` and `locales/zh-CN.json`: the words a check is answered in.

The engine's tests hold the course to itself: every solution passes its own
exercise by proof or evidence, every known wrong answer fails it for the
reason it states, every starter fails, no hint holds two consecutive lines of
the solution and no lesson its whole body, no answer and no lesson carries a
program the check compares against, every locale has every text, every hint
and every message with the same placeholders, and each lesson's code is the
same in every locale.

To add a lesson, add its directory with the three files, name it in a unit
of `course.json` and in `engine/course.rs`'s list, and give it a solution and
at least one wrong answer; the tests then hold it like the others.

## Translations

The Simplified Chinese texts are machine-assisted translations, marked so in
each file (`translations` in the JSON, a first-line comment in the Markdown),
to be reviewed by a fluent reader before they are advertised.