b894f1bbc5
The course's documents join the version contract. The course as kept and as served (wai.quantum.course/1) and each exercise (wai.quantum.exercise/1) move from course/schema/ to the crate's schemas/, named and versioned as the rest; a check, a lesson as served and a hint are wai.quantum.course-check/1, and a check now names its engine beside its schema; the command line's progress file is wai.quantum.learn-progress/1. The engine's test holds the course, every exercise, every lesson in each locale and a check and hint of some to them; the learn test holds the progress file; the contract workflow requires both, and the eval and lease tests, by name, and runs when the answer and eval sets its tests read change. The docs runner reads every page the branches added: the error-correction page, the version policy, the deprecations page, the service's self-hosting, scheduler and provenance pages, and the views' README. Each block the other branches wrote either runs or says why it cannot (a sweep fixture added), and the job service it starts keeps its store in its scratch. The crate's README names wai-quantum 0.7. The Chinese READMEs hold the English pages' code again: the sections for error correction, sets and sweeps, the service's dry runs, the scheduler, scoring a model, the answer layer, views and versions are translated, and the compile pages name the gate set basis. The command line's Chinese words cover task, qec, eval and version, and submit as it reads now. The documentation index links the policy, the deprecations, the error-correction page and the service's pages in both languages. The policy lists every schema file and says the answer layer is a draft outside its promise. The 0.7.0 heading names what the four branches bring. The views page bundles the Studio components that now read their words through the locale module; build-views.mjs gives it the English words alone, so no other language's words reach a host. The result parts the Studio and the views share read their words through it too, so the Studio's result pane stays translated, its English unchanged. Co-Authored-By: Claude Opus 5.5 <[email protected]>
86 lines
4.5 KiB
Markdown
86 lines
4.5 KiB
Markdown
# 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.
|