\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: