Appendix I: The vqelab Package

The progressive project, complete. 29 modules, 6,769 lines, one per chapter from 12 to 40, each extending the last. This listing was generated from the files on disk, not from the chapter text.

The inventory

★ Read the right-hand column as the actual index to this book. Every entry is a refusal the corresponding chapter earned by measuring something, and in seven cases by getting it wrong first.

Assembling the package

Each chapter's code/vqelab/ holds that chapter's module. To assemble the whole package:

mkdir -p vqelab
find part-*/chapter-*/code/vqelab -name "*.py" ! -name "__init__.py" -exec cp {} vqelab/ \;
touch vqelab/__init__.py

⚠️ A naming collision was found while writing this appendix. Chapters 28 and 37 both produced vqelab/optimization.py — one about circuit optimization, one about combinatorial optimization. In separate chapter directories they coexist; assembled into one package, one silently overwrites the other.

Chapter 37's module was renamed to combinatorial.py. If you are assembling from an older copy of this book's source, check for the collision before you trust the result — it produces no error, just a missing half.

The checkpoint chain

Every chapter's project-checkpoint.py tests its own module. The full chain, run in order, is 503 tests.

for d in part-*/chapter-*/code; do
    (cd "$d" && [ -f project-checkpoint.py ] && python project-checkpoint.py)
done

Chapter 40's checkpoint additionally verifies the book's scorecard against the chapters that measured it — if a capstone number is not in its source chapter, it fails.

Design principles, in the order they were earned

1. A function that cannot answer the question raises. It does not return a plausible default. total_error (Ch. 36) raises without a measured active-space error, because a default of zero is silently wrong by seven orders of magnitude in the flattering direction.

2. Required arguments have no defaults. quoted_fidelity(dist, statistic, include_dead) (Ch. 30) takes both explicitly, because one chip supported errors from 0.00750 to 0.07205 depending on the choice.

3. Absence is None, not a convenient number. UncertifiedResult.certified_ratio (Ch. 37) returns None. Returning 1.0 would be a lie.

4. A refusal is a distinct answer from a negative result. INSUFFICIENT_SEEDS is not "no difference" (Ch. 37); UNVALIDATED is not "the error is small" (Ch. 36); BLIND is not "the circuits agree" (Ch. 26).

5. The module ships its own caveats as data. secret_key_rate (Ch. 38) returns a caveat field stating that its finite-key model is optimistic — in the return value, not the docstring, where it cannot be skipped.

6. Provenance travels with the number. PriceBook.as_of is required (Ch. 39); an undated price rots without telling you.

7. No scores. audit_claim (Ch. 40) returns failures. A claim that cannot name its baseline is not fractionally correct — it is unevaluable, and averaging that with a pass would be the last instance of the error this book is about.

Using it after the book

The modules are deliberately small and dependency-light. Most are useful on their own:

• claims.py — the eight questions, applicable to any quantitative claim in any field.
• platform.py — cost modelling for any shot-based workload.
• testing.py — the shot-noise floor and the two-error-rates framing.
• benchmarking.py — refusing to quote a number without its statistic.

None of them need a quantum computer.

See also: every chapter from 12 onward; Chapter 40 §40.7 for what the package was actually teaching.