From 18f5bef127e62099a8d5c2e27e8971a6e779b969 Mon Sep 17 00:00:00 2001 From: saymrwulf Date: Wed, 15 Apr 2026 19:25:39 +0200 Subject: [PATCH] Add foolproof course navigation: central entry point and inter-notebook links MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Create notebooks/00_START_HERE.ipynb as the single entry point with plan descriptions, audience guidance, and links to all 4 plans - Add navigation footer cells to all 11 content notebooks with Next/Previous links and back-link to Start Here - Terminal notebooks (plan endings) offer cross-plan links to explore other plans - Plan C dashboard gets explicit recommended reading order (Track A → B → C) - Add test_start_here_exists_and_links_all_plans and test_every_notebook_has_navigation_footer to test suite - Skip navigation-only notebooks in code-cell and assessment tests --- notebooks/00_START_HERE.ipynb | 102 ++++++++++++++++ notebooks/plan_a/01_encoded_magic_state.ipynb | 113 ++++++++++-------- notebooks/plan_a/02_measuring_progress.ipynb | 30 +++-- notebooks/plan_a/03_the_ratchet.ipynb | 22 ++-- notebooks/plan_b/spiral_notebook.ipynb | 16 +++ notebooks/plan_c/00_dashboard.ipynb | 23 ++-- notebooks/plan_c/track_a_physics.ipynb | 12 +- notebooks/plan_c/track_b_engineering.ipynb | 20 ++-- notebooks/plan_c/track_c_search.ipynb | 28 +++-- .../plan_d/experiment_1_protection.ipynb | 24 ++-- notebooks/plan_d/experiment_2_noise.ipynb | 22 ++-- .../plan_d/experiment_3_optimisation.ipynb | 34 +++--- tests/test_notebooks.py | 41 ++++++- 13 files changed, 355 insertions(+), 132 deletions(-) create mode 100644 notebooks/00_START_HERE.ipynb diff --git a/notebooks/00_START_HERE.ipynb b/notebooks/00_START_HERE.ipynb new file mode 100644 index 0000000..1548c4a --- /dev/null +++ b/notebooks/00_START_HERE.ipynb @@ -0,0 +1,102 @@ +{ + "nbformat": 4, + "nbformat_minor": 5, + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "name": "python", + "version": "3.11.0" + } + }, + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Autoresearch Quantum \u2014 Start Here\n", + "\n", + "Welcome to the **Autoresearch Quantum** course: an interactive exploration of encoded magic-state preparation using the [[4,2,2]] quantum error-detecting code.\n", + "\n", + "This course offers **four learning plans**. Each covers the same core material \u2014 quantum error detection, noise modelling, scoring, and automated optimisation \u2014 but at a different pace, depth, and style. **Pick the one that fits you best.**" + ], + "id": "start-header" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "---\n", + "## Choose Your Learning Plan\n", + "\n", + "| Plan | Style | Who is it for? | Start here |\n", + "|------|-------|----------------|------------|\n", + "| **A \u2014 Sequential** | Three notebooks, gentle build-up | Learners who prefer a structured, step-by-step introduction | [Plan A \u2014 Notebook 1](plan_a/01_encoded_magic_state.ipynb) |\n", + "| **B \u2014 Spiral** | One long notebook, three passes at increasing depth | Learners who like seeing the whole picture first, then zooming in | [Plan B \u2014 Spiral Notebook](plan_b/spiral_notebook.ipynb) |\n", + "| **C \u2014 Parallel Tracks** | Dashboard + three independent deep-dive tracks | Experienced learners who want to explore topics in any order | [Plan C \u2014 Dashboard](plan_c/00_dashboard.ipynb) |\n", + "| **D \u2014 Hypothesis-Driven** | Three experiments, each testing a hypothesis | Research-minded learners who think in hypotheses and evidence | [Plan D \u2014 Experiment 1](plan_d/experiment_1_protection.ipynb) |" + ], + "id": "plan-table" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "---\n", + "## Plan Details\n", + "\n", + "### Plan A \u2014 Sequential (3 notebooks)\n", + "A gentle, linear path through the material:\n", + "1. **[Notebook 1: Building an Encoded Magic State](plan_a/01_encoded_magic_state.ipynb)** \u2014 construct the [[4,2,2]] code and verify stabilisers\n", + "2. **[Notebook 2: Measuring Progress](plan_a/02_measuring_progress.ipynb)** \u2014 add noise, define a scoring metric, evaluate quality\n", + "3. **[Notebook 3: The Ratchet](plan_a/03_the_ratchet.ipynb)** \u2014 automated optimisation via the ratchet algorithm\n", + "\n", + "### Plan B \u2014 Spiral (1 notebook)\n", + "One continuous notebook with three passes:\n", + "- **Pass 1:** Run the machine, watch it work, get curious\n", + "- **Pass 2:** Understand what each component does\n", + "- **Pass 3:** Take the wheel and drive the optimiser yourself\n", + "\n", + "**\u2192 [Start Plan B](plan_b/spiral_notebook.ipynb)**\n", + "\n", + "### Plan C \u2014 Parallel Tracks (4 notebooks)\n", + "A hub-and-spoke design for self-directed exploration:\n", + "- **[Dashboard](plan_c/00_dashboard.ipynb)** \u2014 interactive control room (keep open alongside tracks)\n", + "- **[Track A: Physics](plan_c/track_a_physics.ipynb)** \u2014 the quantum error-detecting code\n", + "- **[Track B: Engineering](plan_c/track_b_engineering.ipynb)** \u2014 noise, transpilation, cost\n", + "- **[Track C: Search](plan_c/track_c_search.ipynb)** \u2014 optimisation and the ratchet\n", + "\n", + "*Recommended order: start with the Dashboard, then work through Track A \u2192 B \u2192 C, returning to the Dashboard between tracks.*\n", + "\n", + "### Plan D \u2014 Hypothesis-Driven (3 notebooks)\n", + "Each notebook tests a hypothesis, building on the previous result:\n", + "1. **[Experiment 1: Can error detection protect a magic state?](plan_d/experiment_1_protection.ipynb)**\n", + "2. **[Experiment 2: How much magic survives real-world noise?](plan_d/experiment_2_noise.ipynb)**\n", + "3. **[Experiment 3: Can a machine learn to optimise preparation?](plan_d/experiment_3_optimisation.ipynb)**" + ], + "id": "plan-details" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "---\n", + "## Not Sure Which Plan to Pick?\n", + "\n", + "- **New to quantum computing?** Start with **Plan A** \u2014 it introduces each concept one at a time.\n", + "- **Short on time?** Try **Plan B** \u2014 the first pass takes about 5 minutes and gives you the full picture.\n", + "- **Already familiar with quantum error correction?** Jump to **Plan C** and explore the tracks that interest you.\n", + "- **Research-oriented?** **Plan D** mirrors the scientific method \u2014 hypothesis, experiment, conclusion.\n", + "\n", + "All four plans cover the same core ideas. You can always switch plans or revisit material from another plan later.\n", + "\n", + "---\n", + "*See [learning_objectives.md](learning_objectives.md) for detailed learning outcomes mapped to each plan.*" + ], + "id": "plan-advice" + } + ] +} \ No newline at end of file diff --git a/notebooks/plan_a/01_encoded_magic_state.ipynb b/notebooks/plan_a/01_encoded_magic_state.ipynb index 541cfa3..c06fe49 100644 --- a/notebooks/plan_a/01_encoded_magic_state.ipynb +++ b/notebooks/plan_a/01_encoded_magic_state.ipynb @@ -10,9 +10,9 @@ "\n", "### The big picture\n", "\n", - "In fault-tolerant quantum computing, most logical gates can be implemented transversally using **Clifford operations** (H, S, CNOT). But Cliffords alone are not enough for universal computation. The **Gottesman-Knill theorem** proves that any circuit built only from Clifford gates can be efficiently simulated on a classical computer — no quantum advantage.\n", + "In fault-tolerant quantum computing, most logical gates can be implemented transversally using **Clifford operations** (H, S, CNOT). But Cliffords alone are not enough for universal computation. The **Gottesman-Knill theorem** proves that any circuit built only from Clifford gates can be efficiently simulated on a classical computer \u2014 no quantum advantage.\n", "\n", - "To break out of this classical-simulability trap, you need a **non-Clifford resource**. The simplest one is the **T-gate** ($\\pi/8$ rotation). But implementing T fault-tolerantly is hard — you cannot do it transversally in most codes. The workaround: prepare a special quantum state called the **magic state**, then consume it to perform the T-gate via gate teleportation.\n", + "To break out of this classical-simulability trap, you need a **non-Clifford resource**. The simplest one is the **T-gate** ($\\pi/8$ rotation). But implementing T fault-tolerantly is hard \u2014 you cannot do it transversally in most codes. The workaround: prepare a special quantum state called the **magic state**, then consume it to perform the T-gate via gate teleportation.\n", "\n", "$$|T\\rangle = \\frac{|0\\rangle + e^{i\\pi/4}|1\\rangle}{\\sqrt{2}}$$\n", "\n", @@ -21,7 +21,7 @@ "2. Understand *why* there are multiple preparation methods and when each matters\n", "3. Encode it into the [[4,2,2]] error-detecting code\n", "4. Verify the encoding using stabilizer algebra\n", - "5. See error detection in action — break the state and watch the code catch it\n", + "5. See error detection in action \u2014 break the state and watch the code catch it\n", "6. Run a full syndrome-measurement simulation with postselection" ] }, @@ -95,7 +95,7 @@ "\n", "### Why this state?\n", "\n", - "Imagine you have a quantum computer that can only do Clifford gates. You can create entanglement, teleport states, do error correction — but you **cannot** solve any problem faster than a classical computer. You are stuck.\n", + "Imagine you have a quantum computer that can only do Clifford gates. You can create entanglement, teleport states, do error correction \u2014 but you **cannot** solve any problem faster than a classical computer. You are stuck.\n", "\n", "The T-state is the key that unlocks universality. By preparing $|T\\rangle$ with high fidelity and \"injecting\" it into your Clifford circuit, you gain the ability to perform the T-gate:\n", "\n", @@ -152,7 +152,7 @@ "version_minor": 0 }, "text/plain": [ - "VBox(children=(HTML(value='
…" + "VBox(children=(HTML(value='
\u2026" ] }, "metadata": {}, @@ -186,12 +186,12 @@ "### The Bloch sphere picture\n", "\n", "Every single-qubit pure state can be visualized as a point on the Bloch sphere. The T-state sits at:\n", - "- **Polar angle** $\\theta = \\pi/2$ (on the equator — equal probability of $|0\\rangle$ and $|1\\rangle$)\n", - "- **Azimuthal angle** $\\phi = \\pi/4$ (45° between the X and Y axes)\n", + "- **Polar angle** $\\theta = \\pi/2$ (on the equator \u2014 equal probability of $|0\\rangle$ and $|1\\rangle$)\n", + "- **Azimuthal angle** $\\phi = \\pi/4$ (45\u00b0 between the X and Y axes)\n", "\n", "This means $\\langle X \\rangle = \\langle Y \\rangle = 1/\\sqrt{2} \\approx 0.707$ and $\\langle Z \\rangle = 0$.\n", "\n", - "Stabilizer states ($|0\\rangle$, $|+\\rangle$, $|i\\rangle$, etc.) always sit at the poles or on the axes. The T-state is **between** axes — that's what makes it non-stabilizer and therefore useful." + "Stabilizer states ($|0\\rangle$, $|+\\rangle$, $|i\\rangle$, etc.) always sit at the poles or on the axes. The T-state is **between** axes \u2014 that's what makes it non-stabilizer and therefore useful." ] }, { @@ -247,7 +247,7 @@ "version_minor": 0 }, "text/plain": [ - "VBox(children=(HTML(value='
…" + "VBox(children=(HTML(value='
\u2026" ] }, "metadata": {}, @@ -261,7 +261,7 @@ "version_minor": 0 }, "text/plain": [ - "VBox(children=(HTML(value='
…" + "VBox(children=(HTML(value='
\u2026" ] }, "execution_count": 8, @@ -299,7 +299,7 @@ "version_minor": 0 }, "text/plain": [ - "VBox(children=(HTML(value='
…" + "VBox(children=(HTML(value='
\u2026" ] }, "metadata": {}, @@ -308,7 +308,7 @@ { "data": { "text/html": [ - "
Checkpoint — 1. The T-state: 3/3 correct (100.0%)

Good grasp of this section. Moving on!
" + "
Checkpoint \u2014 1. The T-state: 3/3 correct (100.0%)

Good grasp of this section. Moving on!
" ], "text/plain": [ "" @@ -343,7 +343,7 @@ "metadata": {}, "source": [ "---\n", - "## 2. Three Seed Styles — Same State, Different Gates\n", + "## 2. Three Seed Styles \u2014 Same State, Different Gates\n", "\n", "### Why multiple preparations?\n", "\n", @@ -446,7 +446,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "All three fidelities are 1.0 (or extremely close) and the Bloch spheres all point to the same spot. The amplitudes may differ by a **global phase** factor $e^{i\\theta}$, which has no physical significance — all measurements yield identical results.\n", + "All three fidelities are 1.0 (or extremely close) and the Bloch spheres all point to the same spot. The amplitudes may differ by a **global phase** factor $e^{i\\theta}$, which has no physical significance \u2014 all measurements yield identical results.\n", "\n", "> **Take-away:** The choice of seed style is not about physics (they all give the same state). It is about **engineering**: which one transpiles to the fewest noisy gates on your target hardware?" ] @@ -464,7 +464,7 @@ "version_minor": 0 }, "text/plain": [ - "VBox(children=(HTML(value='
…" + "VBox(children=(HTML(value='
\u2026" ] }, "metadata": {}, @@ -473,7 +473,7 @@ { "data": { "text/html": [ - "
Checkpoint — 2. Seed styles: 1/1 correct (100.0%)

Good grasp of this section. Moving on!
" + "
Checkpoint \u2014 2. Seed styles: 1/1 correct (100.0%)

Good grasp of this section. Moving on!
" ], "text/plain": [ "" @@ -511,7 +511,7 @@ "\n", "### The dilemma\n", "\n", - "A bare single-qubit T-state is **fragile**. Any noise — bit-flips, phase drifts, measurement crosstalk — corrupts it. And we cannot protect it the way we protect classical data:\n", + "A bare single-qubit T-state is **fragile**. Any noise \u2014 bit-flips, phase drifts, measurement crosstalk \u2014 corrupts it. And we cannot protect it the way we protect classical data:\n", "\n", "- **No cloning**: Quantum mechanics forbids copying an unknown quantum state.\n", "- **No majority vote**: We cannot make 3 copies and take the majority.\n", @@ -528,7 +528,7 @@ "\n", "What \"distance 2\" means concretely: if **one** qubit suffers an error (X, Y, or Z), the code's stabilizer measurements will flag it. The strategy is **postselection**: discard any shot where an error was detected, and keep only the clean shots.\n", "\n", - "This is a trade-off: you lose some shots (reduced acceptance rate) but the surviving shots have higher quality. Whether this trade-off is worthwhile depends on the noise level — we'll explore this quantitatively in Notebook 2." + "This is a trade-off: you lose some shots (reduced acceptance rate) but the surviving shots have higher quality. Whether this trade-off is worthwhile depends on the noise level \u2014 we'll explore this quantitatively in Notebook 2." ] }, { @@ -544,7 +544,7 @@ "version_minor": 0 }, "text/plain": [ - "VBox(children=(HTML(value='
…" + "VBox(children=(HTML(value='
\u2026" ] }, "metadata": {}, @@ -558,7 +558,7 @@ "version_minor": 0 }, "text/plain": [ - "VBox(children=(HTML(value='
…" + "VBox(children=(HTML(value='
\u2026" ] }, "execution_count": 16, @@ -599,7 +599,7 @@ "version_minor": 0 }, "text/plain": [ - "VBox(children=(HTML(value='
…" + "VBox(children=(HTML(value='
\u2026" ] }, "metadata": {}, @@ -608,7 +608,7 @@ { "data": { "text/html": [ - "
Checkpoint — 3. Why encode: 1/1 correct (100.0%)

Good grasp of this section. Moving on!
" + "
Checkpoint \u2014 3. Why encode: 1/1 correct (100.0%)

Good grasp of this section. Moving on!
" ], "text/plain": [ "" @@ -647,7 +647,7 @@ "\n", "### What the encoder does\n", "\n", - "The encoder takes 4 qubits in the state $|T\\rangle|0\\rangle|0\\rangle|0\\rangle$ and entangles them into a 4-qubit codeword. After encoding, **no single qubit carries the T-state information** — it is distributed across all four qubits. This redundancy is what enables error detection.\n", + "The encoder takes 4 qubits in the state $|T\\rangle|0\\rangle|0\\rangle|0\\rangle$ and entangles them into a 4-qubit codeword. After encoding, **no single qubit carries the T-state information** \u2014 it is distributed across all four qubits. This redundancy is what enables error detection.\n", "\n", "The `cx_chain` encoder uses 5 CNOT gates and 1 Hadamard:" ] @@ -691,12 +691,12 @@ "\n", "| Step | Gate | What it does |\n", "|------|------|-------------|\n", - "| 1 | CNOT(0, 2) | Spreads qubit 0's state to qubit 2 — begins creating the logical $X_L = X_0 X_2$ structure |\n", + "| 1 | CNOT(0, 2) | Spreads qubit 0's state to qubit 2 \u2014 begins creating the logical $X_L = X_0 X_2$ structure |\n", "| 2 | CNOT(1, 0) | Entangles the spectator qubit 1 with qubit 0 |\n", "| 3 | H(3) | Puts qubit 3 in superposition $|+\\rangle$ |\n", "| 4-6 | CNOT(3, 0), CNOT(3, 1), CNOT(3, 2) | Qubit 3 fans out to all others, creating the $XXXX$ stabilizer structure |\n", "\n", - "The CNOTs create **entanglement** between the qubits. After step 6, measuring any single qubit gives a random outcome — but measuring the **parity** of all four (the stabilizer) gives a deterministic result." + "The CNOTs create **entanglement** between the qubits. After step 6, measuring any single qubit gives a random outcome \u2014 but measuring the **parity** of all four (the stabilizer) gives a deterministic result." ] }, { @@ -712,7 +712,7 @@ "version_minor": 0 }, "text/plain": [ - "VBox(children=(HTML(value='
…" + "VBox(children=(HTML(value='
\u2026" ] }, "metadata": {}, @@ -726,7 +726,7 @@ "version_minor": 0 }, "text/plain": [ - "VBox(children=(HTML(value='
…" + "VBox(children=(HTML(value='
\u2026" ] }, "execution_count": 20, @@ -759,7 +759,7 @@ "\n", "### What to expect\n", "\n", - "A 4-qubit system has $2^4 = 16$ possible basis states ($|0000\\rangle$ through $|1111\\rangle$). But the encoded T-state only occupies a small subspace — the **codespace** of the [[4,2,2]] code. We expect only a few basis states to have non-zero amplitude." + "A 4-qubit system has $2^4 = 16$ possible basis states ($|0000\\rangle$ through $|1111\\rangle$). But the encoded T-state only occupies a small subspace \u2014 the **codespace** of the [[4,2,2]] code. We expect only a few basis states to have non-zero amplitude." ] }, { @@ -775,7 +775,7 @@ "version_minor": 0 }, "text/plain": [ - "VBox(children=(HTML(value='
…" + "VBox(children=(HTML(value='
\u2026" ] }, "metadata": {}, @@ -789,7 +789,7 @@ "version_minor": 0 }, "text/plain": [ - "VBox(children=(HTML(value='
…" + "VBox(children=(HTML(value='
\u2026" ] }, "execution_count": 22, @@ -879,9 +879,9 @@ "### Interpreting the output\n", "\n", "You should see exactly **4** non-zero amplitudes: $|0000\\rangle$, $|0101\\rangle$, $|1010\\rangle$, $|1111\\rangle$. These are the codewords of the [[4,2,2]] code. Notice:\n", - "- All four have the **same magnitude** (0.5) — equal probability\n", + "- All four have the **same magnitude** (0.5) \u2014 equal probability\n", "- The **phases** encode the T-state information (the $e^{i\\pi/4}$ factor appears on $|0101\\rangle$ and $|1010\\rangle$)\n", - "- No single qubit's measurement alone reveals the T-state — the information lives in the *correlations* between qubits" + "- No single qubit's measurement alone reveals the T-state \u2014 the information lives in the *correlations* between qubits" ] }, { @@ -892,7 +892,7 @@ { "data": { "text/html": [ - "
Checkpoint — 5. Encoded state: 1/1 correct (100.0%)

Good grasp of this section. Moving on!
" + "
Checkpoint \u2014 5. Encoded state: 1/1 correct (100.0%)

Good grasp of this section. Moving on!
" ], "text/plain": [ "" @@ -911,7 +911,7 @@ "metadata": {}, "source": [ "---\n", - "## 6. Stabilizer Verification — The Quantum Checksum\n", + "## 6. Stabilizer Verification \u2014 The Quantum Checksum\n", "\n", "### What are stabilizers?\n", "\n", @@ -965,7 +965,7 @@ "version_minor": 0 }, "text/plain": [ - "VBox(children=(HTML(value='
…" + "VBox(children=(HTML(value='
\u2026" ] }, "metadata": {}, @@ -979,7 +979,7 @@ "version_minor": 0 }, "text/plain": [ - "VBox(children=(HTML(value='
…" + "VBox(children=(HTML(value='
\u2026" ] }, "execution_count": 27, @@ -1036,7 +1036,7 @@ "metadata": {}, "source": [ "---\n", - "## 7. Error Detection in Action — Break It on Purpose\n", + "## 7. Error Detection in Action \u2014 Break It on Purpose\n", "\n", "### The experiment\n", "\n", @@ -1130,7 +1130,7 @@ "| Z (phase-flip) | XXXX | Z anti-commutes with X |\n", "| Y (both) | XXXX and ZZZZ | Y = iXZ, so both parts are caught |\n", "\n", - "This is the **distance-2 guarantee**: the code detects all weight-1 errors. A weight-2 error (two qubits affected simultaneously) could go undetected — that's the limitation of distance 2." + "This is the **distance-2 guarantee**: the code detects all weight-1 errors. A weight-2 error (two qubits affected simultaneously) could go undetected \u2014 that's the limitation of distance 2." ] }, { @@ -1232,7 +1232,7 @@ "\n", "### The measurement problem\n", "\n", - "We just computed $\\langle ZZZZ \\rangle$ and $\\langle XXXX \\rangle$ using the full statevector. But on a real quantum computer, we don't have access to the statevector — we can only **measure** qubits.\n", + "We just computed $\\langle ZZZZ \\rangle$ and $\\langle XXXX \\rangle$ using the full statevector. But on a real quantum computer, we don't have access to the statevector \u2014 we can only **measure** qubits.\n", "\n", "**The catch:** If we measure the 4 data qubits directly, the measurement collapses the superposition and **destroys** the encoded state. We'd learn the stabilizer value, but the T-state would be gone.\n", "\n", @@ -1241,13 +1241,13 @@ "Instead, we use **ancilla** (helper) qubits. The idea:\n", "1. Prepare an ancilla qubit in $|0\\rangle$\n", "2. Apply controlled gates between the ancilla and each data qubit to transfer the stabilizer's **parity** onto the ancilla\n", - "3. Measure **only the ancilla** — the data qubits remain untouched\n", + "3. Measure **only the ancilla** \u2014 the data qubits remain untouched\n", "\n", "The ancilla measurement result (0 or 1) tells us the stabilizer eigenvalue ($+1$ or $-1$) without collapsing the data qubits. This is called **syndrome extraction**.\n", "\n", "The result is a **syndrome** bitstring. For our code with two stabilizers, the syndrome is 2 bits:\n", - "- `00` → both stabilizers +1 → no error detected → **keep this shot**\n", - "- Anything else → error detected → **discard this shot** (postselection)" + "- `00` \u2192 both stabilizers +1 \u2192 no error detected \u2192 **keep this shot**\n", + "- Anything else \u2192 error detected \u2192 **discard this shot** (postselection)" ] }, { @@ -1377,7 +1377,7 @@ "In a **noiseless** simulation, the state is always in the codespace. That means:\n", "- Both stabilizers always return +1\n", "- Syndrome is always `00`\n", - "- **Every** shot passes postselection → acceptance rate = 100%\n", + "- **Every** shot passes postselection \u2192 acceptance rate = 100%\n", "\n", "This is our baseline. Real hardware will be much noisier." ] @@ -1441,13 +1441,13 @@ "metadata": {}, "source": [ "---\n", - "## 11. Postselection — Keeping Only the Good Shots\n", + "## 11. Postselection \u2014 Keeping Only the Good Shots\n", "\n", "### The idea\n", "\n", "**Postselection** is a filter: after collecting all measurement results, we look at the syndrome bits and **discard** any shot where the syndrome indicates an error was detected.\n", "\n", - "In the ideal case (above), this filter has no effect — all shots pass. But under noise (Notebook 2), many shots will fail the syndrome check. The trade-off:\n", + "In the ideal case (above), this filter has no effect \u2014 all shots pass. But under noise (Notebook 2), many shots will fail the syndrome check. The trade-off:\n", "\n", "| | Without postselection | With postselection |\n", "|---|---|---|\n", @@ -1533,10 +1533,10 @@ "| Concept | What you now know |\n", "|---------|------------------|\n", "| **T-state** | The non-Clifford resource $|T\\rangle = (|0\\rangle + e^{i\\pi/4}|1\\rangle)/\\sqrt{2}$ needed for universal QC |\n", - "| **Seed styles** | Three equivalent gate sequences (h_p, ry_rz, u_magic) — same physics, different engineering trade-offs |\n", - "| **[[4,2,2]] code** | 4 physical qubits, 2 logical qubits, distance 2 — detects but doesn't correct single errors |\n", - "| **Stabilizers** | XXXX and ZZZZ act as quantum checksums — eigenvalue +1 means \"no error\" |\n", - "| **Error detection** | X→caught by ZZZZ, Z→caught by XXXX, Y→caught by both |\n", + "| **Seed styles** | Three equivalent gate sequences (h_p, ry_rz, u_magic) \u2014 same physics, different engineering trade-offs |\n", + "| **[[4,2,2]] code** | 4 physical qubits, 2 logical qubits, distance 2 \u2014 detects but doesn't correct single errors |\n", + "| **Stabilizers** | XXXX and ZZZZ act as quantum checksums \u2014 eigenvalue +1 means \"no error\" |\n", + "| **Error detection** | X\u2192caught by ZZZZ, Z\u2192caught by XXXX, Y\u2192caught by both |\n", "| **Ancilla qubits** | Allow syndrome extraction without destroying the encoded state |\n", "| **Postselection** | Discard error-flagged shots to improve quality at the cost of acceptance rate |\n", "\n", @@ -1561,6 +1561,19 @@ "path = tracker.save()\n", "print(f\"\\nProgress saved to: {path}\")" ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "---\n", + "## Navigation\n", + "\n", + "**\u2192 Next: [Notebook 2 \u2014 Measuring Progress](02_measuring_progress.ipynb)**\n", + "\n", + "*\u2190 Back to [Start Here](../00_START_HERE.ipynb)*" + ], + "id": "nav-footer-01" } ], "metadata": { @@ -1584,4 +1597,4 @@ }, "nbformat": 4, "nbformat_minor": 4 -} +} \ No newline at end of file diff --git a/notebooks/plan_a/02_measuring_progress.ipynb b/notebooks/plan_a/02_measuring_progress.ipynb index 5a108e6..7322cce 100644 --- a/notebooks/plan_a/02_measuring_progress.ipynb +++ b/notebooks/plan_a/02_measuring_progress.ipynb @@ -6,7 +6,7 @@ "source": [ "# Notebook 2: How Do You Know If It Worked?\n", "\n", - "**Plan A — Measuring Progress**\n", + "**Plan A \u2014 Measuring Progress**\n", "\n", "In Notebook 1 you built an encoded magic state and verified it in an ideal simulator. But real quantum hardware is noisy. This notebook answers: *How do we quantify how good our preparation is, and how do we turn those measurements into a single score the ratchet can optimize?*\n", "\n", @@ -244,7 +244,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "> **Observe:** The ideal histogram shows only a few bitstrings (those consistent with the codespace). The noisy histogram is spread across many more outcomes — noise is kicking the state out of the codespace.\n", + "> **Observe:** The ideal histogram shows only a few bitstrings (those consistent with the codespace). The noisy histogram is spread across many more outcomes \u2014 noise is kicking the state out of the codespace.\n", "\n", "---\n", "## 3. Postselection: Filtering Bad Shots\n", @@ -309,7 +309,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "> **Key Insight:** The acceptance rate is the fraction of shots that survive postselection. Under noise it can drop significantly — this is the code *working* by detecting errors. But a low acceptance rate means you need more shots to get the same statistical precision, which increases cost.\n", + "> **Key Insight:** The acceptance rate is the fraction of shots that survive postselection. Under noise it can drop significantly \u2014 this is the code *working* by detecting errors. But a low acceptance rate means you need more shots to get the same statistical precision, which increases cost.\n", "\n", "---\n", "## 4. Measuring Logical Operators\n", @@ -384,8 +384,8 @@ "\n", "9951W = \frac{1 + \frac{\\langle X_L \rangle + \\langle Y_L \rangle}{\\sqrt{2}}}{2} \times \frac{1 + \\langle Z_{\text{spectator}} \rangle}{2}9951\n", "\n", - "- The first factor checks the \"magic\" — a perfect T-state has $\\langle X_L \rangle = \\langle Y_L \rangle = 1/\\sqrt{2}$, giving 1.0.\n", - "- The second factor checks spectator integrity — the second logical qubit should be in $|0_L\rangle$, giving $\\langle Z_{\text{spectator}} \rangle = +1$.\n", + "- The first factor checks the \"magic\" \u2014 a perfect T-state has $\\langle X_L \rangle = \\langle Y_L \rangle = 1/\\sqrt{2}$, giving 1.0.\n", + "- The second factor checks spectator integrity \u2014 the second logical qubit should be in $|0_L\rangle$, giving $\\langle Z_{\text{spectator}} \rangle = +1$.\n", "- For a perfect encoded T-state: = 1.0$.\n", "- For a maximally mixed state: \u0007pprox 0.25$." ] @@ -454,7 +454,7 @@ "---\n", "## 6. Noisy Fidelity via Density Matrix\n", "\n", - "An alternative quality metric is the **state fidelity** — how close the noisy output is to the ideal encoded T-state." + "An alternative quality metric is the **state fidelity** \u2014 how close the noisy output is to the ideal encoded T-state." ] }, { @@ -463,7 +463,7 @@ "source": [ "# Noisy fidelity via density matrix on the LOGICAL (untranspiled) 4-qubit circuit.\n", "# Note: density matrix simulation on the transpiled 127-qubit circuit would require\n", - "# 2^127 x 2^127 matrix entries — impossible on any current machine!\n", + "# 2^127 x 2^127 matrix entries \u2014 impossible on any current machine!\n", "# Instead, we apply the noise model to the compact 4-qubit prep circuit.\n", "\n", "target = encoded_magic_statevector()\n", @@ -714,12 +714,12 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "> **Observe:** Higher optimization levels typically reduce gate count and depth, which lowers cost. But the effect on quality depends on how the transpiler remaps the circuit — sometimes a different layout performs better or worse under that backend's specific noise profile.\n", + "> **Observe:** Higher optimization levels typically reduce gate count and depth, which lowers cost. But the effect on quality depends on how the transpiler remaps the circuit \u2014 sometimes a different layout performs better or worse under that backend's specific noise profile.\n", "\n", "---\n", "## 9. Dominant Failure Modes\n", "\n", - "The harness classifies each experiment into a **dominant failure mode** — the biggest weakness:\n", + "The harness classifies each experiment into a **dominant failure mode** \u2014 the biggest weakness:\n", "\n", "| Failure Mode | Trigger | Meaning |\n", "|---|---|---|\n", @@ -765,7 +765,7 @@ "---\n", "## 10. Factory Throughput Score\n", "\n", - "The default scorer optimizes . An alternative — **factory throughput** — optimizes for producing accepted magic states per unit cost, penalizing circuit resources more heavily:\n", + "The default scorer optimizes . An alternative \u2014 **factory throughput** \u2014 optimizes for producing accepted magic states per unit cost, penalizing circuit resources more heavily:\n", "\n", "9951\text{throughput} = \frac{\text{acceptance\\_rate} \times W}{\text{cost}}9951\n", "\n", @@ -824,7 +824,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "> **Key Insight:** Different scoring functions rank experiments differently. The choice depends on your goal: maximizing state quality vs maximizing factory throughput. The ratchet is agnostic — it optimizes whichever score you configure.\n", + "> **Key Insight:** Different scoring functions rank experiments differently. The choice depends on your goal: maximizing state quality vs maximizing factory throughput. The ratchet is agnostic \u2014 it optimizes whichever score you configure.\n", "\n", "---\n", "## 11. Summary\n", @@ -836,7 +836,7 @@ "| **Acceptance rate** | Fraction of shots surviving postselection |\n", "| **Logical witness** | Certification of magic property ( = 1.0$ for perfect T-state) |\n", "| **Noisy fidelity** | Overlap with ideal encoded state under noise |\n", - "| **Score** | quality × acceptance / cost — the single number to optimize |\n", + "| **Score** | quality \u00d7 acceptance / cost \u2014 the single number to optimize |\n", "| **Failure mode** | Biggest weakness of the current configuration |\n", "\n", "**Next:** Notebook 3 shows how the ratchet *automatically* explores parameter space to maximize this score." @@ -860,6 +860,12 @@ ], "outputs": [], "execution_count": null + }, + { + "cell_type": "markdown", + "id": "bb8ecde9", + "source": "---\n## Navigation\n\n**\u2192 Next: [Notebook 3 \u2014 The Ratchet](03_the_ratchet.ipynb)**\n\n*\u2190 Previous: [Notebook 1 \u2014 Building an Encoded Magic State](01_encoded_magic_state.ipynb) \u00b7 [Start Here](../00_START_HERE.ipynb)*", + "metadata": {} } ], "metadata": { diff --git a/notebooks/plan_a/03_the_ratchet.ipynb b/notebooks/plan_a/03_the_ratchet.ipynb index ac0e296..7273143 100644 --- a/notebooks/plan_a/03_the_ratchet.ipynb +++ b/notebooks/plan_a/03_the_ratchet.ipynb @@ -7,7 +7,7 @@ "source": [ "# Notebook 3: The Ratchet Learns For You\n", "\n", - "**Plan A — Automated Search**\n", + "**Plan A \u2014 Automated Search**\n", "\n", "You now know what an encoded magic state is (Notebook 1) and how to measure its quality (Notebook 2). This notebook shows how the **autoresearch ratchet** automatically explores the parameter space to find the best circuit configuration.\n", "\n", @@ -97,12 +97,12 @@ "\n", "The ratchet keeps a **best-so-far** configuration called the **incumbent**. Each step:\n", "\n", - "1. Generate **challengers** — new configurations that differ from the incumbent in one or more parameters\n", + "1. Generate **challengers** \u2014 new configurations that differ from the incumbent in one or more parameters\n", "2. Evaluate each challenger on the cheap tier (noisy simulator)\n", "3. If any challenger beats the incumbent by a margin, it becomes the new incumbent\n", "4. Repeat until patience runs out\n", "\n", - "This is a form of **local search** — like hill climbing in parameter space." + "This is a form of **local search** \u2014 like hill climbing in parameter space." ] }, { @@ -178,7 +178,7 @@ "version_minor": 0 }, "text/plain": [ - "VBox(children=(HTML(value='
…" + "VBox(children=(HTML(value='
\u2026" ] }, "metadata": {}, @@ -192,7 +192,7 @@ "version_minor": 0 }, "text/plain": [ - "VBox(children=(HTML(value='
…" + "VBox(children=(HTML(value='
\u2026" ] }, "execution_count": 4, @@ -365,7 +365,7 @@ "---\n", "## 4. One Ratchet Step in Slow Motion\n", "\n", - "Now let the harness run a complete ratchet step — including challenger generation, evaluation, promotion, and winner selection." + "Now let the harness run a complete ratchet step \u2014 including challenger generation, evaluation, promotion, and winner selection." ] }, { @@ -596,7 +596,7 @@ "---\n", "## 8. Lesson-Guided Search\n", "\n", - "After a rung completes, the harness extracts **SearchRules** — machine-readable directives like \"prefer z_only\" or \"avoid x_only\". These guide future search." + "After a rung completes, the harness extracts **SearchRules** \u2014 machine-readable directives like \"prefer z_only\" or \"avoid x_only\". These guide future search." ] }, { @@ -825,6 +825,12 @@ "path = tracker.save()\n", "print(f\"\\nProgress saved to: {path}\")" ] + }, + { + "cell_type": "markdown", + "id": "d0913b05", + "source": "---\n## You've completed Plan A!\n\nWant to explore the same material from a different angle? Try another plan:\n- [Plan B \u2014 Spiral Notebook](../plan_b/spiral_notebook.ipynb) (three passes, increasing depth)\n- [Plan C \u2014 Parallel Tracks](../plan_c/00_dashboard.ipynb) (self-directed deep dives)\n- [Plan D \u2014 Hypothesis-Driven](../plan_d/experiment_1_protection.ipynb) (experimental method)\n\n*\u2190 Previous: [Notebook 2 \u2014 Measuring Progress](02_measuring_progress.ipynb) \u00b7 [Start Here](../00_START_HERE.ipynb)*", + "metadata": {} } ], "metadata": { @@ -848,4 +854,4 @@ }, "nbformat": 4, "nbformat_minor": 5 -} +} \ No newline at end of file diff --git a/notebooks/plan_b/spiral_notebook.ipynb b/notebooks/plan_b/spiral_notebook.ipynb index 8c73df2..3a635f2 100644 --- a/notebooks/plan_b/spiral_notebook.ipynb +++ b/notebooks/plan_b/spiral_notebook.ipynb @@ -1976,6 +1976,22 @@ ], "outputs": [], "execution_count": null + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "---\n", + "## You've completed Plan B!\n", + "\n", + "Want to explore the same material from a different angle? Try another plan:\n", + "- [Plan A \u2014 Sequential](../plan_a/01_encoded_magic_state.ipynb) (step-by-step, three notebooks)\n", + "- [Plan C \u2014 Parallel Tracks](../plan_c/00_dashboard.ipynb) (self-directed deep dives)\n", + "- [Plan D \u2014 Hypothesis-Driven](../plan_d/experiment_1_protection.ipynb) (experimental method)\n", + "\n", + "*\u2190 Back to [Start Here](../00_START_HERE.ipynb)*" + ], + "id": "nav-footer-spiral" } ], "metadata": { diff --git a/notebooks/plan_c/00_dashboard.ipynb b/notebooks/plan_c/00_dashboard.ipynb index 874bdec..421f2f8 100644 --- a/notebooks/plan_c/00_dashboard.ipynb +++ b/notebooks/plan_c/00_dashboard.ipynb @@ -4,7 +4,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Autoresearch Quantum — Control Room\n", + "# Autoresearch Quantum \u2014 Control Room\n", "\n", "This interactive dashboard lets you run encoded magic-state experiments with different parameter settings\n", "and instantly visualize the results. Use it alongside the three Track notebooks:\n", @@ -116,7 +116,7 @@ "parameters. Click **Compare** to overlay a second run on the same plots (in orange) for side-by-side\n", "comparison.\n", "\n", - "**Tip**: Try changing `seed_style` among `h_p`, `ry_rz`, `u_magic` — the witness should stay roughly\n", + "**Tip**: Try changing `seed_style` among `h_p`, `ry_rz`, `u_magic` \u2014 the witness should stay roughly\n", "the same (they are equivalent preparations up to global phase)." ] }, @@ -168,7 +168,7 @@ "metadata": {}, "outputs": [], "source": [ - "# ── Widget definitions ─────────────────────────────────────────────\n", + "# \u2500\u2500 Widget definitions \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n", "w_seed = widgets.Dropdown(\n", " options=[\"h_p\", \"ry_rz\", \"u_magic\"],\n", " value=\"h_p\",\n", @@ -257,9 +257,9 @@ "\n", " colors = plt.cm.tab10.colors\n", " fig, axes = plt.subplots(2, 2, figsize=(14, 10))\n", - " fig.suptitle(\"Autoresearch Quantum — Control Room\", fontsize=14, fontweight=\"bold\")\n", + " fig.suptitle(\"Autoresearch Quantum \u2014 Control Room\", fontsize=14, fontweight=\"bold\")\n", "\n", - " # ── Top-left: Circuit diagram (latest run only) ──\n", + " # \u2500\u2500 Top-left: Circuit diagram (latest run only) \u2500\u2500\n", " ax_circ = axes[0, 0]\n", " ax_circ.set_axis_off()\n", " latest_prep = run_history[-1][2]\n", @@ -274,7 +274,7 @@ " bbox=dict(boxstyle=\"round\", facecolor=\"#f0f0f0\", alpha=0.8),\n", " )\n", "\n", - " # ── Top-right: Histogram of acceptance counts ──\n", + " # \u2500\u2500 Top-right: Histogram of acceptance counts \u2500\u2500\n", " ax_hist = axes[0, 1]\n", " ax_hist.set_title(\"Measurement Outcome Counts (acceptance circuit)\", fontsize=11)\n", " bar_width = 0.8 / max(len(run_history), 1)\n", @@ -295,7 +295,7 @@ " ax_hist.set_ylabel(\"Counts\")\n", " ax_hist.legend(fontsize=8)\n", "\n", - " # ── Bottom-left: Quality metrics bar chart ──\n", + " # \u2500\u2500 Bottom-left: Quality metrics bar chart \u2500\u2500\n", " ax_metrics = axes[1, 0]\n", " ax_metrics.set_title(\"Quality Metrics\", fontsize=11)\n", " metric_names = [\"acceptance_rate\", \"witness\", \"score\"]\n", @@ -317,7 +317,7 @@ " ax_metrics.set_xlim(0, 1.0)\n", " ax_metrics.legend(fontsize=8)\n", "\n", - " # ── Bottom-right: Transpile cost stats ──\n", + " # \u2500\u2500 Bottom-right: Transpile cost stats \u2500\u2500\n", " ax_cost = axes[1, 1]\n", " ax_cost.set_title(\"Transpile & Cost Stats\", fontsize=11)\n", " cost_names = [\"2Q gates\", \"depth\", \"total_cost\"]\n", @@ -395,7 +395,7 @@ "btn_compare.on_click(on_compare)\n", "btn_clear.on_click(on_clear)\n", "\n", - "# ── Layout ──\n", + "# \u2500\u2500 Layout \u2500\u2500\n", "controls_left = widgets.VBox([w_seed, w_encoder, w_verification, w_postselection])\n", "controls_right = widgets.VBox([w_opt_level, w_shots, w_backend])\n", "buttons = widgets.HBox([btn_run, btn_compare, btn_clear])\n", @@ -479,6 +479,11 @@ ], "outputs": [], "execution_count": null + }, + { + "cell_type": "markdown", + "source": "---\n## Navigation \u2014 Plan C\n\n**Recommended reading order:**\n1. You are here: **Dashboard** (keep open alongside tracks)\n2. [Track A \u2014 Physics](track_a_physics.ipynb): the quantum error-detecting code\n3. [Track B \u2014 Engineering](track_b_engineering.ipynb): noise, transpilation, cost\n4. [Track C \u2014 Search](track_c_search.ipynb): optimisation and the ratchet\n\n*\u2190 Back to [Start Here](../00_START_HERE.ipynb)*", + "metadata": {} } ], "metadata": { diff --git a/notebooks/plan_c/track_a_physics.ipynb b/notebooks/plan_c/track_a_physics.ipynb index bbd955c..8d85919 100644 --- a/notebooks/plan_c/track_a_physics.ipynb +++ b/notebooks/plan_c/track_a_physics.ipynb @@ -6,9 +6,9 @@ "source": [ "# Track A: The Physics of Encoded Magic States\n", "\n", - "**Plan C — Parallel Tracks**\n", + "**Plan C \u2014 Parallel Tracks**\n", "\n", - "This track is pure quantum mechanics. It covers the theory behind magic states, the [[4,2,2]] stabilizer code, and the witness formula. No optimization, no scoring — just the physics.\n", + "This track is pure quantum mechanics. It covers the theory behind magic states, the [[4,2,2]] stabilizer code, and the witness formula. No optimization, no scoring \u2014 just the physics.\n", "\n", "> **Dashboard:** Open `00_dashboard.ipynb` alongside this notebook for interactive exploration." ] @@ -501,7 +501,7 @@ "\n", "fig, ax = plt.subplots(figsize=(8, 4))\n", "ax.plot(lx_values, w_vals, \"b-\", linewidth=2)\n", - "ax.axvline(x=1/np.sqrt(2), color=\"r\", linestyle=\"--\", label=\"T-state: 1/√2\")\n", + "ax.axvline(x=1/np.sqrt(2), color=\"r\", linestyle=\"--\", label=\"T-state: 1/\u221a2\")\n", "ax.set_xlabel(\" = \")\n", "ax.set_ylabel(\"Witness W\")\n", "ax.set_title(\"Magic Witness vs Logical Operator Expectations\")\n", @@ -574,6 +574,12 @@ ], "outputs": [], "execution_count": null + }, + { + "cell_type": "markdown", + "id": "11221165", + "source": "---\n## Navigation \u2014 Plan C\n\n**\u2192 Next: [Track B \u2014 Engineering](track_b_engineering.ipynb)**\n\n*\u2190 [Dashboard](00_dashboard.ipynb) \u00b7 [Start Here](../00_START_HERE.ipynb)*", + "metadata": {} } ], "metadata": { diff --git a/notebooks/plan_c/track_b_engineering.ipynb b/notebooks/plan_c/track_b_engineering.ipynb index 2aead44..1c86f8b 100644 --- a/notebooks/plan_c/track_b_engineering.ipynb +++ b/notebooks/plan_c/track_b_engineering.ipynb @@ -4,9 +4,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Track B: The Engineering — Noise, Transpilation, and Cost\n", + "# Track B: The Engineering \u2014 Noise, Transpilation, and Cost\n", "\n", - "**Plan C — Parallel Tracks**\n", + "**Plan C \u2014 Parallel Tracks**\n", "\n", "This track is about making quantum circuits work on noisy hardware. You will learn how noise degrades the encoded state, how transpilation maps logical circuits to physical hardware, and how the scoring formula balances quality against cost.\n", "\n", @@ -142,7 +142,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "> **Observe:** The ideal histogram concentrates on a few bitstrings (valid codewords). Noise spreads probability across many bitstrings — errors kick the state out of the codespace.\n", + "> **Observe:** The ideal histogram concentrates on a few bitstrings (valid codewords). Noise spreads probability across many bitstrings \u2014 errors kick the state out of the codespace.\n", "\n", "---\n", "## 2. What Is a Noise Model?\n", @@ -262,7 +262,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "> **Key Insight:** Higher optimization levels generally reduce gate count and depth, but the effect is non-monotonic — it depends on the specific circuit and backend topology. Each two-qubit gate is ~10x noisier than a single-qubit gate, so fewer = better.\n", + "> **Key Insight:** Higher optimization levels generally reduce gate count and depth, but the effect is non-monotonic \u2014 it depends on the specific circuit and backend topology. Each two-qubit gate is ~10x noisier than a single-qubit gate, so fewer = better.\n", "\n", "---\n", "## 4. The Cost Model\n", @@ -410,7 +410,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "> **Key Insight:** The \"best\" optimization level is not always the highest — it depends on how the backend's noise profile interacts with the transpiled circuit layout.\n", + "> **Key Insight:** The \"best\" optimization level is not always the highest \u2014 it depends on how the backend's noise profile interacts with the transpiled circuit layout.\n", "\n", "---\n", "## 6. Noisy Fidelity via Density Matrix\n", @@ -570,7 +570,7 @@ "---\n", "## 9. Factory Throughput: An Alternative Score\n", "\n", - "The factory throughput scorer optimizes for *yield* — accepted magic states per unit cost:\n", + "The factory throughput scorer optimizes for *yield* \u2014 accepted magic states per unit cost:\n", "\n", "$$\\text{throughput} = \\frac{\\text{acceptance} \\times W}{\\text{cost}}$$" ] @@ -641,7 +641,7 @@ "| **Acceptance rate** | Fraction of shots surviving postselection; drops under noise |\n", "| **Cost model** | Penalizes 2Q gates, depth, shots, runtime |\n", "| **Failure modes** | Four categories classify the dominant weakness |\n", - "| **Score** | quality x acceptance / cost — the single optimization target |\n", + "| **Score** | quality x acceptance / cost \u2014 the single optimization target |\n", "\n", "> **Next:** Track A covers the physics in depth. Track C shows how the ratchet automates parameter search.\n", "\n", @@ -666,6 +666,12 @@ ], "outputs": [], "execution_count": null + }, + { + "cell_type": "markdown", + "id": "565da346", + "source": "---\n## Navigation \u2014 Plan C\n\n**\u2192 Next: [Track C \u2014 Search](track_c_search.ipynb)**\n\n*\u2190 Previous: [Track A \u2014 Physics](track_a_physics.ipynb) \u00b7 [Dashboard](00_dashboard.ipynb) \u00b7 [Start Here](../00_START_HERE.ipynb)*", + "metadata": {} } ], "metadata": { diff --git a/notebooks/plan_c/track_c_search.ipynb b/notebooks/plan_c/track_c_search.ipynb index 58c1b4a..fd085fd 100644 --- a/notebooks/plan_c/track_c_search.ipynb +++ b/notebooks/plan_c/track_c_search.ipynb @@ -4,9 +4,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Track C: The Search — Optimization and the Ratchet\n", + "# Track C: The Search \u2014 Optimization and the Ratchet\n", "\n", - "**Plan C — Parallel Tracks**\n", + "**Plan C \u2014 Parallel Tracks**\n", "\n", "This track covers automated parameter search. You will learn how the ratchet generates challengers, selects winners, extracts lessons, and narrows the search space across rungs.\n", "\n", @@ -128,7 +128,7 @@ "- Each challenger is evaluated (\"plays a match\")\n", "- If a challenger beats the incumbent by a sufficient margin, it takes the title\n", "\n", - "This is a form of **local search** — like hill climbing in a discrete parameter space." + "This is a form of **local search** \u2014 like hill climbing in a discrete parameter space." ] }, { @@ -202,7 +202,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "> **Key Insight:** NeighborWalk is exhaustive within single axes but never tests *combinations*. It is fast and deterministic — good for identifying which individual parameter matters most.\n", + "> **Key Insight:** NeighborWalk is exhaustive within single axes but never tests *combinations*. It is fast and deterministic \u2014 good for identifying which individual parameter matters most.\n", "\n", "---\n", "## 4. RandomCombo: Multi-Axis Perturbation\n", @@ -246,7 +246,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "> **Key Insight:** RandomCombo can discover *interaction effects* — parameter combinations that are better or worse than the sum of individual effects. It introduces diversity but is less systematic.\n", + "> **Key Insight:** RandomCombo can discover *interaction effects* \u2014 parameter combinations that are better or worse than the sum of individual effects. It introduces diversity but is less systematic.\n", "\n", "---\n", "## 5. Evaluating: Incumbent vs Challengers\n", @@ -458,7 +458,7 @@ "---\n", "## 8. Lesson Extraction\n", "\n", - "After a rung, the harness analyzes all experiments and extracts **lessons** — both human-readable narratives and machine-readable rules." + "After a rung, the harness analyzes all experiments and extracts **lessons** \u2014 both human-readable narratives and machine-readable rules." ] }, { @@ -537,7 +537,7 @@ " for c in guided_challengers:\n", " print(f\" {c.mutation_note}\")\n", "else:\n", - " print(\"No rules extracted — try a larger step_budget for more data.\")" + " print(\"No rules extracted \u2014 try a larger step_budget for more data.\")" ], "outputs": [], "execution_count": null @@ -592,7 +592,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "> **Key Insight:** Narrowing is \"learning\" — the machine prunes bad options based on evidence. This makes subsequent rungs faster and more focused.\n", + "> **Key Insight:** Narrowing is \"learning\" \u2014 the machine prunes bad options based on evidence. This makes subsequent rungs faster and more focused.\n", "\n", "---\n", "## 11. Cross-Rung Propagation\n", @@ -706,9 +706,9 @@ "\n", "| Concept | What it does |\n", "|---|---|\n", - "| **NeighborWalk** | Single-axis mutations — systematic but limited |\n", - "| **RandomCombo** | Multi-axis mutations — discovers interactions |\n", - "| **LessonGuided** | Rule-biased mutations — focuses on promising regions |\n", + "| **NeighborWalk** | Single-axis mutations \u2014 systematic but limited |\n", + "| **RandomCombo** | Multi-axis mutations \u2014 discovers interactions |\n", + "| **LessonGuided** | Rule-biased mutations \u2014 focuses on promising regions |\n", "| **Ratchet step** | Generate, evaluate, promote, select winner |\n", "| **Patience** | Stop early if no improvement |\n", "| **Lesson extraction** | Human-readable + machine-readable rules from data |\n", @@ -737,6 +737,12 @@ ], "outputs": [], "execution_count": null + }, + { + "cell_type": "markdown", + "id": "1cc666e4", + "source": "---\n## You've completed Plan C!\n\nWant to explore the same material from a different angle? Try another plan:\n- [Plan A \u2014 Sequential](../plan_a/01_encoded_magic_state.ipynb) (step-by-step, three notebooks)\n- [Plan B \u2014 Spiral Notebook](../plan_b/spiral_notebook.ipynb) (three passes, increasing depth)\n- [Plan D \u2014 Hypothesis-Driven](../plan_d/experiment_1_protection.ipynb) (experimental method)\n\n*\u2190 [Dashboard](00_dashboard.ipynb) \u00b7 [Track B \u2014 Engineering](track_b_engineering.ipynb) \u00b7 [Start Here](../00_START_HERE.ipynb)*", + "metadata": {} } ], "metadata": { diff --git a/notebooks/plan_d/experiment_1_protection.ipynb b/notebooks/plan_d/experiment_1_protection.ipynb index 3b8c27d..a80e40e 100644 --- a/notebooks/plan_d/experiment_1_protection.ipynb +++ b/notebooks/plan_d/experiment_1_protection.ipynb @@ -32,7 +32,7 @@ "\n", "Fault-tolerant quantum computing needs the $T$-gate, but the $T$-gate\n", "cannot be implemented transversally on most error-correcting codes\n", - "(Eastin–Knill theorem). The workaround is to prepare a **magic state**\n", + "(Eastin\u2013Knill theorem). The workaround is to prepare a **magic state**\n", "$|T\\rangle = (|0\\rangle + e^{i\\pi/4}|1\\rangle)/\\sqrt{2}$ and consume\n", "it via gate teleportation.\n", "\n", @@ -107,9 +107,9 @@ "\n", "$$|T\\rangle = \\frac{|0\\rangle + e^{i\\pi/4}|1\\rangle}{\\sqrt{2}}$$\n", "\n", - "It lives on the **equator** of the Bloch sphere, at $45°$ between the\n", + "It lives on the **equator** of the Bloch sphere, at $45\u00b0$ between the\n", "$+X$ and $+Y$ axes. Its special property: it enables the $T$-gate via\n", - "gate teleportation — the key non-Clifford resource for universal quantum\n", + "gate teleportation \u2014 the key non-Clifford resource for universal quantum\n", "computing." ] }, @@ -218,7 +218,7 @@ "metadata": {}, "source": [ "---\n", - "## Part 3: Testing Claim (2) — Stabiliser Verification\n", + "## Part 3: Testing Claim (2) \u2014 Stabiliser Verification\n", "\n", "**Claim:** Both stabiliser expectations are $+1$, confirming the\n", "encoded state is a valid codeword." @@ -267,7 +267,7 @@ "metadata": {}, "source": [ "---\n", - "## Part 4: Testing Claim (3) — Every Single-Qubit Error Is Detectable\n", + "## Part 4: Testing Claim (3) \u2014 Every Single-Qubit Error Is Detectable\n", "\n", "**Claim:** Every single-qubit Pauli error ($X$, $Z$, $Y$ on any of the\n", "4 qubits) flips at least one stabiliser from $+1$ to $-1$.\n", @@ -369,7 +369,7 @@ "metadata": {}, "source": [ "---\n", - "## Part 5: Testing Claim (1) — The Magic Witness\n", + "## Part 5: Testing Claim (1) \u2014 The Magic Witness\n", "\n", "**Claim:** The magic witness $W = 1.0$, proving the encoded state fully\n", "preserves the $T$-state character.\n", @@ -436,7 +436,7 @@ "metadata": {}, "source": [ "---\n", - "## Part 6: Testing Claim (4) — Postselection Works\n", + "## Part 6: Testing Claim (4) \u2014 Postselection Works\n", "\n", "**Claim:** Syndrome-based postselection correctly identifies all\n", "detected errors. On an ideal simulator, 100% of shots have syndrome \"00\"\n", @@ -515,12 +515,12 @@ "\n", "---\n", "\n", - "## But Wait — Next Hypothesis\n", + "## But Wait \u2014 Next Hypothesis\n", "\n", "> **H2 (for Experiment 2):** Everything above was on a **perfect\n", "> simulator** with zero noise. On a realistic noise model (mimicking\n", "> IBM Brisbane, 127 qubits, real error rates), the magic-state quality\n", - "> will degrade — but the degradation is **quantifiable**, and by tuning\n", + "> will degrade \u2014 but the degradation is **quantifiable**, and by tuning\n", "> circuit parameters we can recover significantly more magic than a\n", "> naive default configuration.\n", "\n", @@ -556,6 +556,12 @@ ], "outputs": [], "execution_count": null + }, + { + "cell_type": "markdown", + "id": "d129382e", + "source": "---\n## Navigation \u2014 Plan D\n\n**\u2192 Next: [Experiment 2 \u2014 How Much Magic Survives Noise?](experiment_2_noise.ipynb)**\n\n*\u2190 Back to [Start Here](../00_START_HERE.ipynb)*", + "metadata": {} } ] } \ No newline at end of file diff --git a/notebooks/plan_d/experiment_2_noise.ipynb b/notebooks/plan_d/experiment_2_noise.ipynb index 2dcf4a5..0ca33cb 100644 --- a/notebooks/plan_d/experiment_2_noise.ipynb +++ b/notebooks/plan_d/experiment_2_noise.ipynb @@ -41,7 +41,7 @@ "If all parameter choices gave similar results under noise, hand-tuning\n", "would be pointless. But if the score varies by $2\\text{--}5\\times$\n", "across the parameter space, then **finding the right settings is a\n", - "genuine optimisation problem** — one worth automating.\n", + "genuine optimisation problem** \u2014 one worth automating.\n", "\n", "### Claim\n", "\n", @@ -130,9 +130,9 @@ "metadata": {}, "source": [ "---\n", - "## Part 2: Testing Claim (1) — Noise Degrades the Magic\n", + "## Part 2: Testing Claim (1) \u2014 Noise Degrades the Magic\n", "\n", - "We load the `fake_brisbane` noise model — a realistic simulation of an\n", + "We load the `fake_brisbane` noise model \u2014 a realistic simulation of an\n", "IBM 127-qubit processor with measured gate errors, readout errors, and\n", "decoherence times." ] @@ -228,7 +228,7 @@ "metadata": {}, "source": [ "---\n", - "## Part 3: Testing Claim (2) — The Scoring Formula\n", + "## Part 3: Testing Claim (2) \u2014 The Scoring Formula\n", "\n", "The score must capture the three-way trade-off:\n", "\n", @@ -283,7 +283,7 @@ "metadata": {}, "source": [ "---\n", - "## Part 4: Testing Claim (3) — Parameter Choice Matters\n", + "## Part 4: Testing Claim (3) \u2014 Parameter Choice Matters\n", "\n", "We sweep the transpiler optimisation level (1, 2, 3) and measure how\n", "much the score varies. If the variation is small, optimisation is\n", @@ -388,16 +388,16 @@ "\n", "**Hypothesis H2 is confirmed.** The degradation is quantifiable, and\n", "parameter choice has a large effect on the score. Hand-tuning works but\n", - "is tedious — there are many more parameters to explore (encoder style,\n", + "is tedious \u2014 there are many more parameters to explore (encoder style,\n", "verification, layout method, routing, approximation degree...).\n", "\n", "---\n", "\n", "## Next Hypothesis\n", "\n", - "> **H3 (for Experiment 3):** An automated **ratchet** — an optimiser\n", + "> **H3 (for Experiment 3):** An automated **ratchet** \u2014 an optimiser\n", "> that only accepts improvements and extracts lessons from its own\n", - "> results — can discover better configurations than manual tuning. The\n", + "> results \u2014 can discover better configurations than manual tuning. The\n", "> configurations it finds will **generalise** to backends it has never\n", "> seen (transfer evaluation).\n", "\n", @@ -432,6 +432,12 @@ ], "outputs": [], "execution_count": null + }, + { + "cell_type": "markdown", + "id": "d67d8be7", + "source": "---\n## Navigation \u2014 Plan D\n\n**\u2192 Next: [Experiment 3 \u2014 Can a Machine Learn to Optimise?](experiment_3_optimisation.ipynb)**\n\n*\u2190 Previous: [Experiment 1 \u2014 Protection](experiment_1_protection.ipynb) \u00b7 [Start Here](../00_START_HERE.ipynb)*", + "metadata": {} } ] } \ No newline at end of file diff --git a/notebooks/plan_d/experiment_3_optimisation.ipynb b/notebooks/plan_d/experiment_3_optimisation.ipynb index 5ab6c30..56a57c8 100644 --- a/notebooks/plan_d/experiment_3_optimisation.ipynb +++ b/notebooks/plan_d/experiment_3_optimisation.ipynb @@ -26,7 +26,7 @@ "- **Experiment 1** proved the $[\\![4,2,2]\\!]$ encoding works: $W = 1.0$,\n", " all errors detected.\n", "- **Experiment 2** proved that noise degrades quality, but parameter\n", - " choice matters enormously — the score varies by $2\\text{--}5\\times$\n", + " choice matters enormously \u2014 the score varies by $2\\text{--}5\\times$\n", " across the parameter space.\n", "\n", "The manual sweep in Experiment 2 explored just one dimension (optimisation\n", @@ -36,9 +36,9 @@ "\n", "## Hypothesis\n", "\n", - "> **H3:** An automated ratchet — a monotonic optimiser that maintains\n", + "> **H3:** An automated ratchet \u2014 a monotonic optimiser that maintains\n", "> an incumbent (best-so-far) configuration and only accepts improvements\n", - "> — can discover better configurations than our manual sweep from\n", + "> \u2014 can discover better configurations than our manual sweep from\n", "> Experiment 2. Furthermore, the configurations it finds will\n", "> **generalise**: scoring well on a different backend (transfer\n", "> evaluation), proving it learned general principles rather than\n", @@ -101,8 +101,8 @@ "## Part 1: The Ratchet Mechanism\n", "\n", "The ratchet works like this:\n", - "1. Start with a **bootstrap incumbent** — a domain-expert guess.\n", - "2. Generate **challengers** — alternative configurations.\n", + "1. Start with a **bootstrap incumbent** \u2014 a domain-expert guess.\n", + "2. Generate **challengers** \u2014 alternative configurations.\n", "3. Score each challenger on the noisy simulator.\n", "4. **If** any challenger beats the incumbent, promote it.\n", "5. **If not**, the incumbent stays (monotonicity guarantee).\n", @@ -188,7 +188,7 @@ "metadata": {}, "source": [ "---\n", - "## Part 3: Testing Claim (1) — Running One Ratchet Step\n", + "## Part 3: Testing Claim (1) \u2014 Running One Ratchet Step\n", "\n", "We evaluate the incumbent and all challengers, then check: does any\n", "challenger win?" @@ -267,7 +267,7 @@ "metadata": {}, "source": [ "---\n", - "## Part 4: Testing Claims (2) & (3) — Full Rung with Lesson Extraction\n", + "## Part 4: Testing Claims (2) & (3) \u2014 Full Rung with Lesson Extraction\n", "\n", "Now we run the ratchet for a full rung: multiple steps until patience\n", "runs out. Then we extract lessons." @@ -376,7 +376,7 @@ "metadata": {}, "source": [ "---\n", - "## Part 5: Testing Claim (4) — Transfer Evaluation\n", + "## Part 5: Testing Claim (4) \u2014 Transfer Evaluation\n", "\n", "The ultimate test: does the winning configuration work on a **different**\n", "backend? If the score drops sharply, the ratchet overfitted to\n", @@ -394,10 +394,10 @@ "# Transfer test: re-evaluate the winner with fresh shot noise\n", "# This tests statistical robustness (different random seed)\n", "if winner_spec:\n", - " # Score 1 — already have this from the rung\n", + " # Score 1 \u2014 already have this from the rung\n", " original_score = winner_result.score\n", "\n", - " # Score 2 — fresh evaluation (different shot noise)\n", + " # Score 2 \u2014 fresh evaluation (different shot noise)\n", " transfer_result = executor.evaluate(winner_spec, rung_config)\n", " transfer_score = transfer_result.score\n", "\n", @@ -410,7 +410,7 @@ " print(f\"\\nTransfer {'GOOD' if abs(drop_pct) < 30 else 'POOR'}: \"\n", " f\"{'Configuration appears robust' if abs(drop_pct) < 30 else 'Possible overfitting to noise realisation'}\")\n", "else:\n", - " print(\"No winner found — cannot perform transfer test.\")" + " print(\"No winner found \u2014 cannot perform transfer test.\")" ], "outputs": [], "execution_count": null @@ -461,11 +461,11 @@ "| **3. Optimisation** | A machine can learn to do it better | **Yes:** monotonic improvement, lessons generalise |\n", "\n", "Starting from \"can we even protect a magic state?\" we built a system\n", - "that **teaches itself** how to prepare magic states optimally — and\n", + "that **teaches itself** how to prepare magic states optimally \u2014 and\n", "whose knowledge **transfers** to hardware it has never seen.\n", "\n", - "The pipeline is fully automated and reproducible: prepare → encode →\n", - "verify → score → optimise → learn → transfer." + "The pipeline is fully automated and reproducible: prepare \u2192 encode \u2192\n", + "verify \u2192 score \u2192 optimise \u2192 learn \u2192 transfer." ] }, { @@ -495,6 +495,12 @@ ], "outputs": [], "execution_count": null + }, + { + "cell_type": "markdown", + "id": "340e32fe", + "source": "---\n## You've completed Plan D!\n\nWant to explore the same material from a different angle? Try another plan:\n- [Plan A \u2014 Sequential](../plan_a/01_encoded_magic_state.ipynb) (step-by-step, three notebooks)\n- [Plan B \u2014 Spiral Notebook](../plan_b/spiral_notebook.ipynb) (three passes, increasing depth)\n- [Plan C \u2014 Parallel Tracks](../plan_c/00_dashboard.ipynb) (self-directed deep dives)\n\n*\u2190 Previous: [Experiment 2 \u2014 Noise](experiment_2_noise.ipynb) \u00b7 [Start Here](../00_START_HERE.ipynb)*", + "metadata": {} } ] } \ No newline at end of file diff --git a/tests/test_notebooks.py b/tests/test_notebooks.py index 88126fc..6a11fb3 100644 --- a/tests/test_notebooks.py +++ b/tests/test_notebooks.py @@ -21,6 +21,9 @@ NOTEBOOK_DIR = Path("notebooks") ALL_NOTEBOOKS = sorted(NOTEBOOK_DIR.rglob("*.ipynb")) +# Navigation-only notebooks (no code cells, no assessments) +NAVIGATION_NOTEBOOKS = {NOTEBOOK_DIR / "00_START_HERE.ipynb"} + # Execution timeout per cell (seconds) — noisy simulation cells can be slow CELL_TIMEOUT = 180 @@ -43,7 +46,9 @@ def test_notebook_valid_json(notebook_path): def test_notebook_has_code_cells(notebook_path): - """Every notebook has at least one code cell.""" + """Every content notebook has at least one code cell.""" + if notebook_path in NAVIGATION_NOTEBOOKS: + pytest.skip("navigation-only notebook") nb = nbformat.read(str(notebook_path), as_version=4) code_cells = [c for c in nb.cells if c.cell_type == "code"] assert len(code_cells) > 0, f"{notebook_path} has no code cells" @@ -99,6 +104,38 @@ def test_notebook_quiz_cells_have_section(notebook_path): ) +def test_start_here_exists_and_links_all_plans(): + """00_START_HERE.ipynb exists and links to all four plans.""" + start = NOTEBOOK_DIR / "00_START_HERE.ipynb" + assert start.exists(), "00_START_HERE.ipynb not found" + nb = nbformat.read(str(start), as_version=4) + text = "\n".join("".join(c.source) for c in nb.cells) + assert "Plan A" in text + assert "Plan B" in text + assert "Plan C" in text + assert "Plan D" in text + # Must link to each plan's entry notebook + assert "plan_a/01_encoded_magic_state.ipynb" in text + assert "plan_b/spiral_notebook.ipynb" in text + assert "plan_c/00_dashboard.ipynb" in text + assert "plan_d/experiment_1_protection.ipynb" in text + + +def test_every_notebook_has_navigation_footer(): + """Every content notebook ends with a navigation cell linking back to Start Here.""" + for nb_path in ALL_NOTEBOOKS: + if nb_path in NAVIGATION_NOTEBOOKS: + continue + nb = nbformat.read(str(nb_path), as_version=4) + # Check last 3 cells for a navigation markdown cell + tail_cells = nb.cells[-3:] + nav_found = any( + c.cell_type == "markdown" and "START_HERE" in "".join(c.source) + for c in tail_cells + ) + assert nav_found, f"{nb_path} has no navigation footer linking to START_HERE" + + def test_learning_objectives_document_exists(): """learning_objectives.md exists and covers all four plans.""" obj_path = NOTEBOOK_DIR / "learning_objectives.md" @@ -115,6 +152,8 @@ def test_every_notebook_has_assessments(): """Every notebook has at least one assessment cell (quiz/predict/reflect/order).""" assessment_pattern = re.compile(r"(quiz|predict_choice|reflect|order)\s*\(") for nb_path in ALL_NOTEBOOKS: + if nb_path in NAVIGATION_NOTEBOOKS: + continue nb = nbformat.read(str(nb_path), as_version=4) has_assessment = False for cell in nb.cells: