1. How to use this book

Why this book exists

You run machines. You have NixOS hosts on a tailnet, systemd units you wrote, containers where they help, a shell history that reads like a small distribution. The Artificer’s Primer ends with you running your own agent daemon; the Hearthwright’s with you running your own hypervisor. Both own a floor of the machine you run on. This book owns the atoms — a different physics entirely, not a lower floor of the same stack.

The Artificer builds the mind. The Hearthwright houses it. The Wyrdwright builds the machine that runs on physics: a quantum computer. Where the other two build the machine you run on, this one builds the machine that runs on quantum mechanics. The two books are parallel tracks, not a third floor. You do not need the Artificer’s daemon or the Hearthwright’s hypervisor to read this; you need linear algebra you can read and a systems background. Part I rebuilds the linear algebra from scratch if it is rusty.

This book ends with you able to reckon with any quantum algorithm: derive it from a single qubit, build it in numpy, and verify it against a real cloud QPU. The destination is not a daemon or a VMM you keep. It is a reckoning.

What is granted, what is thin

Granted, and therefore skipped: Unix, C, Go, NixOS, a systems background, the ability to read a paper. This is not an introduction to programming, not an introduction to quantum mechanics, and not a physics course. There is no wavefunction in a box, no perturbation theory, no hydrogen atom, no “what is a particle.” That last one is the one question physicists spend careers on; this book refuses it. You are here to build a computer, not to settle whether it exists.

Thin, and therefore where the book spends its time:

  • The four postulates of quantum mechanics — state as a unit vector, evolution as a unitary, measurement as a Born-rule operator, composite systems as a tensor product. This is the why behind the circuit model, and the line that keeps this a computation primer, not a physics course.
  • Amplitudes and interference — complex numbers with phase, the Bloch sphere, single-qubit gates as rotations, interference as the mechanism that separates quantum from “faster Bayes.”
  • The circuit model — gates, circuits, the circuit diagram, the vocabulary.
  • The algorithms — Deutsch–Jozsa, Bernstein–Vazirani, Grover, the QFT, Shor, quantum simulation, QAOA/VQE.
  • Fault tolerance — the 5-qubit code, the surface code, the threshold theorem, the most important idea in the field.
  • The models that aren’t gates — measurement-based computing, teleportation, quantum key distribution.

The one codebase in the repository you cloned, and the one contrast:

  • tqp (Python, numpy only) — a from-scratch quantum computer. Literacy and a test fixture. Not a production QPU.
  • The cloud QPU (Rigetti QCS, IBM Quantum, Quantinuum) — the contrast to llama-server on the fleet. You build the algorithm in tqp, then submit the same circuit to a real QPU and verify your interference actually happens. You do not own the floor; you verify against the real machine. That is the one honest lab this book can have.

tqp owns the whole book. The QPU owns nothing you keep.

How the book is built

One codebase, one contract

The finished repository you cloned has this shape:

tqp/
├── py/tqp/                # Python, numpy only (the whole book)
├── labs/chNN/             # one directory per lab chapter
├── book/                  # this book (HonKit sources)
├── docs/superpowers/      # specs and plans (not published)
├── deploy/                # Caddy site block
└── Makefile

tqp is the quantum analogue of tinygpt: Python and numpy only, and it runs the whole book. scipy for sparse matrices is justified in DECISIONS.md; any other dependency is too. Everything a chapter claims about tqp is checked by make check.

The chapter template

Every chapter after this one has the same six sections, in order:

  1. Why this layer exists — what breaks without it, and where it reappears in tqp or the cloud QPU.
  2. Mechanism — the idea, with the maths derived where it is used: amplitudes, the Bloch sphere, the tensor product, the QFT.
  3. Walkthrough — code listings extracted from the reference source.
  4. Exercises — short problems, answers in collapsed blocks.
  5. Lab — a build task that runs in tqp, and where it has one, a circuit submitted to a real cloud QPU.
  6. Further reading — primary sources, cited by title and year.

Labs run, or they are not labs

The labs run in labs/chNN/. tqp runs anywhere Python and numpy run — any host, including the Mac. The cloud QPUs are read-only, cloud-run, and dated; you submit the circuit you built, never warm a dilution refrigerator. A lab skipped because the machine at hand has no numpy install is documented in the lab’s notes — the skip is an honest state, not a pass, and the lab is rerun before the part is called done. A chapter that only prints listings is not done.

Listings cannot drift

Every code listing in a chapter is a copy of a marked region of a real source file that passes its tests. In the source, the region is bracketed by comment markers — # listing:NAME and # end-listing:NAME in Python — and the language’s own comment form in any other tree. In the chapter, the directive <!-- listing: PATH#NAME --> sits on the line immediately before a fenced code block, where PATH is relative to the repository root; the block under it is regenerated, never hand-edited.

tools/listings walks every Markdown file under book/, extracts each named region, and compares it byte-for-byte with the fenced block. make listings fails the build on any drift or on a dead SUMMARY.md link; make sync rewrites stale blocks from source. The consequence: a listing in this book is never a paraphrase, never a version from three refactors ago. When you read a listing, you are reading the code the tests ran against.

The test that names the object: if a chapter claims to run on a real QPU, it is running on tqp, not the QPU. The QPU is read-only and cloud-run; a listing that pretends otherwise is not a listing, it is a lie.

The route

The spine is ordered so that the postulates arrive before the circuit model, the circuit model before the algorithms, the algorithms before fault tolerance, and the fault-tolerant qubit before the models that aren’t gates.

Part I teaches the new intuition. The four postulates of quantum mechanics, amplitudes and the Bloch sphere, superposition and measurement, interference, entanglement, the information measures, density matrices. This is where you learn to think in amplitudes instead of probabilities — the whole new ontology. Read it first.

Part II is the machine, reading-only. Superconducting qubits and trapped ions, coherence and decoherence, the no-cloning and no-teleportation theorems. The substrate you can’t boot. It can wait — the postulates are the object; the substrate can follow.

Part III is the algorithm. The circuit model, Deutsch–Jozsa, Bernstein–Vazirani, Grover, the QFT and Shor, quantum simulation, QAOA/VQE. The interference you built in Part I exploits.

Part IV is fault tolerance. The 5-qubit code, the surface code, the threshold theorem, fault-tolerant computation. The most important idea in the field, and the reason a quantum computer is more than a toy.

Part V is the models that aren’t gates. Measurement-based computing, teleportation, quantum key distribution. The circuit model is not the only way to compute, and quantum information is not only about computing.

Part VI is the limits. BQP vs NP. What quantum can and can’t do. The honest part.

Environment

Install the host toolchain with make deps: on Omarchy it is omarchy pkg add for the Python stack; on Debian/Ubuntu the same via apt; on NixOS, nix develop from flake.nix builds the dev shell with everything pinned. numpy and scipy come from the flake’s dev shell.

Then run make doctor. It prints one line per check and exits non-zero on any failure:

ok   make                     GNU Make 4.4.1
ok   uv                       uv 0.5.x
ok   python                   python 3.14
ok   numpy                    numpy 2.x

Read it line by line. make is the book’s own plumbing. uv manages the Python environment. python is the interpreter. numpy is the only dependency the book runs on; scipy is justified in DECISIONS.md. A FAIL on any line means make deps (or nix develop) did not finish its job on that machine.

Which host plays which role:

Role Host
Run tqp any machine with Python and numpy, including the Mac
Submit a circuit to a QPU any machine with the cloud QPU’s API key
Never a QPU you own any machine — no dilution refrigerator, no cryogenics

The book keeps the same host-command rules your fleet does, and its labs never ask you to break them: machines are addressed by MagicDNS name, never tailnet IP; nothing is ever piped into an interpreter; no lab uses a foreground sleep as a timer — when a lab needs to wait for something it waits on the thing itself, a pipe or a socket, not on a clock.

Lab: take stock

Nothing runs in this chapter. The first circuit that runs is chapter 14’s (the circuit model). What this lab produces is knowledge of your own machines, written down.

On every machine you intend to use with this book, from the repository root:

make doctor

Record, in a file outside the repository (never commit it):

  • which machine is the tqp host — the one whose doctor output is fully ok, where every lab runs;
  • which machine is the QPU host — the one with a cloud QPU API key, where the verification labs run;
  • every machine where numpy is absent or doctor fails, and what the failing line said.

If doctor fails on the machine you meant to use as the tqp host, fix that before chapter 14: every circuit from there on runs.

Further reading

The three documents this book keeps open:

And the paper behind the cloud QPU, read in Part III:

results matching ""

    No results matching ""