open-standards/wai/wai-quantum/course

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:

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).
• lessons/<id>/exercise.json: the exercise (its schema): 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.