diff --git a/FIRST_RUN.md b/FIRST_RUN.md
index 5007845..aa7df37 100644
--- a/FIRST_RUN.md
+++ b/FIRST_RUN.md
@@ -38,7 +38,7 @@ Use this the first time you open the platform, or anytime you want a clean local
`START_HERE.ipynb -> COURSE_BLUEPRINT.ipynb -> foundations -> qiskit_engineering -> algorithms -> professional -> COURSE_COMPLETE.ipynb`
9. Inside every module, the required local flow is:
`lecture.ipynb -> lab.ipynb -> problems.ipynb -> studio.ipynb`
-10. Use `notebooks/reference/PROFESSIONAL_PATH.ipynb` only if you want the optional deeper mastery-map reference. It is not part of the mandatory first-pass path.
+10. Do not branch into side material during the first run. Stay on the guarded mainline until `COURSE_COMPLETE.ipynb`.
## Expected Local Behavior
diff --git a/README.md b/README.md
index 169f8f3..3e889f6 100644
--- a/README.md
+++ b/README.md
@@ -141,7 +141,7 @@ The rebuilt course is now organized into five bands:
The consumer entry point is [START_HERE.ipynb](/Users/oho/GitClone/CodexProjects/QuantumLearning/notebooks/START_HERE.ipynb).
The first serious orientation notebook after that is [COURSE_BLUEPRINT.ipynb](/Users/oho/GitClone/CodexProjects/QuantumLearning/notebooks/COURSE_BLUEPRINT.ipynb).
-The optional mastery-map reference lives at [PROFESSIONAL_PATH.ipynb](/Users/oho/GitClone/CodexProjects/QuantumLearning/notebooks/reference/PROFESSIONAL_PATH.ipynb).
+The consumer route is intentionally single-path. Follow the notebook handoff from `START_HERE` to `COURSE_COMPLETE` without branching into side material.
The full `Foundations` band is now rebuilt as module bundles:
@@ -170,6 +170,7 @@ The `Professional Design` band is now rebuilt as well:
- [Module 14: Capstone Circuit Design Review]()
The old single-notebook sequence is no longer part of the visible learner path. The canonical course path is the guarded `START_HERE -> COURSE_BLUEPRINT -> bundle mainline -> COURSE_COMPLETE` route.
+Additional internal reference material is intentionally hidden from the visible Jupyter root so the learner path stays unambiguous.
See [FIRST_RUN.md](/Users/oho/GitClone/CodexProjects/QuantumLearning/FIRST_RUN.md) for the short startup checklist.
See [OPERATIONS.md](/Users/oho/GitClone/CodexProjects/QuantumLearning/OPERATIONS.md) for setup on another Mac, monitoring, validation, and recovery.
diff --git a/configs/curriculum.toml b/configs/curriculum.toml
index e7ebad4..fd1844c 100644
--- a/configs/curriculum.toml
+++ b/configs/curriculum.toml
@@ -40,7 +40,7 @@ level = "orientation"
mode = "meta"
focus = "Understand the end-state of professional circuit design and identify present bottlenecks honestly."
status = "seeded"
-primary_notebook = "notebooks/reference/PROFESSIONAL_PATH.ipynb"
+primary_notebook = "notebooks/.reference/PROFESSIONAL_PATH.ipynb"
goals = [
"Understand the capstone role the course is targeting",
"See why design, verification, and hardware-awareness shape the earlier modules",
diff --git a/configs/mastery_blueprint.toml b/configs/mastery_blueprint.toml
index 03dba20..3ca1ed2 100644
--- a/configs/mastery_blueprint.toml
+++ b/configs/mastery_blueprint.toml
@@ -7,7 +7,7 @@ order = 0
id = "00-amateur-orientation"
title = "Amateur Orientation"
identity = "You are new enough that you cannot yet decompose circuit-design skill into subskills."
-anchor_notebook = "notebooks/reference/PROFESSIONAL_PATH.ipynb"
+anchor_notebook = "notebooks/.reference/PROFESSIONAL_PATH.ipynb"
must_master = [
"Understand the end-state the course is aiming at",
"See that the current intro notebooks are only the first layer of training",
diff --git a/notebooks/.reference/PROFESSIONAL_PATH.ipynb b/notebooks/.reference/PROFESSIONAL_PATH.ipynb
new file mode 100644
index 0000000..91f7e16
--- /dev/null
+++ b/notebooks/.reference/PROFESSIONAL_PATH.ipynb
@@ -0,0 +1,266 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "a5347f8d",
+ "metadata": {},
+ "source": [
+ "# Professional Path\n",
+ "\n",
+ "This notebook is the didactical map of the course. Its purpose is to answer the question: what must be learned, mastered, and defended at every stage if the final goal is genuine professional circuit design rather than superficial tool familiarity?\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "da0a486a",
+ "metadata": {},
+ "source": [
+ "## Optional Deep-Dive Reference\n",
+ "\n",
+ "This notebook is not part of the mandatory first-pass mainline. Use it when you want the full backward-designed mastery map in more depth. For the mainline flow, return to `../COURSE_BLUEPRINT.ipynb` and follow the next-notebook handoff there.\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "f8f39a46",
+ "metadata": {},
+ "source": [
+ "## The Backward-Design Principle\n",
+ "\n",
+ "The course is built backward from the terminal capability. That terminal capability is not “knows Qiskit,” not “can run example notebooks,” and not “has seen Bell states.” The terminal capability is: **independent hardware-aware circuit designer who can propose, compare, debug, and defend circuit architectures under constraints.**\n",
+ "\n",
+ "Once that target is stated clearly, the earlier stages stop being arbitrary. Beginner work is no longer something you “have to get through.” It becomes the deliberate installation of subskills without which later engineering judgment collapses. This is why the course begins with literacy, state reasoning, and measurement reasoning, even though the long-term target is much more advanced.\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "9b75dbba",
+ "metadata": {},
+ "source": [
+ "## The Stage Ladder\n",
+ "\n",
+ "The stage ladder should be read as a sequence of identities, not just a sequence of topics. At each stage, the question is: what kind of person are you becoming as a designer?\n",
+ "\n",
+ "You begin as someone who cannot yet parse a diagram confidently. Then you become someone who can narrate small circuits. Then someone who can predict state evolution. Then someone who can think in reusable blocks. Then someone who can synthesize designs, adapt them to constraints, reason about noise, review failures, and finally defend a capstone design. That is a dramatic transformation. The course should feel structured enough to support it.\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "d84237c3",
+ "metadata": {},
+ "source": [
+ "## Why The Ladder Is Emotional As Well As Technical\n",
+ "\n",
+ "Many learners experience a hidden emotional problem when studying advanced technical material: they cannot tell whether confusion means the subject is deep, the material is poorly taught, or they themselves are missing a prerequisite. A well-articulated stage ladder helps with that. It gives your confusion a location. If you cannot yet think in reusable subcircuits, that does not mean you are bad at quantum computing in general. It means you are at a specific stage boundary. That is a much healthier and more useful diagnosis.\n",
+ "\n",
+ "Good pedagogy respects this emotional dimension without becoming soft. The course still expects real work. But it tries to make that work legible. Legibility is one of the reasons the notebooks are becoming more text-heavy and more explicit about objectives, gates, and deliverables.\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "8817fc63",
+ "metadata": {},
+ "source": [
+ "## Why The Technical Notebooks Must Feel Denser Than Normal Tutorials\n",
+ "\n",
+ "A normal tutorial is optimized for quick success. That is useful when the goal is tool onboarding. It is not enough when the goal is professional circuit design. Professional growth requires deeper reading, repeated explanation, retrieval, self-diagnosis, and gradual comfort with ambiguity. That is why the notebooks are being rewritten with much heavier explanatory text than a standard example-driven notebook would contain.\n",
+ "\n",
+ "The text is not there because the code is weak. The text is there because code by itself often hides the conceptual burden. A line of code can be syntactically simple and conceptually deep. Without explanation, beginners tend to either overestimate or underestimate the importance of a line. Dense lecture writing helps calibrate attention. The quizzes and reflection prompts then test whether that calibration has stuck.\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "fa376509",
+ "metadata": {},
+ "source": [
+ "## Extended Path Notes I\n",
+ "\n",
+ "Backward-designed curriculum can sound abstract until you feel its practical force. The practical force is this: once the final professional role is named precisely, many tempting teaching decisions become obviously insufficient. If the final role is independent circuit designer under constraints, then a course built around isolated novelty examples is not enough. If the final role includes review, debugging, adaptation, and defense, then a course that measures only whether a notebook ran successfully is not enough. The capstone standard reaches backward and reshapes every earlier lesson.\n",
+ "\n",
+ "That reshaping is the real reason for the stage ladder. A stage is not just a folder label. It is a claim about what kind of judgment you should now possess. At the earliest stage, the judgment is local: can you read the circuit at all, and can you distinguish the important objects? At a slightly later stage, the judgment becomes dynamical: can you predict how state, basis, or measurement will respond to a design choice? Later still it becomes architectural: can you think in reusable blocks and structured experiments rather than flat strings of gates? Eventually it becomes strategic: can you compare alternatives under hardware, synthesis, and noise constraints? Seeing the path in those terms makes the course much more coherent.\n",
+ "\n",
+ "The stage ladder also protects against a common self-study trap: mistaking interest for preparation. You may be highly motivated by error correction, encoded circuits, or architecture papers, but if the earlier layers are weak then the advanced material becomes something you admire rather than something you can manipulate. Backward design does not deny ambition. It channels ambition into prerequisites. It says: if this advanced capability truly matters, which earlier capabilities must become automatic first? That question is often more valuable than asking which advanced topic looks exciting next.\n",
+ "\n",
+ "A well-designed apprenticeship path therefore does two things simultaneously. It raises the standard by naming a demanding final role, and it lowers confusion by decomposing that role into visible subskills. That combination is what the notebook is trying to provide.\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "a8ea786b",
+ "metadata": {},
+ "source": [
+ "## How To Use The Interactive Elements In The Technical Notebooks\n",
+ "\n",
+ "The quizzes are for retrieval. The editable labs are for manipulation. The reference tables are for code-to-diagram translation. The reflection boxes are for self-explanation. Those are different learning mechanisms, and they complement each other. If you use all four, the notebook behaves much more like a live teaching environment. If you use only one, the notebook shrinks back toward a static document.\n",
+ "\n",
+ "This matters because circuit design expertise is not a single skill. It is an integration of language, prediction, manipulation, and judgment. The platform therefore has to exercise all of those muscles, not merely one of them.\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "4777e27d",
+ "metadata": {},
+ "source": [
+ "## Extended Path Notes II\n",
+ "\n",
+ "There is also a deeper pedagogical principle behind the course structure: each stage changes the unit of thought. Beginners often think in lines of code. More developed learners begin to think in gates and local transformations. Later they think in subcircuits, patterns, invariants, and constraints. The jump to professional design happens when you can choose the right unit of thought for the problem in front of you and move up or down that ladder without getting lost. A course that only presents topics without highlighting these changing units of thought will often feel fragmented, even if its content is correct.\n",
+ "\n",
+ "The stage ladder is therefore not merely chronological. It is representational. It tells you what kind of object should now be salient to you. In an early notebook, a control-target relationship may be the key object. In a later notebook, the key object may be a synthesis pattern or a routing bottleneck. In a capstone, the key object may be a design tradeoff backed by evidence. By naming these shifts directly, the course helps you notice whether your internal way of seeing circuits is actually evolving.\n",
+ "\n",
+ "This is one reason the platform now emphasizes writing inside the notebooks. Written explanation can make invisible representational changes visible. If you compare how you describe a circuit at the start of the course to how you describe one several stages later, you should hear a difference. Early explanations will be local and syntactic. Later explanations should mention burden, purpose, constraint, degradation mode, or verification strategy. That change in language reflects a real change in cognition.\n",
+ "\n",
+ "The final reason to care about this path notebook is motivational in the precise sense, not the sentimental sense. Motivation becomes much stronger when effort is legible. If you know why a beginner notebook exists, you can invest in it honestly. If you do not know why it exists, you are tempted either to dismiss it or to drown in it. A visible staircase solves both problems by showing what each rung is preparing you to do next.\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "db931e50",
+ "metadata": {},
+ "source": [
+ "## The Real Backward Calculation\n",
+ "\n",
+ "If the capstone requires you to defend a design review, then you must already know how to compare candidates. If you must compare candidates, you must already know how to describe circuit structure. If you must describe circuit structure, you must already know how to read code and diagrams without confusion. If you must debug noise and constraint effects later, you must already have clean ideal intuitions now. This is the backward calculation in its simplest form: every advanced ability decomposes into earlier abilities, and every earlier ability must be trained deliberately if the final role is serious.\n",
+ "\n",
+ "That is why the course does not apologize for starting simply. The simplicity is not the endpoint. It is the first stable platform from which the later complexity can be climbed.\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "06d86ceb",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from pathlib import Path\n",
+ "import sys\n",
+ "\n",
+ "project_root = Path.cwd().resolve()\n",
+ "if project_root.name == \"notebooks\":\n",
+ " project_root = project_root.parent\n",
+ "\n",
+ "src_path = project_root / \"src\"\n",
+ "if str(src_path) not in sys.path:\n",
+ " sys.path.insert(0, str(src_path))\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "b639477b",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from quantum_learning import load_curriculum, load_mastery_blueprint\n",
+ "from quantum_learning.interactive import quiz_block\n",
+ "\n",
+ "blueprint = load_mastery_blueprint()\n",
+ "curriculum = load_curriculum()\n",
+ "\n",
+ "[(stage.order, stage.title, stage.identity, stage.gate) for stage in blueprint.stages]\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "b278b501",
+ "metadata": {},
+ "source": [
+ "## How To Use The Ladder\n",
+ "\n",
+ "Do not use the stage ladder as a motivational poster. Use it as a diagnostic instrument. Ask, at each stage, whether you can already perform the gate condition of that stage. If not, identify the missing subskill precisely. Vague self-descriptions like “I’m still a beginner” are not useful enough. More useful statements are things like “I cannot yet predict measurement-basis effects before running a circuit” or “I still flatten every design into raw gate sequences instead of reusable blocks.” The notebook is trying to push you toward that higher-resolution self-assessment.\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "846688a8",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "[(lesson.stage, lesson.title, lesson.deliverable, lesson.mastery_gate) for lesson in curriculum]\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "fe5b5282",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "quiz_block([{'prompt': 'Why is the course built backward from the capstone role?', 'options': ['Because advanced notebooks are easier to write first', 'Because the terminal professional capability determines which prerequisites actually matter', 'Because it removes the need for fundamentals'], 'correct_index': 1, 'explanation': 'Backward design tells us which earlier capabilities are genuinely necessary.'}, {'prompt': 'What is a mastery gate for?', 'options': ['To punish the learner for moving too slowly', 'To check whether a notebook file exists', 'To state the concrete ability that marks real progress'], 'correct_index': 2, 'explanation': 'A mastery gate defines the real competence to be owned.'}, {'prompt': 'What is the difference between a topic list and an apprenticeship path?', 'options': ['An apprenticeship path changes who the learner can be as a designer', 'A topic list always uses more notebooks', 'An apprenticeship path avoids all quizzes'], 'correct_index': 0, 'explanation': 'The apprenticeship model is about identity and capability growth, not just exposure.'}], heading='Professional Path Quiz A')\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "8f8df1e1",
+ "metadata": {},
+ "source": [
+ "## What You Should Feel After Reading This Notebook\n",
+ "\n",
+ "You should not feel that the path is easy. You should feel that the path is finally legible. A serious course does not pretend that mastery comes cheaply. It tries to make the staircase visible, so that each step can be attacked honestly and deliberately. That is the role of this notebook. Once you understand the staircase, the opening technical notebooks should feel like the first rungs of a long but coherent climb.\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "e7ce1be6",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from quantum_learning.interactive import reflection_box\n",
+ "\n",
+ "reflection_box(\"List the three most important professional subskills you are currently missing.\")\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "5e662da9",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "quiz_block([{'prompt': 'Which statement is closest to the terminal goal of the course?', 'options': ['Be able to run Qiskit notebooks locally', 'Become an independent hardware-aware circuit designer', 'Memorize the major gate families'], 'correct_index': 1, 'explanation': 'The course aims much higher than local execution literacy.'}, {'prompt': 'How should you interpret beginner notebooks after reading this notebook?', 'options': ['As trivial material to finish quickly', 'As prerequisites that install the language and mental models for later design work', 'As optional supplements that can be skipped'], 'correct_index': 1, 'explanation': 'The foundational notebooks are prerequisites for later engineering judgment.'}, {'prompt': 'What is the next action after this notebook?', 'options': ['Start the technical sequence and study it with prediction, quizzes, and editable labs', 'Jump directly to the capstone notebook', 'Ignore the quizzes because the text is enough'], 'correct_index': 0, 'explanation': 'The technical sequence is where the blueprint turns into training.'}], heading='Professional Path Quiz B')\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "457d5f43",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "quiz_block([{'prompt': 'What changes most across the course stages?', 'options': ['Only the number of gates in the examples', 'The unit of thought, from local syntax toward patterns, constraints, and tradeoffs', 'Only the notebook length'], 'correct_index': 1, 'explanation': 'The course is designed to change how you see and reason about circuits, not just how many examples you have seen.'}, {'prompt': 'Why is backward design valuable for an ambitious learner?', 'options': ['It translates ambition into visible prerequisite capabilities', 'It removes the need for staged practice', 'It guarantees that advanced material will feel easy'], 'correct_index': 0, 'explanation': 'Backward design turns a distant goal into a concrete prerequisite ladder.'}, {'prompt': 'What is a healthy interpretation of being at an early stage?', 'options': ['It means advanced work is irrelevant', 'It means you are missing specific subskills that can be named and trained', 'It means you should avoid self-explanation until later'], 'correct_index': 1, 'explanation': 'Stage language is meant to improve diagnosis, not to freeze identity.'}], heading='Professional Path Quiz C')\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "6f6791b1",
+ "metadata": {},
+ "source": [
+ "## Your Responsibility As The Learner\n",
+ "\n",
+ "The platform can provide structure, explanations, and interaction, but it cannot do the decisive act for you: honest engagement. That means answering the quizzes without peeking, editing the labs rather than merely admiring them, and writing reflections precise enough that another engineer could understand what you currently do and do not know. If you do that, the notebooks become apprenticeship tools. If you do not, they collapse back into passive reading material.\n"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "QuantumLearning (.venv)",
+ "language": "python",
+ "name": "quantum-learning"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.12.4"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/notebooks/COURSE_BLUEPRINT.ipynb b/notebooks/COURSE_BLUEPRINT.ipynb
index 1cbe9d9..14d25c7 100644
--- a/notebooks/COURSE_BLUEPRINT.ipynb
+++ b/notebooks/COURSE_BLUEPRINT.ipynb
@@ -238,11 +238,11 @@
"source": [
"## What To Open Next\n",
"\n",
- "The full technical mainline is now rebuilt. Start with **Principles and Circuit Literacy**, continue through the rest of the foundations modules, then move into **Circuit Construction and Analysis**, **Transpilation and Visualization**, and **Simulation and Noise Models**, then continue into **Deutsch Family and Oracle Thinking**, **Bernstein-Vazirani and Structured Oracles**, **QFT and Periodic Structure**, and **Grover and Amplitude Amplification**, and finally complete the professional band with **Qiskit Patterns and Workflow Design**, **Hardware-Aware Redesign Studio**, **Noise-Aware Verification and Mitigation**, and **Capstone Circuit Design Review**. Inside each module, read the lecture notebook first. Then move into the lab, then problems, then the studio. Do not reverse that order unless you are deliberately revising.\n",
+ "The full technical mainline is now rebuilt. Start with **Principles and Circuit Literacy**, continue through the rest of the foundations modules, then move into **Circuit Construction and Analysis**, **Transpilation and Visualization**, and **Simulation and Noise Models**, then continue into **Deutsch Family and Oracle Thinking**, **Bernstein-Vazirani and Structured Oracles**, **QFT and Periodic Structure**, and **Grover and Amplitude Amplification**, and finally complete the professional band with **Qiskit Patterns and Workflow Design**, **Hardware-Aware Redesign Studio**, **Noise-Aware Verification and Mitigation**, and **Capstone Circuit Design Review**. Inside each module, read the lecture notebook first. Then move into the lab, then problems, then the studio. Keep that order.\n",
"\n",
"The sequence matters. If you jump straight into the studio, you may produce activity without comprehension. If you stop after the lecture, you may feel recognition without control. The four-notebook loop is the point.\n"
],
- "id": "492e1a52"
+ "id": "12532442"
},
{
"cell_type": "code",
@@ -312,11 +312,11 @@
"4. Repeat the same loop in `module_03_gates_and_measurement`\n",
"5. Continue with `qiskit_engineering/module_01_circuit_construction_and_analysis`\n",
"6. Then complete `module_02_transpilation_and_visualization` and `module_03_simulation_and_noise_models`\n",
- "7. Only then return to the later single-notebook materials as transition content\n",
+ "7. Continue following the explicit next-notebook handoff until `COURSE_COMPLETE.ipynb`\n",
"\n",
"That is the new mainline.\n"
],
- "id": "45b6af37"
+ "id": "0e6ec22f"
},
{
"cell_type": "markdown",
@@ -327,9 +327,9 @@
"\n",
"Next notebook: [Principles and Circuit Literacy Lecture](foundations/module_01_principles_and_circuit_literacy/lecture.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "a9330e49"
+ "id": "8c373b9b"
}
],
"metadata": {
diff --git a/notebooks/COURSE_COMPLETE.ipynb b/notebooks/COURSE_COMPLETE.ipynb
index 431b7ab..1b44fde 100644
--- a/notebooks/COURSE_COMPLETE.ipynb
+++ b/notebooks/COURSE_COMPLETE.ipynb
@@ -48,11 +48,11 @@
"## What To Do Next\n",
"\n",
"1. Revisit the hardest studio notebooks and tighten your written design judgements.\n",
- "2. Use `notebooks/reference/PROFESSIONAL_PATH.ipynb` if you want the long-range mastery map again.\n",
- "3. Extend the capstone with your own circuit family and defend the design choices in writing.\n",
+ "2. Extend the capstone with your own circuit family and defend the design choices in writing.\n",
+ "3. Repeat a full module bundle deliberately only when you know exactly which skill you are repairing.\n",
"4. Only after that, add external hardware targets or new research notebooks.\n"
],
- "id": "db6bb597"
+ "id": "5f5a5470"
},
{
"cell_type": "markdown",
@@ -73,9 +73,9 @@
"\n",
"Next notebook: none. This notebook closes the mainline course.\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "This is the end of the guarded mainline route.\n"
],
- "id": "7ab33e0e"
+ "id": "628143ad"
}
],
"metadata": {
diff --git a/notebooks/START_HERE.ipynb b/notebooks/START_HERE.ipynb
index 5263493..77009d7 100644
--- a/notebooks/START_HERE.ipynb
+++ b/notebooks/START_HERE.ipynb
@@ -2,13 +2,13 @@
"cells": [
{
"cell_type": "markdown",
- "id": "fa7f5f3a",
"metadata": {},
"source": [
"# Start Here\n",
"\n",
- "This notebook is the only supported starting point for the course. Do not guess where to begin from the filesystem. Start here, run the cells in order, and follow the next-notebook handoff at the end. Its job is to tell you how to use the platform so that the later notebooks do not feel like disconnected technical fragments. The platform is intended to function like a notebook-based textbook plus lab manual plus design studio. If you only click through cells, you will get much less from it than the structure is designed to offer.\n"
- ]
+ "This notebook is the only supported starting point for the course. Its job is to tell you how to use the platform so that the later notebooks do not feel like disconnected technical fragments. The platform is intended to function like a notebook-based textbook plus lab manual plus design studio. If you only click through cells, you will get much less from it than the structure is designed to offer.\n"
+ ],
+ "id": "6f546318"
},
{
"cell_type": "markdown",
@@ -29,7 +29,6 @@
},
{
"cell_type": "markdown",
- "id": "dba3362b",
"metadata": {},
"source": [
"## How To Read The Course\n",
@@ -43,33 +42,23 @@
"- a mastery gate tells you what ability you are actually supposed to own\n",
"\n",
"This is deliberate. The course is trying to train design reasoning, not just tool familiarity.\n"
- ]
+ ],
+ "id": "dba3362b"
},
{
"cell_type": "markdown",
- "id": "b94b4649",
"metadata": {},
"source": [
"## What To Do In Your First Session\n",
"\n",
- "Read the rest of this notebook, then open `COURSE_BLUEPRINT.ipynb`. That is the first serious orientation notebook in the enforced mainline path. After that, follow the notebook-to-notebook handoff from inside the notebooks themselves instead of guessing from the filesystem.\n",
- "\n",
- "If you later want the deeper mastery-map background, use `reference/PROFESSIONAL_PATH.ipynb` as an optional side reference. It is not the next required notebook in the first-pass learner journey.\n"
- ]
+ "Read the rest of this notebook, then open `COURSE_BLUEPRINT.ipynb`. That is the first serious orientation notebook in the enforced mainline path. After that, follow the notebook-to-notebook handoff from inside the notebooks themselves instead of guessing from the filesystem.\n"
+ ],
+ "id": "24589eae"
},
{
"cell_type": "code",
- "execution_count": 2,
- "id": "933dd369",
- "metadata": {
- "execution": {
- "iopub.execute_input": "2026-04-15T14:34:34.620068Z",
- "iopub.status.busy": "2026-04-15T14:34:34.619450Z",
- "iopub.status.idle": "2026-04-15T14:34:34.628343Z",
- "shell.execute_reply": "2026-04-15T14:34:34.627170Z",
- "shell.execute_reply.started": "2026-04-15T14:34:34.620017Z"
- }
- },
+ "execution_count": null,
+ "metadata": {},
"outputs": [],
"source": [
"from pathlib import Path\n",
@@ -82,35 +71,14 @@
"src_path = project_root / \"src\"\n",
"if str(src_path) not in sys.path:\n",
" sys.path.insert(0, str(src_path))\n"
- ]
+ ],
+ "id": "933dd369"
},
{
"cell_type": "code",
- "execution_count": 3,
- "id": "82d23cb8",
- "metadata": {
- "execution": {
- "iopub.execute_input": "2026-04-15T14:34:35.433072Z",
- "iopub.status.busy": "2026-04-15T14:34:35.432515Z",
- "iopub.status.idle": "2026-04-15T14:34:36.146503Z",
- "shell.execute_reply": "2026-04-15T14:34:36.146093Z",
- "shell.execute_reply.started": "2026-04-15T14:34:35.433024Z"
- }
- },
- "outputs": [
- {
- "data": {
- "text/plain": [
- "{'terminal_role': 'Independent hardware-aware quantum circuit designer',\n",
- " 'stage_count': 10,\n",
- " 'lesson_count': 16}"
- ]
- },
- "execution_count": 3,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
"source": [
"from quantum_learning import load_curriculum, load_mastery_blueprint\n",
"from quantum_learning.interactive import quiz_block\n",
@@ -123,11 +91,11 @@
" \"stage_count\": len(blueprint.stages),\n",
" \"lesson_count\": len(curriculum),\n",
"}\n"
- ]
+ ],
+ "id": "82d23cb8"
},
{
"cell_type": "markdown",
- "id": "5a3b7b62",
"metadata": {},
"source": [
"## The Structure You Are Entering\n",
@@ -135,11 +103,11 @@
"The course does not imagine that you become a master circuit designer by finishing five gentle notebooks. It imagines that you become a master only after passing through several distinct identities: beginner, circuit-literate builder, state-and-measurement thinker, composable designer, synthesis engineer, hardware-aware optimizer, verifier, and finally capstone designer.\n",
"\n",
"That sequence matters because expertise is layered. Each stage gives you a new way to look at circuits. At the beginning you mostly see syntax. Then you start seeing processes. Later you start seeing patterns. Later still you see constraints, tradeoffs, failure modes, and review language. This course is trying to make that transformation explicit rather than accidental.\n"
- ]
+ ],
+ "id": "5a3b7b62"
},
{
"cell_type": "markdown",
- "id": "17d64417",
"metadata": {},
"source": [
"## Why The Platform Is Becoming More Literary And More Interactive\n",
@@ -147,11 +115,11 @@
"You asked for accompanying literature inside the notebooks because opening bare code felt disorienting. That diagnosis was correct. A serious self-study platform cannot assume that the learner already knows which sentence, diagram, or output matters most. The platform therefore now treats writing as part of the engineering infrastructure. The text tells you what problem is being solved, what distinction matters, what confusion to avoid, and what ability the notebook is meant to install.\n",
"\n",
"But text alone is not enough either. Good pedagogy alternates explanation with retrieval and manipulation. That is why the notebooks now combine longer lecture notes with multiple choice quizzes and editable labs. Reading tells you what the designers want you to notice. Quizzes test whether that notice has become recall. Editable labs test whether recall survives contact with variation. This is the core instructional triangle of the platform.\n"
- ]
+ ],
+ "id": "17d64417"
},
{
"cell_type": "markdown",
- "id": "c736476c",
"metadata": {},
"source": [
"## Extended Orientation I\n",
@@ -163,11 +131,11 @@
"The most useful study rhythm is not complicated, but it does require discipline. Read a section of prose. Pause and summarize it in your own words. Predict what the next circuit cell or analysis cell is going to show. Run the cell. Compare the result to your prediction. If the result surprises you, treat that surprise as data about your mental model. Then answer the quiz or reflection prompt honestly. This rhythm is slower than passive clicking, but it produces much stronger learning because every step forces interpretation.\n",
"\n",
"Another important point is that the notebooks are not trying to entertain you into mastery. They are trying to train you into mastery. Training is necessarily repetitive. It comes back to central ideas multiple times because the point is not novelty. The point is control. By the time you leave a notebook, the main idea should feel easier to explain, easier to manipulate, and easier to recognize in a new setting. If that is happening, then the notebook is doing its job.\n"
- ]
+ ],
+ "id": "c736476c"
},
{
"cell_type": "markdown",
- "id": "4c77da02",
"metadata": {},
"source": [
"## How To Judge Whether A Notebook Worked\n",
@@ -175,11 +143,11 @@
"The right metric is not “did I finish the notebook?” The right metric is “what can I now explain or modify that I could not explain or modify before?” That is why each notebook has a mastery gate. The gate is the honest end-point of the lesson. If the gate still feels unstable, you have not failed; you have simply learned what still needs consolidation.\n",
"\n",
"Use the reflection prompts seriously. They are there to turn vague discomfort into precise diagnosis. “I am lost” is not yet a useful learning statement. “I can draw the circuit, but I still cannot explain why that gate changes the support pattern” is useful. The course is trying to move you from the first kind of statement to the second.\n"
- ]
+ ],
+ "id": "4c77da02"
},
{
"cell_type": "markdown",
- "id": "0bd9fb0c",
"metadata": {},
"source": [
"## What To Do When You Feel Lost\n",
@@ -187,11 +155,11 @@
"Feeling lost is not itself a problem. Staying vague about why you feel lost is the problem. The platform is trying to give you tools for that diagnosis. If a notebook overwhelms you, stop and ask: is the problem vocabulary, code syntax, diagram reading, prediction, or interpretation? Those are different failures and they need different repairs. A well-designed notebook should help you name which one is happening.\n",
"\n",
"This is also why the notebooks now include reflection boxes. They are not decorative journaling. They are structured places to write the sentence you currently cannot yet say fluently. Often the missing sentence is the actual missing concept. Once you can name the unstable point, later study becomes much more efficient.\n"
- ]
+ ],
+ "id": "0bd9fb0c"
},
{
"cell_type": "markdown",
- "id": "abc4a853",
"metadata": {},
"source": [
"## Extended Orientation II\n",
@@ -203,11 +171,11 @@
"You should also know how to respond when the notebook feels too dense. Do not immediately interpret density as failure. Instead, diagnose the exact friction point. Are you missing vocabulary? Are you unable to track time ordering in the diagram? Are you confused by what is being measured versus what is being transformed? Are you able to repeat the explanation while reading it but not from memory? Each of those failures points to a different repair strategy. A strong learner does not merely persist emotionally. A strong learner improves the resolution of the diagnosis.\n",
"\n",
"Finally, treat the early notebooks with respect. Foundational topics are not “baby material” if they are the place where your language, visual literacy, and explanatory habits are being formed. Professional designers are often distinguished less by secret advanced tricks than by extraordinary cleanliness in fundamentals. That is one of the governing assumptions of the whole platform.\n"
- ]
+ ],
+ "id": "abc4a853"
},
{
"cell_type": "markdown",
- "id": "0ac343c5",
"metadata": {},
"source": [
"## Why The Platform Uses Multiple Choice Quizzes\n",
@@ -215,131 +183,60 @@
"Many technically strong learners underestimate the value of retrieval. They assume that because a paragraph made sense while reading it, the idea is already stable. It usually is not. A multiple choice question is useful not because it is the highest form of assessment, but because it exposes whether the concept is available without the notebook whispering the answer at you.\n",
"\n",
"That matters especially in self-study. A quiz can reveal confusion immediately and cheaply. If you miss a question, the point is not that you failed. The point is that the notebook just showed you exactly where the explanation must be reread or rephrased.\n"
- ]
+ ],
+ "id": "0ac343c5"
},
{
"cell_type": "code",
- "execution_count": 5,
- "id": "4e8fffa8",
- "metadata": {
- "execution": {
- "iopub.execute_input": "2026-04-15T14:35:54.633507Z",
- "iopub.status.busy": "2026-04-15T14:35:54.633156Z",
- "iopub.status.idle": "2026-04-15T14:35:54.660295Z",
- "shell.execute_reply": "2026-04-15T14:35:54.659570Z",
- "shell.execute_reply.started": "2026-04-15T14:35:54.633480Z"
- }
- },
- "outputs": [
- {
- "data": {
- "application/vnd.jupyter.widget-view+json": {
- "model_id": "3a418bcf95e5457ab718080ec4ee7a0c",
- "version_major": 2,
- "version_minor": 0
- },
- "text/plain": [
- "VBox(children=(HTML(value=\"Start Here Quiz
\"), VBox(children=(HTML(value='…"
- ]
- },
- "execution_count": 5,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
"source": [
"quiz_block([{'prompt': 'What is the main purpose of the markdown in these notebooks?', 'options': ['It is mostly decorative context around the code', 'It carries part of the actual course content and must be studied', 'It exists only so the notebooks look more polished'], 'correct_index': 1, 'explanation': 'The markdown is part of the teaching, not decoration.'}, {'prompt': 'Why does the course emphasize prediction before execution?', 'options': ['Because prediction is the fastest way to run a notebook', 'Because prediction reveals whether you actually understand the circuit', 'Because prediction removes the need for simulation'], 'correct_index': 1, 'explanation': 'Prediction turns passive reading into active reasoning.'}, {'prompt': 'What should you open immediately after this notebook?', 'options': ['The capstone review notebook', 'The README again', 'COURSE_BLUEPRINT.ipynb'], 'correct_index': 2, 'explanation': 'Course Blueprint is the next required notebook in the guarded mainline path.'}], heading='Start Here Quiz')\n"
- ]
+ ],
+ "id": "4e8fffa8"
},
{
"cell_type": "code",
- "execution_count": 7,
- "id": "889b848f",
- "metadata": {
- "execution": {
- "iopub.execute_input": "2026-04-15T14:36:39.557051Z",
- "iopub.status.busy": "2026-04-15T14:36:39.556610Z",
- "iopub.status.idle": "2026-04-15T14:36:39.584919Z",
- "shell.execute_reply": "2026-04-15T14:36:39.583365Z",
- "shell.execute_reply.started": "2026-04-15T14:36:39.557020Z"
- }
- },
- "outputs": [
- {
- "data": {
- "application/vnd.jupyter.widget-view+json": {
- "model_id": "e8586bf43d9c415297841e498f0d3a46",
- "version_major": 2,
- "version_minor": 0
- },
- "text/plain": [
- "VBox(children=(HTML(value=\"Start Here Quiz B
\"), VBox(children=(HTML(value…"
- ]
- },
- "execution_count": 7,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
"source": [
"quiz_block([{'prompt': 'What should you do if a notebook feels dense or overwhelming?', 'options': ['Skim the markdown and hope later notebooks clarify it', 'Diagnose the exact friction point and use the interactive elements to test that weakness', 'Skip directly to advanced notebooks with more exciting topics'], 'correct_index': 1, 'explanation': 'Precise diagnosis is much more useful than vague frustration.'}, {'prompt': 'Why are editable labs important in this course?', 'options': ['They test whether your explanation survives deliberate circuit changes', 'They mainly make the notebooks look modern', 'They replace the need for written explanation'], 'correct_index': 0, 'explanation': 'Manipulation is one of the main ways the notebooks check for real understanding.'}, {'prompt': 'What does the course expect from foundational notebooks?', 'options': ['Fast completion', 'Respectful, detailed study because fundamentals shape later design judgment', 'Minimal attention because they are mostly syntax'], 'correct_index': 1, 'explanation': 'The course treats fundamentals as the place where professional habits begin.'}], heading='Start Here Quiz B')\n"
- ]
+ ],
+ "id": "889b848f"
},
{
"cell_type": "code",
- "execution_count": 8,
- "id": "acfc8a04",
- "metadata": {
- "execution": {
- "iopub.execute_input": "2026-04-15T14:36:43.068505Z",
- "iopub.status.busy": "2026-04-15T14:36:43.068171Z",
- "iopub.status.idle": "2026-04-15T14:36:43.078972Z",
- "shell.execute_reply": "2026-04-15T14:36:43.077738Z",
- "shell.execute_reply.started": "2026-04-15T14:36:43.068480Z"
- }
- },
- "outputs": [
- {
- "data": {
- "application/vnd.jupyter.widget-view+json": {
- "model_id": "c51a760b7a6b44529de7172d0ded66eb",
- "version_major": 2,
- "version_minor": 0
- },
- "text/plain": [
- "VBox(children=(HTML(value='Write down what you expect a professional circuit designer to be able to do that…"
- ]
- },
- "execution_count": 8,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
"source": [
"from quantum_learning.interactive import reflection_box\n",
"\n",
"reflection_box(\"Write down what you expect a professional circuit designer to be able to do that you cannot yet do.\")\n"
- ]
+ ],
+ "id": "acfc8a04"
},
{
"cell_type": "markdown",
- "id": "480ab187",
"metadata": {},
"source": [
"## How To Continue After This Notebook\n",
"\n",
- "After this notebook, open `COURSE_BLUEPRINT.ipynb`. Then begin `foundations/module_01_principles_and_circuit_literacy/lecture.ipynb`. If you want the deeper mastery map later, use `reference/PROFESSIONAL_PATH.ipynb` as an optional side reference. Read the text, answer the quizzes, edit the circuit lab, and use the reflection prompts. That full cycle is now the expected workflow. If you only sample one of those pieces, you are no longer using the notebook in the way it was designed to teach.\n"
- ]
+ "After this notebook, open `COURSE_BLUEPRINT.ipynb`. Then follow the explicit notebook-to-notebook handoff through the mainline path. Read the text, answer the quizzes, edit the circuit lab, and use the reflection prompts. That full cycle is now the expected workflow. If you only sample one of those pieces, you are no longer using the notebook in the way it was designed to teach.\n"
+ ],
+ "id": "4309c127"
},
{
"cell_type": "markdown",
- "id": "def4360d",
"metadata": {},
"source": [
"## Final Instruction\n",
"\n",
- "Open `COURSE_BLUEPRINT.ipynb` next. Then follow the mainline handoff from notebook to notebook. `reference/PROFESSIONAL_PATH.ipynb` is optional and not required for the first pass. The notebooks are now written to be read in detail, quizzed actively, and modified interactively. That is the intended workflow.\n"
- ]
+ "Open `COURSE_BLUEPRINT.ipynb` next. Then follow the mainline handoff from notebook to notebook. Do not branch away from that route on the first run. The notebooks are now written to be read in detail, quizzed actively, and modified interactively. That is the intended workflow.\n"
+ ],
+ "id": "0633a838"
},
{
"cell_type": "markdown",
@@ -350,17 +247,9 @@
"\n",
"Next notebook: [Course Blueprint](COURSE_BLUEPRINT.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "7efd4648"
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "id": "b2f4a5e3",
- "metadata": {},
- "outputs": [],
- "source": []
+ "id": "4f3bced3"
}
],
"metadata": {
@@ -370,16 +259,8 @@
"name": "quantum-learning"
},
"language_info": {
- "codemirror_mode": {
- "name": "ipython",
- "version": 3
- },
- "file_extension": ".py",
- "mimetype": "text/x-python",
"name": "python",
- "nbconvert_exporter": "python",
- "pygments_lexer": "ipython3",
- "version": "3.12.4"
+ "version": "3.12"
}
},
"nbformat": 4,
diff --git a/notebooks/algorithms/module_01_deutsch_family/lab.ipynb b/notebooks/algorithms/module_01_deutsch_family/lab.ipynb
index 0dcaf32..3920a07 100644
--- a/notebooks/algorithms/module_01_deutsch_family/lab.ipynb
+++ b/notebooks/algorithms/module_01_deutsch_family/lab.ipynb
@@ -347,9 +347,9 @@
"\n",
"Next notebook: [Deutsch Family and Oracle Thinking Problems](problems.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "a566b478"
+ "id": "5d9c18ca"
}
],
"metadata": {
diff --git a/notebooks/algorithms/module_01_deutsch_family/lecture.ipynb b/notebooks/algorithms/module_01_deutsch_family/lecture.ipynb
index a16b2b2..bc270a2 100644
--- a/notebooks/algorithms/module_01_deutsch_family/lecture.ipynb
+++ b/notebooks/algorithms/module_01_deutsch_family/lecture.ipynb
@@ -299,9 +299,9 @@
"\n",
"Next notebook: [Deutsch Family and Oracle Thinking Lab](lab.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "3bae879b"
+ "id": "9469d84a"
}
],
"metadata": {
diff --git a/notebooks/algorithms/module_01_deutsch_family/problems.ipynb b/notebooks/algorithms/module_01_deutsch_family/problems.ipynb
index 56d2a2e..c3bb8e1 100644
--- a/notebooks/algorithms/module_01_deutsch_family/problems.ipynb
+++ b/notebooks/algorithms/module_01_deutsch_family/problems.ipynb
@@ -251,9 +251,9 @@
"\n",
"Next notebook: [Deutsch Family and Oracle Thinking Studio](studio.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "947f3e61"
+ "id": "6d2876d3"
}
],
"metadata": {
diff --git a/notebooks/algorithms/module_01_deutsch_family/studio.ipynb b/notebooks/algorithms/module_01_deutsch_family/studio.ipynb
index 0d93f73..3faffb4 100644
--- a/notebooks/algorithms/module_01_deutsch_family/studio.ipynb
+++ b/notebooks/algorithms/module_01_deutsch_family/studio.ipynb
@@ -264,9 +264,9 @@
"\n",
"Next notebook: [Bernstein-Vazirani and Structured Oracles Lecture](../module_02_bernstein_vazirani/lecture.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "128e2b5b"
+ "id": "f87f3f82"
}
],
"metadata": {
diff --git a/notebooks/algorithms/module_02_bernstein_vazirani/lab.ipynb b/notebooks/algorithms/module_02_bernstein_vazirani/lab.ipynb
index 4fc4f1c..7609715 100644
--- a/notebooks/algorithms/module_02_bernstein_vazirani/lab.ipynb
+++ b/notebooks/algorithms/module_02_bernstein_vazirani/lab.ipynb
@@ -359,9 +359,9 @@
"\n",
"Next notebook: [Bernstein-Vazirani and Structured Oracles Problems](problems.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "8429e40b"
+ "id": "e17bab3b"
}
],
"metadata": {
diff --git a/notebooks/algorithms/module_02_bernstein_vazirani/lecture.ipynb b/notebooks/algorithms/module_02_bernstein_vazirani/lecture.ipynb
index 99dd109..b53548d 100644
--- a/notebooks/algorithms/module_02_bernstein_vazirani/lecture.ipynb
+++ b/notebooks/algorithms/module_02_bernstein_vazirani/lecture.ipynb
@@ -295,9 +295,9 @@
"\n",
"Next notebook: [Bernstein-Vazirani and Structured Oracles Lab](lab.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "883abd8f"
+ "id": "0c79e4b9"
}
],
"metadata": {
diff --git a/notebooks/algorithms/module_02_bernstein_vazirani/problems.ipynb b/notebooks/algorithms/module_02_bernstein_vazirani/problems.ipynb
index 7cfc1cf..1722ff9 100644
--- a/notebooks/algorithms/module_02_bernstein_vazirani/problems.ipynb
+++ b/notebooks/algorithms/module_02_bernstein_vazirani/problems.ipynb
@@ -251,9 +251,9 @@
"\n",
"Next notebook: [Bernstein-Vazirani and Structured Oracles Studio](studio.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "c236caa2"
+ "id": "07ccdbad"
}
],
"metadata": {
diff --git a/notebooks/algorithms/module_02_bernstein_vazirani/studio.ipynb b/notebooks/algorithms/module_02_bernstein_vazirani/studio.ipynb
index 3e9b71b..8f48ccf 100644
--- a/notebooks/algorithms/module_02_bernstein_vazirani/studio.ipynb
+++ b/notebooks/algorithms/module_02_bernstein_vazirani/studio.ipynb
@@ -264,9 +264,9 @@
"\n",
"Next notebook: [QFT and Periodic Structure Lecture](../module_03_qft/lecture.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "35df0be1"
+ "id": "e6bbfa45"
}
],
"metadata": {
diff --git a/notebooks/algorithms/module_03_qft/lab.ipynb b/notebooks/algorithms/module_03_qft/lab.ipynb
index b358d6f..b4cf76f 100644
--- a/notebooks/algorithms/module_03_qft/lab.ipynb
+++ b/notebooks/algorithms/module_03_qft/lab.ipynb
@@ -348,9 +348,9 @@
"\n",
"Next notebook: [QFT and Periodic Structure Problems](problems.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "3e104134"
+ "id": "b487a1ce"
}
],
"metadata": {
diff --git a/notebooks/algorithms/module_03_qft/lecture.ipynb b/notebooks/algorithms/module_03_qft/lecture.ipynb
index ca10c65..4de486b 100644
--- a/notebooks/algorithms/module_03_qft/lecture.ipynb
+++ b/notebooks/algorithms/module_03_qft/lecture.ipynb
@@ -299,9 +299,9 @@
"\n",
"Next notebook: [QFT and Periodic Structure Lab](lab.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "9c17c135"
+ "id": "30b64964"
}
],
"metadata": {
diff --git a/notebooks/algorithms/module_03_qft/problems.ipynb b/notebooks/algorithms/module_03_qft/problems.ipynb
index 4c0d575..6a4d1b1 100644
--- a/notebooks/algorithms/module_03_qft/problems.ipynb
+++ b/notebooks/algorithms/module_03_qft/problems.ipynb
@@ -251,9 +251,9 @@
"\n",
"Next notebook: [QFT and Periodic Structure Studio](studio.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "595bed95"
+ "id": "b721bf5e"
}
],
"metadata": {
diff --git a/notebooks/algorithms/module_03_qft/studio.ipynb b/notebooks/algorithms/module_03_qft/studio.ipynb
index 89d7c0f..4b7a554 100644
--- a/notebooks/algorithms/module_03_qft/studio.ipynb
+++ b/notebooks/algorithms/module_03_qft/studio.ipynb
@@ -264,9 +264,9 @@
"\n",
"Next notebook: [Grover and Amplitude Amplification Lecture](../module_04_grover/lecture.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "d9a014f4"
+ "id": "90c7710c"
}
],
"metadata": {
diff --git a/notebooks/algorithms/module_04_grover/lab.ipynb b/notebooks/algorithms/module_04_grover/lab.ipynb
index dced4dc..0401290 100644
--- a/notebooks/algorithms/module_04_grover/lab.ipynb
+++ b/notebooks/algorithms/module_04_grover/lab.ipynb
@@ -361,9 +361,9 @@
"\n",
"Next notebook: [Grover and Amplitude Amplification Problems](problems.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "a3e60a4b"
+ "id": "a313251e"
}
],
"metadata": {
diff --git a/notebooks/algorithms/module_04_grover/lecture.ipynb b/notebooks/algorithms/module_04_grover/lecture.ipynb
index 361e88c..ba33aaf 100644
--- a/notebooks/algorithms/module_04_grover/lecture.ipynb
+++ b/notebooks/algorithms/module_04_grover/lecture.ipynb
@@ -314,9 +314,9 @@
"\n",
"Next notebook: [Grover and Amplitude Amplification Lab](lab.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "b01737b5"
+ "id": "2816fee7"
}
],
"metadata": {
diff --git a/notebooks/algorithms/module_04_grover/problems.ipynb b/notebooks/algorithms/module_04_grover/problems.ipynb
index 6ea511c..8b42fc5 100644
--- a/notebooks/algorithms/module_04_grover/problems.ipynb
+++ b/notebooks/algorithms/module_04_grover/problems.ipynb
@@ -251,9 +251,9 @@
"\n",
"Next notebook: [Grover and Amplitude Amplification Studio](studio.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "3756fd18"
+ "id": "4dbcccc8"
}
],
"metadata": {
diff --git a/notebooks/algorithms/module_04_grover/studio.ipynb b/notebooks/algorithms/module_04_grover/studio.ipynb
index b978aa2..5c3ad41 100644
--- a/notebooks/algorithms/module_04_grover/studio.ipynb
+++ b/notebooks/algorithms/module_04_grover/studio.ipynb
@@ -264,9 +264,9 @@
"\n",
"Next notebook: [Qiskit Patterns and Workflow Design Lecture](../../professional/module_01_qiskit_patterns/lecture.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "acb30432"
+ "id": "57697751"
}
],
"metadata": {
diff --git a/notebooks/foundations/module_01_principles_and_circuit_literacy/lab.ipynb b/notebooks/foundations/module_01_principles_and_circuit_literacy/lab.ipynb
index 2e8893d..fed3df4 100644
--- a/notebooks/foundations/module_01_principles_and_circuit_literacy/lab.ipynb
+++ b/notebooks/foundations/module_01_principles_and_circuit_literacy/lab.ipynb
@@ -344,9 +344,9 @@
"\n",
"Next notebook: [Principles and Circuit Literacy Problems](problems.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "5096246f"
+ "id": "5175655e"
}
],
"metadata": {
diff --git a/notebooks/foundations/module_01_principles_and_circuit_literacy/lecture.ipynb b/notebooks/foundations/module_01_principles_and_circuit_literacy/lecture.ipynb
index 0a942f6..783b4ca 100644
--- a/notebooks/foundations/module_01_principles_and_circuit_literacy/lecture.ipynb
+++ b/notebooks/foundations/module_01_principles_and_circuit_literacy/lecture.ipynb
@@ -335,9 +335,9 @@
"\n",
"Next notebook: [Principles and Circuit Literacy Lab](lab.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "966208c8"
+ "id": "20e0cd40"
}
],
"metadata": {
diff --git a/notebooks/foundations/module_01_principles_and_circuit_literacy/problems.ipynb b/notebooks/foundations/module_01_principles_and_circuit_literacy/problems.ipynb
index a54c9c1..dff9ede 100644
--- a/notebooks/foundations/module_01_principles_and_circuit_literacy/problems.ipynb
+++ b/notebooks/foundations/module_01_principles_and_circuit_literacy/problems.ipynb
@@ -277,9 +277,9 @@
"\n",
"Next notebook: [Principles and Circuit Literacy Studio](studio.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "6c4ddb1b"
+ "id": "7976b005"
}
],
"metadata": {
diff --git a/notebooks/foundations/module_01_principles_and_circuit_literacy/studio.ipynb b/notebooks/foundations/module_01_principles_and_circuit_literacy/studio.ipynb
index 7fcc435..04a4066 100644
--- a/notebooks/foundations/module_01_principles_and_circuit_literacy/studio.ipynb
+++ b/notebooks/foundations/module_01_principles_and_circuit_literacy/studio.ipynb
@@ -329,9 +329,9 @@
"\n",
"Next notebook: [Qubit and Statevector Intuition Lecture](../module_02_qubit_and_statevector_intuition/lecture.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "fffce62b"
+ "id": "1d5c485a"
}
],
"metadata": {
diff --git a/notebooks/foundations/module_02_qubit_and_statevector_intuition/lab.ipynb b/notebooks/foundations/module_02_qubit_and_statevector_intuition/lab.ipynb
index 59774b4..f137682 100644
--- a/notebooks/foundations/module_02_qubit_and_statevector_intuition/lab.ipynb
+++ b/notebooks/foundations/module_02_qubit_and_statevector_intuition/lab.ipynb
@@ -338,9 +338,9 @@
"\n",
"Next notebook: [Qubit and Statevector Intuition Problems](problems.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "12021713"
+ "id": "efd986d5"
}
],
"metadata": {
diff --git a/notebooks/foundations/module_02_qubit_and_statevector_intuition/lecture.ipynb b/notebooks/foundations/module_02_qubit_and_statevector_intuition/lecture.ipynb
index 2f3f20c..e093fa6 100644
--- a/notebooks/foundations/module_02_qubit_and_statevector_intuition/lecture.ipynb
+++ b/notebooks/foundations/module_02_qubit_and_statevector_intuition/lecture.ipynb
@@ -2,13 +2,13 @@
"cells": [
{
"cell_type": "markdown",
+ "id": "59618769",
"metadata": {},
"source": [
"# Qubit and Statevector Intuition Lecture\n",
"\n",
"This module exists because a circuit designer who cannot think in state language becomes trapped at the surface of the diagrams. You can memorize gate names, execute code, and even produce attractive histograms while still being unable to explain what object the circuit is preparing. That gap becomes fatal later. It makes phase look mystical, it makes basis changes look arbitrary, and it makes algorithmic circuits feel like collections of clever tricks instead of understandable constructions. The role of this lecture is to close that gap early.\n"
- ],
- "id": "59618769"
+ ]
},
{
"cell_type": "markdown",
@@ -29,6 +29,7 @@
},
{
"cell_type": "markdown",
+ "id": "57f908eb",
"metadata": {},
"source": [
"## Learning Objective\n",
@@ -36,11 +37,11 @@
"By the end of this lecture, you should be able to describe a small quantum state in a disciplined way. That means naming its basis labels, identifying its support, saying what the amplitudes are doing at a high level, and explaining which information survives or disappears when you finally measure it. The lecture is not trying to make you a full mathematical formalist in one sitting. It is trying to make your intuition precise enough that you can stop hiding behind vague sentences such as “the qubit is in both states at once” or “the phase changed somehow.”\n",
"\n",
"The working target is practical. When you look at a short circuit, you should be able to say not only what gates appear in it, but what state description the circuit is building toward. That change in attention is one of the first major steps from amateur exposure to professional circuit thinking.\n"
- ],
- "id": "57f908eb"
+ ]
},
{
"cell_type": "markdown",
+ "id": "0d103a1a",
"metadata": {},
"source": [
"## Why Statevectors Matter\n",
@@ -48,11 +49,11 @@
"A histogram is evidence. A statevector is a model. Those two sentences do a lot of work in this course. A histogram tells you what happened after you asked one particular measurement question many times. A statevector tells you what pre-measurement object the circuit prepared, at least in the ideal noiseless story. If you confuse those two layers, you will constantly misread what later circuits are doing. You will think that the histogram is the state. You will forget that another basis could reveal a different face of the same preparation. You will treat phase as a decorative nuisance instead of as a structural part of the description.\n",
"\n",
"This lecture therefore treats the statevector as a literacy tool. It is not here so you can perform heroic linear algebra by hand on large systems. It is here so you can learn the right descriptive habits on small systems where every basis label is still visible enough to inspect. If that inspection habit becomes normal now, larger circuits later will feel like scale rather than magic.\n"
- ],
- "id": "0d103a1a"
+ ]
},
{
"cell_type": "markdown",
+ "id": "a663d5d6",
"metadata": {},
"source": [
"## Support, Amplitude, And Probability\n",
@@ -60,11 +61,11 @@
"The first useful distinction is between support and full description. The support of a state is the set of basis labels that actually carry weight. That is already informative. A Bell state, for example, has support on only two of the four computational basis labels. But support is not the entire story. It does not yet tell you the exact amplitudes, and it certainly does not tell you the relative phases between them. If you stop at support, you have only learned where the state lives, not how it lives there.\n",
"\n",
"The second distinction is between amplitude magnitude and probability. Probabilities come from amplitude magnitudes, but the amplitude also carries phase information. Beginners often understand the probability part first because it is easy to connect to histograms. Good. Keep that connection. But do not let it erase the phase story. Some circuits differ only by phase until a later basis change makes that phase visible in counts. That is one of the most important pieces of maturity installed by this module.\n"
- ],
- "id": "a663d5d6"
+ ]
},
{
"cell_type": "markdown",
+ "id": "d004d9db",
"metadata": {},
"source": [
"## Relative Phase Is The First Serious Shock\n",
@@ -72,11 +73,11 @@
"The cleanest beginner shock in this subject is the discovery that two states can have the same computational-basis probabilities and still not be the same state. That is not a mathematical technicality. It is one of the reasons quantum circuit design is interesting at all. Relative phase changes how later gates interfere with the branches already present in the state. A phase change can be operationally silent in one basis and decisive in another.\n",
"\n",
"This is why the lecture uses a one-qubit phase-probe circuit as its anchor. It is a tiny circuit with a very large teaching payoff. A Hadamard creates balanced support. A `Z` gate flips the relative phase of the `|1>` branch while leaving the computational-basis probabilities balanced. A second Hadamard then turns that previously hidden difference into a visible measurement effect. In one short line of reasoning, you get the main lesson: not all meaningful structure is immediately visible in the probabilities you happened to inspect first.\n"
- ],
- "id": "d004d9db"
+ ]
},
{
"cell_type": "markdown",
+ "id": "f0c35ed6",
"metadata": {},
"source": [
"## Multi-Qubit States And Label Reading\n",
@@ -84,12 +85,12 @@
"Multi-qubit states introduce a second challenge: reading the basis labels correctly. The problem is not advanced mathematics. The problem is bookkeeping discipline. Once you have two qubits, there are four computational basis labels. Once you have three, there are eight. The number grows quickly, but the real beginner danger is simpler than that growth. The danger is misreading the labels and telling the wrong story about the right data. If you swap the order in your head, you can create a fake bug where none exists or miss a real pattern that the circuit is clearly producing.\n",
"\n",
"That is why this module takes time to talk about basis labels and support patterns explicitly. A professional designer cannot afford a fuzzy relationship to labeling. The more serious the circuit becomes, the more expensive those small confusions become.\n"
- ],
- "id": "f0c35ed6"
+ ]
},
{
"cell_type": "code",
"execution_count": null,
+ "id": "30dd0fcd",
"metadata": {},
"outputs": [],
"source": [
@@ -105,12 +106,12 @@
"src_path = project_root / \"src\"\n",
"if str(src_path) not in sys.path:\n",
" sys.path.insert(0, str(src_path))\n"
- ],
- "id": "30dd0fcd"
+ ]
},
{
"cell_type": "code",
"execution_count": null,
+ "id": "c703e4f7",
"metadata": {},
"outputs": [],
"source": [
@@ -127,42 +128,42 @@
")\n",
"from qiskit import QuantumCircuit\n",
"from qiskit.quantum_info import Statevector\n"
- ],
- "id": "c703e4f7"
+ ]
},
{
"cell_type": "markdown",
+ "id": "7f552a43",
"metadata": {},
"source": [
"## Code-To-Diagram Anchor\n",
"\n",
"Read the marker table first. The point is to see how a single quiet phase change can sit in the middle of a short circuit and still carry decisive explanatory weight. Notice that the table forces you to translate from code line to diagram effect to conceptual burden. That translation habit is part of the subject, not a supplementary study trick.\n"
- ],
- "id": "7f552a43"
+ ]
},
{
"cell_type": "code",
"execution_count": null,
+ "id": "b445fd92",
"metadata": {},
"outputs": [],
"source": [
"step_reference_table([{'marker': '[1]', 'code_focus': 'Apply Hadamard to create equal-magnitude amplitudes on the computational basis states.', 'diagram_effect': 'The single wire leaves the all-zero path and enters a balanced branch structure.', 'why_it_matters': 'This is the first moment where the circuit meaning requires amplitude language rather than a hidden classical bit story.'}, {'marker': '[2]', 'code_focus': 'Apply Z to flip the phase of the |1> component without changing computational-basis probabilities.', 'diagram_effect': 'The diagram looks small, but the state description changes in a way that is invisible to a direct Z-basis probability check.', 'why_it_matters': 'This is the cleanest beginner example of information that lives in phase rather than in raw support.'}, {'marker': '[3]', 'code_focus': 'Apply a second Hadamard to convert the hidden phase difference into a visible population difference.', 'diagram_effect': 'The final gate changes the basis in which the hidden structure becomes empirically legible.', 'why_it_matters': 'The circuit teaches that phase can matter operationally even when it looked invisible one step earlier.'}, {'marker': '[4]', 'code_focus': 'Measure into a classical bit only after the phase has been translated into a basis-dependent question.', 'diagram_effect': 'The wire ends in a concrete experiment rather than an abstract state description.', 'why_it_matters': 'Counts are answers to a chosen question, not a full dump of the statevector.'}])\n"
- ],
- "id": "b445fd92"
+ ]
},
{
"cell_type": "markdown",
+ "id": "8752516c",
"metadata": {},
"source": [
"## Editable Phase-Probe Circuit\n",
"\n",
"Start by altering exactly one line. Delete the `Z`, move the second `H`, or change the measurement position. Then say what story should survive and what story should break. The circuit is small on purpose. Small circuits make it impossible to hide weak reasoning behind size.\n"
- ],
- "id": "8752516c"
+ ]
},
{
"cell_type": "code",
"execution_count": null,
+ "id": "1f2499a3",
"metadata": {},
"outputs": [],
"source": [
@@ -174,22 +175,22 @@
" instructions='Change one marked step at a time and explain which part of the state story changed: support, phase, or measurement question.',\n",
" shots=256,\n",
")\n"
- ],
- "id": "1f2499a3"
+ ]
},
{
"cell_type": "markdown",
+ "id": "72041e25",
"metadata": {},
"source": [
"## Looking Beneath The Counts\n",
"\n",
"The widget above gives you the diagram and a quick measurement preview, but the main point of this module is that counts alone are not enough. The next code cell looks at the pre-measurement state directly. Read it carefully. The balanced support after the first Hadamard does not disappear when the `Z` gate is inserted, but the relative sign does change. That sign is exactly what the final Hadamard turns into a new measurement outcome.\n"
- ],
- "id": "72041e25"
+ ]
},
{
"cell_type": "code",
"execution_count": null,
+ "id": "668c1621",
"metadata": {},
"outputs": [],
"source": [
@@ -202,12 +203,12 @@
" \"amplitudes\": [complex(value) for value in state.data],\n",
" \"probabilities\": statevector_probabilities(phase_probe),\n",
"}\n"
- ],
- "id": "668c1621"
+ ]
},
{
"cell_type": "code",
"execution_count": null,
+ "id": "b125bf25",
"metadata": {},
"outputs": [],
"source": [
@@ -218,21 +219,21 @@
"bell_probabilities = statevector_probabilities(bell)\n",
"plot_probabilities(bell_probabilities, title=\"Bell-State Support Pattern\")\n",
"bell_probabilities\n"
- ],
- "id": "b125bf25"
+ ]
},
{
"cell_type": "code",
"execution_count": null,
+ "id": "76d8fb62",
"metadata": {},
"outputs": [],
"source": [
"quiz_block([{'prompt': 'What does a statevector give you that a histogram does not?', 'options': ['Only prettier output formatting', 'Amplitude-level information before a particular measurement question is chosen', 'A direct picture of hardware noise'], 'correct_index': 1, 'explanation': 'Statevectors preserve amplitude structure that can be lost once you ask only one measurement question.'}, {'prompt': 'If two basis states have equal probability, what is still missing from that statement?', 'options': ['The relative phase information', 'The number of classical bits in the register', 'The transpiler optimization level'], 'correct_index': 0, 'explanation': 'Probability magnitudes alone do not tell you how amplitudes differ by phase.'}, {'prompt': \"Why is the phrase 'the qubit is really 0 or 1 underneath' dangerous here?\", 'options': ['Because it blocks basis and phase reasoning by forcing a classical hidden-value story onto a quantum object', 'Because it makes circuits larger', 'Because it prevents plotting'], 'correct_index': 0, 'explanation': 'The hidden-value story fails precisely where phase and basis dependence start to matter.'}], heading='Statevector Checkpoint A')\n"
- ],
- "id": "76d8fb62"
+ ]
},
{
"cell_type": "markdown",
+ "id": "da43eb70",
"metadata": {},
"source": [
"## Why Counts Are A Lossy Compression\n",
@@ -240,11 +241,11 @@
"Once you measure, you compress the story. That compression is not a flaw; it is the nature of the experiment you chose to run. But it is still a compression. You no longer hold the full pre-measurement object in your hand. You hold evidence produced by one specific question. This is why the course keeps insisting on the phrase “measurement is a chosen question.” The question determines what information survives directly into the histogram and what information remains hidden unless you ask differently.\n",
"\n",
"This is also why statevector intuition is not a luxury for people who like math. It is a practical defense against shallow interpretation. If you know only the counts, you can talk yourself into believing that two circuits are identical when they merely agree in one basis. If you know the state-level story, you are much less vulnerable to that mistake.\n"
- ],
- "id": "da43eb70"
+ ]
},
{
"cell_type": "markdown",
+ "id": "a0a28913",
"metadata": {},
"source": [
"## Common Misconceptions To Kill Here\n",
@@ -252,11 +253,11 @@
"The first misconception is that equal probabilities imply equal states. They do not. The second is that phase only matters in advanced algorithms. It already matters in one-qubit circuits. The third is that statevector inspection is somehow “less real” than measurement because it is a simulation object. In a local-first learning platform, statevector inspection is a teaching instrument. It gives you a clean view of the intended ideal object so that later distortions, noisy counts, and transpiled rewrites have something stable to be compared against.\n",
"\n",
"The fourth misconception is that notation difficulties are a sign of weak intelligence. Usually they are a sign that the learner has not yet built enough bookkeeping habits. This course answers that problem by making the bookkeeping explicit: basis labels, support patterns, measurement questions, and reflection writing all exist so that confusion can become specific rather than vague.\n"
- ],
- "id": "a0a28913"
+ ]
},
{
"cell_type": "markdown",
+ "id": "1a060ef9",
"metadata": {},
"source": [
"## How To Read A Statevector Professionally\n",
@@ -266,11 +267,11 @@
"That order matters because it prevents a common collapse of reasoning. Beginners often jump straight from “I see two nonzero entries” to “therefore I understand the state.” Not yet. Two nonzero entries only tell you part of the story. A good explanation keeps going until it can say what another gate or another basis would do with that state. In other words, a statevector is not just something to read statically; it is something to reason forward from.\n",
"\n",
"This forward-looking habit is what turns state inspection into circuit design preparation. Once you can look at a state and ask what basis would reveal its structure, what gate would convert hidden phase into visible population, or what edit would destroy the intended support pattern, you have started moving beyond notation literacy into engineering literacy.\n"
- ],
- "id": "1a060ef9"
+ ]
},
{
"cell_type": "markdown",
+ "id": "deaa86a2",
"metadata": {},
"source": [
"## Transfer Forward\n",
@@ -278,48 +279,47 @@
"If this lecture lands correctly, later modules become dramatically easier to interpret. Basis changes before measurement stop feeling arbitrary. Oracle and phase-kickback circuits stop feeling like special magic. Transpilation and noise notebooks become easier because you can separate the ideal object from the distorted evidence. That is the real reason to take statevectors seriously. They are not the final destination of the course. They are the clean reference frame that later engineering work needs.\n",
"\n",
"As you move to the lab, keep the following sentence in view: support tells you where the state lives, amplitudes tell you how it lives there, and measurement tells you which part of that story you decided to ask about.\n"
- ],
- "id": "deaa86a2"
+ ]
},
{
"cell_type": "code",
"execution_count": null,
+ "id": "94c20a98",
"metadata": {},
"outputs": [],
"source": [
"quiz_block([{'prompt': 'Why does the `Z` gate in the phase-probe circuit matter even though the intermediate probabilities stay balanced?', 'options': ['Because it changes the relative phase, which later gates can turn into different measurement behavior', 'Because it secretly performs measurement', 'Because it increases the shot count'], 'correct_index': 0, 'explanation': 'Relative phase can be operationally silent in one basis and visible in another.'}, {'prompt': 'What does the support of a statevector refer to in this course?', 'options': ['The basis states with nonzero amplitude weight', 'The hardware backends that accept the circuit', 'The number of markdown explanations around the code'], 'correct_index': 0, 'explanation': 'Support is about which basis labels actually participate in the state description.'}, {'prompt': 'Why is bitstring ordering worth discussing explicitly in a beginner module?', 'options': ['Because label order affects how you read multi-qubit probability dictionaries and can create false debugging stories if ignored', 'Because Qiskit changes the number of qubits based on label order', 'Because it determines whether Hadamard is allowed'], 'correct_index': 0, 'explanation': 'Ambiguity about labels creates fake confusion that should be removed early.'}], heading='Statevector Checkpoint B')\n"
- ],
- "id": "94c20a98"
+ ]
},
{
"cell_type": "code",
"execution_count": null,
+ "id": "80cea78d",
"metadata": {},
"outputs": [],
"source": [
"reflection_box('Write one paragraph that explains why two circuits can share the same probabilities in one basis and still be different states.')\n"
- ],
- "id": "80cea78d"
+ ]
},
{
"cell_type": "code",
"execution_count": null,
+ "id": "f0c10c75",
"metadata": {},
"outputs": [],
"source": [
"reflection_box(\"Describe the exact role of the second Hadamard in the phase-probe circuit without using the phrase 'it undoes the first gate.'\")\n"
- ],
- "id": "f0c10c75"
+ ]
},
{
"cell_type": "markdown",
+ "id": "b4028af7",
"metadata": {},
"source": [
"## Mastery Gate\n",
"\n",
"You are ready to leave this lecture only if you can inspect a small circuit, name its support pattern, say whether phase is carrying essential information, and explain what a chosen measurement protocol will and will not reveal. That is the floor this module is trying to install.\n"
- ],
- "id": "b4028af7"
+ ]
},
{
"cell_type": "markdown",
@@ -330,9 +330,9 @@
"\n",
"Next notebook: [Qubit and Statevector Intuition Lab](lab.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "c04cf2cd"
+ "id": "90d17364"
}
],
"metadata": {
@@ -342,8 +342,16 @@
"name": "quantum-learning"
},
"language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
"name": "python",
- "version": "3.12"
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.12.4"
}
},
"nbformat": 4,
diff --git a/notebooks/foundations/module_02_qubit_and_statevector_intuition/problems.ipynb b/notebooks/foundations/module_02_qubit_and_statevector_intuition/problems.ipynb
index c599305..c28ea45 100644
--- a/notebooks/foundations/module_02_qubit_and_statevector_intuition/problems.ipynb
+++ b/notebooks/foundations/module_02_qubit_and_statevector_intuition/problems.ipynb
@@ -221,9 +221,9 @@
"\n",
"Next notebook: [Qubit and Statevector Intuition Studio](studio.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "f86691fb"
+ "id": "9b3f4975"
}
],
"metadata": {
diff --git a/notebooks/foundations/module_02_qubit_and_statevector_intuition/studio.ipynb b/notebooks/foundations/module_02_qubit_and_statevector_intuition/studio.ipynb
index c5e7c13..f8ab857 100644
--- a/notebooks/foundations/module_02_qubit_and_statevector_intuition/studio.ipynb
+++ b/notebooks/foundations/module_02_qubit_and_statevector_intuition/studio.ipynb
@@ -242,9 +242,9 @@
"\n",
"Next notebook: [Gates and Measurement Lecture](../module_03_gates_and_measurement/lecture.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "b1c69610"
+ "id": "ebe76aab"
}
],
"metadata": {
diff --git a/notebooks/foundations/module_03_gates_and_measurement/lab.ipynb b/notebooks/foundations/module_03_gates_and_measurement/lab.ipynb
index df6662f..2528e57 100644
--- a/notebooks/foundations/module_03_gates_and_measurement/lab.ipynb
+++ b/notebooks/foundations/module_03_gates_and_measurement/lab.ipynb
@@ -301,9 +301,9 @@
"\n",
"Next notebook: [Gates and Measurement Problems](problems.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "99fc86f1"
+ "id": "0bc5c39e"
}
],
"metadata": {
diff --git a/notebooks/foundations/module_03_gates_and_measurement/lecture.ipynb b/notebooks/foundations/module_03_gates_and_measurement/lecture.ipynb
index d952041..6c9ab17 100644
--- a/notebooks/foundations/module_03_gates_and_measurement/lecture.ipynb
+++ b/notebooks/foundations/module_03_gates_and_measurement/lecture.ipynb
@@ -334,9 +334,9 @@
"\n",
"Next notebook: [Gates and Measurement Lab](lab.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "569afbf7"
+ "id": "ed9c7aec"
}
],
"metadata": {
diff --git a/notebooks/foundations/module_03_gates_and_measurement/problems.ipynb b/notebooks/foundations/module_03_gates_and_measurement/problems.ipynb
index f8b362b..a6f7afe 100644
--- a/notebooks/foundations/module_03_gates_and_measurement/problems.ipynb
+++ b/notebooks/foundations/module_03_gates_and_measurement/problems.ipynb
@@ -221,9 +221,9 @@
"\n",
"Next notebook: [Gates and Measurement Studio](studio.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "0149b171"
+ "id": "9cde0c96"
}
],
"metadata": {
diff --git a/notebooks/foundations/module_03_gates_and_measurement/studio.ipynb b/notebooks/foundations/module_03_gates_and_measurement/studio.ipynb
index 56e28ce..891162e 100644
--- a/notebooks/foundations/module_03_gates_and_measurement/studio.ipynb
+++ b/notebooks/foundations/module_03_gates_and_measurement/studio.ipynb
@@ -242,9 +242,9 @@
"\n",
"Next notebook: [Circuit Construction and Analysis Lecture](../../qiskit_engineering/module_01_circuit_construction_and_analysis/lecture.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "800c035b"
+ "id": "8ca10036"
}
],
"metadata": {
diff --git a/notebooks/professional/module_01_qiskit_patterns/lab.ipynb b/notebooks/professional/module_01_qiskit_patterns/lab.ipynb
index cfa7610..f7e1a63 100644
--- a/notebooks/professional/module_01_qiskit_patterns/lab.ipynb
+++ b/notebooks/professional/module_01_qiskit_patterns/lab.ipynb
@@ -303,9 +303,9 @@
"\n",
"Next notebook: [Qiskit Patterns and Workflow Design Problems](problems.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "1512e038"
+ "id": "10c54994"
}
],
"metadata": {
diff --git a/notebooks/professional/module_01_qiskit_patterns/lecture.ipynb b/notebooks/professional/module_01_qiskit_patterns/lecture.ipynb
index 7d19a93..abda8a9 100644
--- a/notebooks/professional/module_01_qiskit_patterns/lecture.ipynb
+++ b/notebooks/professional/module_01_qiskit_patterns/lecture.ipynb
@@ -350,9 +350,9 @@
"\n",
"Next notebook: [Qiskit Patterns and Workflow Design Lab](lab.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "77bbfbef"
+ "id": "0155e1c9"
}
],
"metadata": {
diff --git a/notebooks/professional/module_01_qiskit_patterns/problems.ipynb b/notebooks/professional/module_01_qiskit_patterns/problems.ipynb
index 87c6d08..f01f0e7 100644
--- a/notebooks/professional/module_01_qiskit_patterns/problems.ipynb
+++ b/notebooks/professional/module_01_qiskit_patterns/problems.ipynb
@@ -290,9 +290,9 @@
"\n",
"Next notebook: [Qiskit Patterns and Workflow Design Studio](studio.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "463de1a6"
+ "id": "4bf55303"
}
],
"metadata": {
diff --git a/notebooks/professional/module_01_qiskit_patterns/studio.ipynb b/notebooks/professional/module_01_qiskit_patterns/studio.ipynb
index afde8c2..2a00035 100644
--- a/notebooks/professional/module_01_qiskit_patterns/studio.ipynb
+++ b/notebooks/professional/module_01_qiskit_patterns/studio.ipynb
@@ -313,9 +313,9 @@
"\n",
"Next notebook: [Hardware-Aware Redesign Studio Lecture](../module_02_hardware_aware_redesign/lecture.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "8475edd7"
+ "id": "aafcd949"
}
],
"metadata": {
diff --git a/notebooks/professional/module_02_hardware_aware_redesign/lab.ipynb b/notebooks/professional/module_02_hardware_aware_redesign/lab.ipynb
index e2ef32e..51c9480 100644
--- a/notebooks/professional/module_02_hardware_aware_redesign/lab.ipynb
+++ b/notebooks/professional/module_02_hardware_aware_redesign/lab.ipynb
@@ -336,9 +336,9 @@
"\n",
"Next notebook: [Hardware-Aware Redesign Studio Problems](problems.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "cc29f375"
+ "id": "d818996c"
}
],
"metadata": {
diff --git a/notebooks/professional/module_02_hardware_aware_redesign/lecture.ipynb b/notebooks/professional/module_02_hardware_aware_redesign/lecture.ipynb
index a2c6711..9b396e7 100644
--- a/notebooks/professional/module_02_hardware_aware_redesign/lecture.ipynb
+++ b/notebooks/professional/module_02_hardware_aware_redesign/lecture.ipynb
@@ -372,9 +372,9 @@
"\n",
"Next notebook: [Hardware-Aware Redesign Studio Lab](lab.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "1b0daab6"
+ "id": "b1e74c49"
}
],
"metadata": {
diff --git a/notebooks/professional/module_02_hardware_aware_redesign/problems.ipynb b/notebooks/professional/module_02_hardware_aware_redesign/problems.ipynb
index ff16bec..de77fee 100644
--- a/notebooks/professional/module_02_hardware_aware_redesign/problems.ipynb
+++ b/notebooks/professional/module_02_hardware_aware_redesign/problems.ipynb
@@ -290,9 +290,9 @@
"\n",
"Next notebook: [Hardware-Aware Redesign Studio Studio](studio.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "e3970e55"
+ "id": "7758ff61"
}
],
"metadata": {
diff --git a/notebooks/professional/module_02_hardware_aware_redesign/studio.ipynb b/notebooks/professional/module_02_hardware_aware_redesign/studio.ipynb
index c591532..41e4e30 100644
--- a/notebooks/professional/module_02_hardware_aware_redesign/studio.ipynb
+++ b/notebooks/professional/module_02_hardware_aware_redesign/studio.ipynb
@@ -346,9 +346,9 @@
"\n",
"Next notebook: [Noise-Aware Verification and Mitigation Lecture](../module_03_noise_aware_verification/lecture.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "bb9aadbc"
+ "id": "e92895d4"
}
],
"metadata": {
diff --git a/notebooks/professional/module_03_noise_aware_verification/lab.ipynb b/notebooks/professional/module_03_noise_aware_verification/lab.ipynb
index 70b439c..1445a49 100644
--- a/notebooks/professional/module_03_noise_aware_verification/lab.ipynb
+++ b/notebooks/professional/module_03_noise_aware_verification/lab.ipynb
@@ -321,9 +321,9 @@
"\n",
"Next notebook: [Noise-Aware Verification and Mitigation Problems](problems.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "13e3bf6c"
+ "id": "ef38a121"
}
],
"metadata": {
diff --git a/notebooks/professional/module_03_noise_aware_verification/lecture.ipynb b/notebooks/professional/module_03_noise_aware_verification/lecture.ipynb
index 4e98118..353479c 100644
--- a/notebooks/professional/module_03_noise_aware_verification/lecture.ipynb
+++ b/notebooks/professional/module_03_noise_aware_verification/lecture.ipynb
@@ -373,9 +373,9 @@
"\n",
"Next notebook: [Noise-Aware Verification and Mitigation Lab](lab.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "b0bb5429"
+ "id": "2a3c8e32"
}
],
"metadata": {
diff --git a/notebooks/professional/module_03_noise_aware_verification/problems.ipynb b/notebooks/professional/module_03_noise_aware_verification/problems.ipynb
index 6356f04..5c1d76f 100644
--- a/notebooks/professional/module_03_noise_aware_verification/problems.ipynb
+++ b/notebooks/professional/module_03_noise_aware_verification/problems.ipynb
@@ -290,9 +290,9 @@
"\n",
"Next notebook: [Noise-Aware Verification and Mitigation Studio](studio.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "4d9d4d24"
+ "id": "02dbbe67"
}
],
"metadata": {
diff --git a/notebooks/professional/module_03_noise_aware_verification/studio.ipynb b/notebooks/professional/module_03_noise_aware_verification/studio.ipynb
index 544d3a8..1c93860 100644
--- a/notebooks/professional/module_03_noise_aware_verification/studio.ipynb
+++ b/notebooks/professional/module_03_noise_aware_verification/studio.ipynb
@@ -331,9 +331,9 @@
"\n",
"Next notebook: [Capstone Circuit Design Review Lecture](../module_04_capstone_design_review/lecture.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "28d0ddba"
+ "id": "2ea7b2ef"
}
],
"metadata": {
diff --git a/notebooks/professional/module_04_capstone_design_review/lab.ipynb b/notebooks/professional/module_04_capstone_design_review/lab.ipynb
index e1c5e0c..7547049 100644
--- a/notebooks/professional/module_04_capstone_design_review/lab.ipynb
+++ b/notebooks/professional/module_04_capstone_design_review/lab.ipynb
@@ -354,9 +354,9 @@
"\n",
"Next notebook: [Capstone Circuit Design Review Problems](problems.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "dd28bb04"
+ "id": "388bc196"
}
],
"metadata": {
diff --git a/notebooks/professional/module_04_capstone_design_review/lecture.ipynb b/notebooks/professional/module_04_capstone_design_review/lecture.ipynb
index 9ef11ca..15cf523 100644
--- a/notebooks/professional/module_04_capstone_design_review/lecture.ipynb
+++ b/notebooks/professional/module_04_capstone_design_review/lecture.ipynb
@@ -394,9 +394,9 @@
"\n",
"Next notebook: [Capstone Circuit Design Review Lab](lab.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "8c640ce9"
+ "id": "e6f17a32"
}
],
"metadata": {
diff --git a/notebooks/professional/module_04_capstone_design_review/problems.ipynb b/notebooks/professional/module_04_capstone_design_review/problems.ipynb
index 295232b..9a1d27a 100644
--- a/notebooks/professional/module_04_capstone_design_review/problems.ipynb
+++ b/notebooks/professional/module_04_capstone_design_review/problems.ipynb
@@ -290,9 +290,9 @@
"\n",
"Next notebook: [Capstone Circuit Design Review Studio](studio.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "cbf75b77"
+ "id": "1386798d"
}
],
"metadata": {
diff --git a/notebooks/professional/module_04_capstone_design_review/studio.ipynb b/notebooks/professional/module_04_capstone_design_review/studio.ipynb
index 730a632..f4b2f32 100644
--- a/notebooks/professional/module_04_capstone_design_review/studio.ipynb
+++ b/notebooks/professional/module_04_capstone_design_review/studio.ipynb
@@ -364,9 +364,9 @@
"\n",
"Next notebook: [Course Complete](../../COURSE_COMPLETE.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "52b98827"
+ "id": "ce05556f"
}
],
"metadata": {
diff --git a/notebooks/qiskit_engineering/module_01_circuit_construction_and_analysis/lab.ipynb b/notebooks/qiskit_engineering/module_01_circuit_construction_and_analysis/lab.ipynb
index c8e61d4..f8416db 100644
--- a/notebooks/qiskit_engineering/module_01_circuit_construction_and_analysis/lab.ipynb
+++ b/notebooks/qiskit_engineering/module_01_circuit_construction_and_analysis/lab.ipynb
@@ -309,9 +309,9 @@
"\n",
"Next notebook: [Circuit Construction and Analysis Problems](problems.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "c46f4197"
+ "id": "f98fa571"
}
],
"metadata": {
diff --git a/notebooks/qiskit_engineering/module_01_circuit_construction_and_analysis/lecture.ipynb b/notebooks/qiskit_engineering/module_01_circuit_construction_and_analysis/lecture.ipynb
index 24d48d5..289ead7 100644
--- a/notebooks/qiskit_engineering/module_01_circuit_construction_and_analysis/lecture.ipynb
+++ b/notebooks/qiskit_engineering/module_01_circuit_construction_and_analysis/lecture.ipynb
@@ -298,9 +298,9 @@
"\n",
"Next notebook: [Circuit Construction and Analysis Lab](lab.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "eaabcfe6"
+ "id": "351ce8ce"
}
],
"metadata": {
diff --git a/notebooks/qiskit_engineering/module_01_circuit_construction_and_analysis/problems.ipynb b/notebooks/qiskit_engineering/module_01_circuit_construction_and_analysis/problems.ipynb
index 36153c6..4897c86 100644
--- a/notebooks/qiskit_engineering/module_01_circuit_construction_and_analysis/problems.ipynb
+++ b/notebooks/qiskit_engineering/module_01_circuit_construction_and_analysis/problems.ipynb
@@ -226,9 +226,9 @@
"\n",
"Next notebook: [Circuit Construction and Analysis Studio](studio.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "81e7ecdf"
+ "id": "7af11716"
}
],
"metadata": {
diff --git a/notebooks/qiskit_engineering/module_01_circuit_construction_and_analysis/studio.ipynb b/notebooks/qiskit_engineering/module_01_circuit_construction_and_analysis/studio.ipynb
index 9574ae1..96bf924 100644
--- a/notebooks/qiskit_engineering/module_01_circuit_construction_and_analysis/studio.ipynb
+++ b/notebooks/qiskit_engineering/module_01_circuit_construction_and_analysis/studio.ipynb
@@ -247,9 +247,9 @@
"\n",
"Next notebook: [Transpilation and Visualization Lecture](../module_02_transpilation_and_visualization/lecture.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "b944a92f"
+ "id": "b14a1147"
}
],
"metadata": {
diff --git a/notebooks/qiskit_engineering/module_02_transpilation_and_visualization/lab.ipynb b/notebooks/qiskit_engineering/module_02_transpilation_and_visualization/lab.ipynb
index 685bfce..f8bc8bf 100644
--- a/notebooks/qiskit_engineering/module_02_transpilation_and_visualization/lab.ipynb
+++ b/notebooks/qiskit_engineering/module_02_transpilation_and_visualization/lab.ipynb
@@ -308,9 +308,9 @@
"\n",
"Next notebook: [Transpilation and Visualization Problems](problems.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "60b98251"
+ "id": "538eaa02"
}
],
"metadata": {
diff --git a/notebooks/qiskit_engineering/module_02_transpilation_and_visualization/lecture.ipynb b/notebooks/qiskit_engineering/module_02_transpilation_and_visualization/lecture.ipynb
index cc71060..32f505f 100644
--- a/notebooks/qiskit_engineering/module_02_transpilation_and_visualization/lecture.ipynb
+++ b/notebooks/qiskit_engineering/module_02_transpilation_and_visualization/lecture.ipynb
@@ -356,9 +356,9 @@
"\n",
"Next notebook: [Transpilation and Visualization Lab](lab.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "fa5873a4"
+ "id": "00ce2c21"
}
],
"metadata": {
diff --git a/notebooks/qiskit_engineering/module_02_transpilation_and_visualization/problems.ipynb b/notebooks/qiskit_engineering/module_02_transpilation_and_visualization/problems.ipynb
index eb4c9d4..db4e463 100644
--- a/notebooks/qiskit_engineering/module_02_transpilation_and_visualization/problems.ipynb
+++ b/notebooks/qiskit_engineering/module_02_transpilation_and_visualization/problems.ipynb
@@ -238,9 +238,9 @@
"\n",
"Next notebook: [Transpilation and Visualization Studio](studio.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "aa8fdee8"
+ "id": "df56db33"
}
],
"metadata": {
diff --git a/notebooks/qiskit_engineering/module_02_transpilation_and_visualization/studio.ipynb b/notebooks/qiskit_engineering/module_02_transpilation_and_visualization/studio.ipynb
index a9c6986..0481579 100644
--- a/notebooks/qiskit_engineering/module_02_transpilation_and_visualization/studio.ipynb
+++ b/notebooks/qiskit_engineering/module_02_transpilation_and_visualization/studio.ipynb
@@ -283,9 +283,9 @@
"\n",
"Next notebook: [Simulation and Noise Models Lecture](../module_03_simulation_and_noise_models/lecture.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "19c41d5a"
+ "id": "c4c061ef"
}
],
"metadata": {
diff --git a/notebooks/qiskit_engineering/module_03_simulation_and_noise_models/lab.ipynb b/notebooks/qiskit_engineering/module_03_simulation_and_noise_models/lab.ipynb
index 36c0b5d..3bc75bd 100644
--- a/notebooks/qiskit_engineering/module_03_simulation_and_noise_models/lab.ipynb
+++ b/notebooks/qiskit_engineering/module_03_simulation_and_noise_models/lab.ipynb
@@ -309,9 +309,9 @@
"\n",
"Next notebook: [Simulation and Noise Models Problems](problems.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "c6c32618"
+ "id": "a61be017"
}
],
"metadata": {
diff --git a/notebooks/qiskit_engineering/module_03_simulation_and_noise_models/lecture.ipynb b/notebooks/qiskit_engineering/module_03_simulation_and_noise_models/lecture.ipynb
index 28ecc6c..0f27516 100644
--- a/notebooks/qiskit_engineering/module_03_simulation_and_noise_models/lecture.ipynb
+++ b/notebooks/qiskit_engineering/module_03_simulation_and_noise_models/lecture.ipynb
@@ -328,9 +328,9 @@
"\n",
"Next notebook: [Simulation and Noise Models Lab](lab.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "7565c077"
+ "id": "95d24bc0"
}
],
"metadata": {
diff --git a/notebooks/qiskit_engineering/module_03_simulation_and_noise_models/problems.ipynb b/notebooks/qiskit_engineering/module_03_simulation_and_noise_models/problems.ipynb
index 741de3c..07c5b1b 100644
--- a/notebooks/qiskit_engineering/module_03_simulation_and_noise_models/problems.ipynb
+++ b/notebooks/qiskit_engineering/module_03_simulation_and_noise_models/problems.ipynb
@@ -238,9 +238,9 @@
"\n",
"Next notebook: [Simulation and Noise Models Studio](studio.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "d411fa2d"
+ "id": "35b93877"
}
],
"metadata": {
diff --git a/notebooks/qiskit_engineering/module_03_simulation_and_noise_models/studio.ipynb b/notebooks/qiskit_engineering/module_03_simulation_and_noise_models/studio.ipynb
index 8b65bc9..80e3c97 100644
--- a/notebooks/qiskit_engineering/module_03_simulation_and_noise_models/studio.ipynb
+++ b/notebooks/qiskit_engineering/module_03_simulation_and_noise_models/studio.ipynb
@@ -299,9 +299,9 @@
"\n",
"Next notebook: [Deutsch Family and Oracle Thinking Lecture](../../algorithms/module_01_deutsch_family/lecture.ipynb)\n",
"\n",
- "If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
+ "When you finish this notebook, open the next notebook shown above. Stay on the guarded mainline route.\n"
],
- "id": "2af0acc5"
+ "id": "11050d32"
}
],
"metadata": {
diff --git a/notebooks/reference/PROFESSIONAL_PATH.ipynb b/notebooks/reference/PROFESSIONAL_PATH.ipynb
deleted file mode 100644
index 31a9a78..0000000
--- a/notebooks/reference/PROFESSIONAL_PATH.ipynb
+++ /dev/null
@@ -1,258 +0,0 @@
-{
- "cells": [
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "# Professional Path\n",
- "\n",
- "This notebook is the didactical map of the course. Its purpose is to answer the question: what must be learned, mastered, and defended at every stage if the final goal is genuine professional circuit design rather than superficial tool familiarity?\n"
- ],
- "id": "a5347f8d"
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Optional Deep-Dive Reference\n",
- "\n",
- "This notebook is not part of the mandatory first-pass mainline. Use it when you want the full backward-designed mastery map in more depth. For the mainline flow, return to `../COURSE_BLUEPRINT.ipynb` and follow the next-notebook handoff there.\n"
- ],
- "id": "da0a486a"
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## The Backward-Design Principle\n",
- "\n",
- "The course is built backward from the terminal capability. That terminal capability is not “knows Qiskit,” not “can run example notebooks,” and not “has seen Bell states.” The terminal capability is: **independent hardware-aware circuit designer who can propose, compare, debug, and defend circuit architectures under constraints.**\n",
- "\n",
- "Once that target is stated clearly, the earlier stages stop being arbitrary. Beginner work is no longer something you “have to get through.” It becomes the deliberate installation of subskills without which later engineering judgment collapses. This is why the course begins with literacy, state reasoning, and measurement reasoning, even though the long-term target is much more advanced.\n"
- ],
- "id": "f8f39a46"
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## The Stage Ladder\n",
- "\n",
- "The stage ladder should be read as a sequence of identities, not just a sequence of topics. At each stage, the question is: what kind of person are you becoming as a designer?\n",
- "\n",
- "You begin as someone who cannot yet parse a diagram confidently. Then you become someone who can narrate small circuits. Then someone who can predict state evolution. Then someone who can think in reusable blocks. Then someone who can synthesize designs, adapt them to constraints, reason about noise, review failures, and finally defend a capstone design. That is a dramatic transformation. The course should feel structured enough to support it.\n"
- ],
- "id": "9b75dbba"
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Why The Ladder Is Emotional As Well As Technical\n",
- "\n",
- "Many learners experience a hidden emotional problem when studying advanced technical material: they cannot tell whether confusion means the subject is deep, the material is poorly taught, or they themselves are missing a prerequisite. A well-articulated stage ladder helps with that. It gives your confusion a location. If you cannot yet think in reusable subcircuits, that does not mean you are bad at quantum computing in general. It means you are at a specific stage boundary. That is a much healthier and more useful diagnosis.\n",
- "\n",
- "Good pedagogy respects this emotional dimension without becoming soft. The course still expects real work. But it tries to make that work legible. Legibility is one of the reasons the notebooks are becoming more text-heavy and more explicit about objectives, gates, and deliverables.\n"
- ],
- "id": "d84237c3"
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Why The Technical Notebooks Must Feel Denser Than Normal Tutorials\n",
- "\n",
- "A normal tutorial is optimized for quick success. That is useful when the goal is tool onboarding. It is not enough when the goal is professional circuit design. Professional growth requires deeper reading, repeated explanation, retrieval, self-diagnosis, and gradual comfort with ambiguity. That is why the notebooks are being rewritten with much heavier explanatory text than a standard example-driven notebook would contain.\n",
- "\n",
- "The text is not there because the code is weak. The text is there because code by itself often hides the conceptual burden. A line of code can be syntactically simple and conceptually deep. Without explanation, beginners tend to either overestimate or underestimate the importance of a line. Dense lecture writing helps calibrate attention. The quizzes and reflection prompts then test whether that calibration has stuck.\n"
- ],
- "id": "8817fc63"
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Extended Path Notes I\n",
- "\n",
- "Backward-designed curriculum can sound abstract until you feel its practical force. The practical force is this: once the final professional role is named precisely, many tempting teaching decisions become obviously insufficient. If the final role is independent circuit designer under constraints, then a course built around isolated novelty examples is not enough. If the final role includes review, debugging, adaptation, and defense, then a course that measures only whether a notebook ran successfully is not enough. The capstone standard reaches backward and reshapes every earlier lesson.\n",
- "\n",
- "That reshaping is the real reason for the stage ladder. A stage is not just a folder label. It is a claim about what kind of judgment you should now possess. At the earliest stage, the judgment is local: can you read the circuit at all, and can you distinguish the important objects? At a slightly later stage, the judgment becomes dynamical: can you predict how state, basis, or measurement will respond to a design choice? Later still it becomes architectural: can you think in reusable blocks and structured experiments rather than flat strings of gates? Eventually it becomes strategic: can you compare alternatives under hardware, synthesis, and noise constraints? Seeing the path in those terms makes the course much more coherent.\n",
- "\n",
- "The stage ladder also protects against a common self-study trap: mistaking interest for preparation. You may be highly motivated by error correction, encoded circuits, or architecture papers, but if the earlier layers are weak then the advanced material becomes something you admire rather than something you can manipulate. Backward design does not deny ambition. It channels ambition into prerequisites. It says: if this advanced capability truly matters, which earlier capabilities must become automatic first? That question is often more valuable than asking which advanced topic looks exciting next.\n",
- "\n",
- "A well-designed apprenticeship path therefore does two things simultaneously. It raises the standard by naming a demanding final role, and it lowers confusion by decomposing that role into visible subskills. That combination is what the notebook is trying to provide.\n"
- ],
- "id": "fa376509"
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## How To Use The Interactive Elements In The Technical Notebooks\n",
- "\n",
- "The quizzes are for retrieval. The editable labs are for manipulation. The reference tables are for code-to-diagram translation. The reflection boxes are for self-explanation. Those are different learning mechanisms, and they complement each other. If you use all four, the notebook behaves much more like a live teaching environment. If you use only one, the notebook shrinks back toward a static document.\n",
- "\n",
- "This matters because circuit design expertise is not a single skill. It is an integration of language, prediction, manipulation, and judgment. The platform therefore has to exercise all of those muscles, not merely one of them.\n"
- ],
- "id": "a8ea786b"
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Extended Path Notes II\n",
- "\n",
- "There is also a deeper pedagogical principle behind the course structure: each stage changes the unit of thought. Beginners often think in lines of code. More developed learners begin to think in gates and local transformations. Later they think in subcircuits, patterns, invariants, and constraints. The jump to professional design happens when you can choose the right unit of thought for the problem in front of you and move up or down that ladder without getting lost. A course that only presents topics without highlighting these changing units of thought will often feel fragmented, even if its content is correct.\n",
- "\n",
- "The stage ladder is therefore not merely chronological. It is representational. It tells you what kind of object should now be salient to you. In an early notebook, a control-target relationship may be the key object. In a later notebook, the key object may be a synthesis pattern or a routing bottleneck. In a capstone, the key object may be a design tradeoff backed by evidence. By naming these shifts directly, the course helps you notice whether your internal way of seeing circuits is actually evolving.\n",
- "\n",
- "This is one reason the platform now emphasizes writing inside the notebooks. Written explanation can make invisible representational changes visible. If you compare how you describe a circuit at the start of the course to how you describe one several stages later, you should hear a difference. Early explanations will be local and syntactic. Later explanations should mention burden, purpose, constraint, degradation mode, or verification strategy. That change in language reflects a real change in cognition.\n",
- "\n",
- "The final reason to care about this path notebook is motivational in the precise sense, not the sentimental sense. Motivation becomes much stronger when effort is legible. If you know why a beginner notebook exists, you can invest in it honestly. If you do not know why it exists, you are tempted either to dismiss it or to drown in it. A visible staircase solves both problems by showing what each rung is preparing you to do next.\n"
- ],
- "id": "4777e27d"
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## The Real Backward Calculation\n",
- "\n",
- "If the capstone requires you to defend a design review, then you must already know how to compare candidates. If you must compare candidates, you must already know how to describe circuit structure. If you must describe circuit structure, you must already know how to read code and diagrams without confusion. If you must debug noise and constraint effects later, you must already have clean ideal intuitions now. This is the backward calculation in its simplest form: every advanced ability decomposes into earlier abilities, and every earlier ability must be trained deliberately if the final role is serious.\n",
- "\n",
- "That is why the course does not apologize for starting simply. The simplicity is not the endpoint. It is the first stable platform from which the later complexity can be climbed.\n"
- ],
- "id": "db931e50"
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "from pathlib import Path\n",
- "import sys\n",
- "\n",
- "project_root = Path.cwd().resolve()\n",
- "if project_root.name == \"notebooks\":\n",
- " project_root = project_root.parent\n",
- "\n",
- "src_path = project_root / \"src\"\n",
- "if str(src_path) not in sys.path:\n",
- " sys.path.insert(0, str(src_path))\n"
- ],
- "id": "06d86ceb"
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "from quantum_learning import load_curriculum, load_mastery_blueprint\n",
- "from quantum_learning.interactive import quiz_block\n",
- "\n",
- "blueprint = load_mastery_blueprint()\n",
- "curriculum = load_curriculum()\n",
- "\n",
- "[(stage.order, stage.title, stage.identity, stage.gate) for stage in blueprint.stages]\n"
- ],
- "id": "b639477b"
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## How To Use The Ladder\n",
- "\n",
- "Do not use the stage ladder as a motivational poster. Use it as a diagnostic instrument. Ask, at each stage, whether you can already perform the gate condition of that stage. If not, identify the missing subskill precisely. Vague self-descriptions like “I’m still a beginner” are not useful enough. More useful statements are things like “I cannot yet predict measurement-basis effects before running a circuit” or “I still flatten every design into raw gate sequences instead of reusable blocks.” The notebook is trying to push you toward that higher-resolution self-assessment.\n"
- ],
- "id": "b278b501"
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "[(lesson.stage, lesson.title, lesson.deliverable, lesson.mastery_gate) for lesson in curriculum]\n"
- ],
- "id": "846688a8"
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "quiz_block([{'prompt': 'Why is the course built backward from the capstone role?', 'options': ['Because advanced notebooks are easier to write first', 'Because the terminal professional capability determines which prerequisites actually matter', 'Because it removes the need for fundamentals'], 'correct_index': 1, 'explanation': 'Backward design tells us which earlier capabilities are genuinely necessary.'}, {'prompt': 'What is a mastery gate for?', 'options': ['To punish the learner for moving too slowly', 'To check whether a notebook file exists', 'To state the concrete ability that marks real progress'], 'correct_index': 2, 'explanation': 'A mastery gate defines the real competence to be owned.'}, {'prompt': 'What is the difference between a topic list and an apprenticeship path?', 'options': ['An apprenticeship path changes who the learner can be as a designer', 'A topic list always uses more notebooks', 'An apprenticeship path avoids all quizzes'], 'correct_index': 0, 'explanation': 'The apprenticeship model is about identity and capability growth, not just exposure.'}], heading='Professional Path Quiz A')\n"
- ],
- "id": "fe5b5282"
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## What You Should Feel After Reading This Notebook\n",
- "\n",
- "You should not feel that the path is easy. You should feel that the path is finally legible. A serious course does not pretend that mastery comes cheaply. It tries to make the staircase visible, so that each step can be attacked honestly and deliberately. That is the role of this notebook. Once you understand the staircase, the opening technical notebooks should feel like the first rungs of a long but coherent climb.\n"
- ],
- "id": "8f8df1e1"
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "from quantum_learning.interactive import reflection_box\n",
- "\n",
- "reflection_box(\"List the three most important professional subskills you are currently missing.\")\n"
- ],
- "id": "e7ce1be6"
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "quiz_block([{'prompt': 'Which statement is closest to the terminal goal of the course?', 'options': ['Be able to run Qiskit notebooks locally', 'Become an independent hardware-aware circuit designer', 'Memorize the major gate families'], 'correct_index': 1, 'explanation': 'The course aims much higher than local execution literacy.'}, {'prompt': 'How should you interpret beginner notebooks after reading this notebook?', 'options': ['As trivial material to finish quickly', 'As prerequisites that install the language and mental models for later design work', 'As optional supplements that can be skipped'], 'correct_index': 1, 'explanation': 'The foundational notebooks are prerequisites for later engineering judgment.'}, {'prompt': 'What is the next action after this notebook?', 'options': ['Start the technical sequence and study it with prediction, quizzes, and editable labs', 'Jump directly to the capstone notebook', 'Ignore the quizzes because the text is enough'], 'correct_index': 0, 'explanation': 'The technical sequence is where the blueprint turns into training.'}], heading='Professional Path Quiz B')\n"
- ],
- "id": "5e662da9"
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "quiz_block([{'prompt': 'What changes most across the course stages?', 'options': ['Only the number of gates in the examples', 'The unit of thought, from local syntax toward patterns, constraints, and tradeoffs', 'Only the notebook length'], 'correct_index': 1, 'explanation': 'The course is designed to change how you see and reason about circuits, not just how many examples you have seen.'}, {'prompt': 'Why is backward design valuable for an ambitious learner?', 'options': ['It translates ambition into visible prerequisite capabilities', 'It removes the need for staged practice', 'It guarantees that advanced material will feel easy'], 'correct_index': 0, 'explanation': 'Backward design turns a distant goal into a concrete prerequisite ladder.'}, {'prompt': 'What is a healthy interpretation of being at an early stage?', 'options': ['It means advanced work is irrelevant', 'It means you are missing specific subskills that can be named and trained', 'It means you should avoid self-explanation until later'], 'correct_index': 1, 'explanation': 'Stage language is meant to improve diagnosis, not to freeze identity.'}], heading='Professional Path Quiz C')\n"
- ],
- "id": "457d5f43"
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Your Responsibility As The Learner\n",
- "\n",
- "The platform can provide structure, explanations, and interaction, but it cannot do the decisive act for you: honest engagement. That means answering the quizzes without peeking, editing the labs rather than merely admiring them, and writing reflections precise enough that another engineer could understand what you currently do and do not know. If you do that, the notebooks become apprenticeship tools. If you do not, they collapse back into passive reading material.\n"
- ],
- "id": "6f6791b1"
- }
- ],
- "metadata": {
- "kernelspec": {
- "display_name": "QuantumLearning (.venv)",
- "language": "python",
- "name": "quantum-learning"
- },
- "language_info": {
- "name": "python",
- "version": "3.12"
- }
- },
- "nbformat": 4,
- "nbformat_minor": 5
-}
diff --git a/scripts/build_course_notebooks.py b/scripts/build_course_notebooks.py
index 73f30f6..70eade0 100644
--- a/scripts/build_course_notebooks.py
+++ b/scripts/build_course_notebooks.py
@@ -662,7 +662,7 @@ def build_start_here() -> dict:
"""
# Start Here
- This notebook is the front door of the course. Its job is to tell you how to use the platform so that the later notebooks do not feel like disconnected technical fragments. The platform is intended to function like a notebook-based textbook plus lab manual plus design studio. If you only click through cells, you will get much less from it than the structure is designed to offer.
+ This notebook is the only supported starting point for the course. Its job is to tell you how to use the platform so that the later notebooks do not feel like disconnected technical fragments. The platform is intended to function like a notebook-based textbook plus lab manual plus design studio. If you only click through cells, you will get much less from it than the structure is designed to offer.
"""
),
markdown_cell(
@@ -685,8 +685,6 @@ def build_start_here() -> dict:
## What To Do In Your First Session
Read the rest of this notebook, then open `COURSE_BLUEPRINT.ipynb`. That is the first serious orientation notebook in the enforced mainline path. After that, follow the notebook-to-notebook handoff from inside the notebooks themselves instead of guessing from the filesystem.
-
- If you later want the deeper mastery-map background, use `reference/PROFESSIONAL_PATH.ipynb` as an optional side reference. It is not the next required notebook in the first-pass learner journey.
"""
),
code_cell(SETUP_CELL),
@@ -840,7 +838,7 @@ reflection_box("Write down what you expect a professional circuit designer to be
"""
## Final Instruction
- Open `COURSE_BLUEPRINT.ipynb` next. Then follow the mainline handoff from notebook to notebook. `reference/PROFESSIONAL_PATH.ipynb` is optional and not required for the first pass. The notebooks are now written to be read in detail, quizzed actively, and modified interactively. That is the intended workflow.
+ Open `COURSE_BLUEPRINT.ipynb` next. Then follow the mainline handoff from notebook to notebook. Do not branch away from that route on the first run. The notebooks are now written to be read in detail, quizzed actively, and modified interactively. That is the intended workflow.
"""
),
]
@@ -853,7 +851,7 @@ def build_professional_path() -> dict:
"""
# Professional Path
- This notebook is the didactical map of the course. Its purpose is to answer the question: what must be learned, mastered, and defended at every stage if the final goal is genuine professional circuit design rather than superficial tool familiarity?
+ This notebook is the hidden didactical map of the course. It is not part of the supported consumer route. Its purpose is to answer the question: what must be learned, mastered, and defended at every stage if the final goal is genuine professional circuit design rather than superficial tool familiarity?
"""
),
markdown_cell(
@@ -2008,16 +2006,19 @@ def build_readme_notebook_redirect() -> None:
def build_all() -> None:
NOTEBOOKS_DIR.mkdir(parents=True, exist_ok=True)
- outputs: dict[str, dict] = {
- "START_HERE.ipynb": build_start_here(),
- "PROFESSIONAL_PATH.ipynb": build_professional_path(),
+ outputs: dict[Path, dict] = {
+ NOTEBOOKS_DIR / "START_HERE.ipynb": build_start_here(),
+ NOTEBOOKS_DIR / ".reference" / "PROFESSIONAL_PATH.ipynb": build_professional_path(),
}
for spec in TECHNICAL_SPECS:
- outputs[spec.filename] = build_technical_notebook(spec)
+ outputs[NOTEBOOKS_DIR / ".legacy_single_notebook_path" / spec.filename] = (
+ build_technical_notebook(spec)
+ )
- for filename, payload in outputs.items():
- with (NOTEBOOKS_DIR / filename).open("w", encoding="utf-8") as handle:
+ for output_path, payload in outputs.items():
+ output_path.parent.mkdir(parents=True, exist_ok=True)
+ with output_path.open("w", encoding="utf-8") as handle:
json.dump(payload, handle, indent=1)
handle.write("\n")
diff --git a/scripts/build_world_class_bundle.py b/scripts/build_world_class_bundle.py
index 4f0434c..3b6930f 100644
--- a/scripts/build_world_class_bundle.py
+++ b/scripts/build_world_class_bundle.py
@@ -596,7 +596,7 @@ curriculum = load_curriculum()
"""
## What To Open Next
- The full technical mainline is now rebuilt. Start with **Principles and Circuit Literacy**, continue through the rest of the foundations modules, then move into **Circuit Construction and Analysis**, **Transpilation and Visualization**, and **Simulation and Noise Models**, then continue into **Deutsch Family and Oracle Thinking**, **Bernstein-Vazirani and Structured Oracles**, **QFT and Periodic Structure**, and **Grover and Amplitude Amplification**, and finally complete the professional band with **Qiskit Patterns and Workflow Design**, **Hardware-Aware Redesign Studio**, **Noise-Aware Verification and Mitigation**, and **Capstone Circuit Design Review**. Inside each module, read the lecture notebook first. Then move into the lab, then problems, then the studio. Do not reverse that order unless you are deliberately revising.
+ The full technical mainline is now rebuilt. Start with **Principles and Circuit Literacy**, continue through the rest of the foundations modules, then move into **Circuit Construction and Analysis**, **Transpilation and Visualization**, and **Simulation and Noise Models**, then continue into **Deutsch Family and Oracle Thinking**, **Bernstein-Vazirani and Structured Oracles**, **QFT and Periodic Structure**, and **Grover and Amplitude Amplification**, and finally complete the professional band with **Qiskit Patterns and Workflow Design**, **Hardware-Aware Redesign Studio**, **Noise-Aware Verification and Mitigation**, and **Capstone Circuit Design Review**. Inside each module, read the lecture notebook first. Then move into the lab, then problems, then the studio. Keep that order.
The sequence matters. If you jump straight into the studio, you may produce activity without comprehension. If you stop after the lecture, you may feel recognition without control. The four-notebook loop is the point.
"""
@@ -657,7 +657,7 @@ curriculum = load_curriculum()
4. Repeat the same loop in `module_03_gates_and_measurement`
5. Continue with `qiskit_engineering/module_01_circuit_construction_and_analysis`
6. Then complete `module_02_transpilation_and_visualization` and `module_03_simulation_and_noise_models`
- 7. Only then return to the later single-notebook materials as transition content
+ 7. Continue following the explicit next-notebook handoff until `COURSE_COMPLETE.ipynb`
That is the new mainline.
"""
diff --git a/scripts/harden_course_flow.py b/scripts/harden_course_flow.py
index 33373de..1e7f0a2 100644
--- a/scripts/harden_course_flow.py
+++ b/scripts/harden_course_flow.py
@@ -4,6 +4,7 @@ from __future__ import annotations
import hashlib
import json
from pathlib import Path
+import shutil
from quantum_learning import (
canonical_course_steps,
@@ -93,10 +94,10 @@ def replace_text(path: Path, replacements: list[tuple[str, str]]) -> None:
def insert_reference_note(path: Path) -> None:
notebook = load_notebook(path)
note = markdown_cell(
- "## Optional Deep-Dive Reference\n\n"
- "This notebook is not part of the mandatory first-pass mainline. "
- "Use it when you want the full backward-designed mastery map in more depth. "
- "For the mainline flow, return to `../COURSE_BLUEPRINT.ipynb` and follow the next-notebook handoff there."
+ "## Hidden Reference Notebook\n\n"
+ "This notebook is intentionally hidden from the visible Jupyter root. "
+ "It exists as an internal deep-reference document, not as part of the supported consumer route. "
+ "The supported learner path is `../START_HERE.ipynb -> ../COURSE_BLUEPRINT.ipynb -> mainline bundles -> ../COURSE_COMPLETE.ipynb`."
)
if any(NAV_TOP_MARKER in "".join(cell.get("source", [])) for cell in notebook["cells"]):
pass
@@ -126,8 +127,8 @@ def build_course_complete() -> None:
markdown_cell(
"## What To Do Next\n\n"
"1. Revisit the hardest studio notebooks and tighten your written design judgements.\n"
- "2. Use `notebooks/reference/PROFESSIONAL_PATH.ipynb` if you want the long-range mastery map again.\n"
- "3. Extend the capstone with your own circuit family and defend the design choices in writing.\n"
+ "2. Extend the capstone with your own circuit family and defend the design choices in writing.\n"
+ "3. Repeat a full module bundle deliberately only when you know exactly which skill you are repairing.\n"
"4. Only after that, add external hardware targets or new research notebooks."
),
markdown_cell(
@@ -143,12 +144,32 @@ def move_optional_and_legacy_notebooks() -> None:
REFERENCE_DIR.mkdir(parents=True, exist_ok=True)
LEGACY_DIR.mkdir(parents=True, exist_ok=True)
+ visible_reference_dir = NOTEBOOKS / "reference"
+ if visible_reference_dir.exists() and not REFERENCE_DIR.exists():
+ visible_reference_dir.rename(REFERENCE_DIR)
+
root_professional_path = NOTEBOOKS / "PROFESSIONAL_PATH.ipynb"
if root_professional_path.exists():
target = reference_notebook_path()
target.parent.mkdir(parents=True, exist_ok=True)
root_professional_path.replace(target)
+ visible_reference_path = visible_reference_dir / "PROFESSIONAL_PATH.ipynb"
+ if visible_reference_path.exists() and visible_reference_path != reference_notebook_path():
+ reference_notebook_path().parent.mkdir(parents=True, exist_ok=True)
+ visible_reference_path.replace(reference_notebook_path())
+
+ if visible_reference_dir.exists():
+ for child in sorted(visible_reference_dir.iterdir()):
+ target = REFERENCE_DIR / child.name
+ if target.exists():
+ continue
+ shutil.move(str(child), str(target))
+
+ remaining = list(visible_reference_dir.iterdir())
+ if not remaining:
+ visible_reference_dir.rmdir()
+
for notebook_name in LEGACY_SINGLE_NOTEBOOKS:
source = NOTEBOOKS / notebook_name
if source.exists():
@@ -183,13 +204,21 @@ def ensure_navigation() -> None:
f"{next_line}\n\n"
"Rule: finish this notebook top-to-bottom before you open the next one."
)
- bottom_text = (
- f"{NAV_BOTTOM_MARKER}\n"
- "## What To Open Next\n\n"
- f"{next_line}\n\n"
- "If this notebook still feels unstable, repeat it before you move on. "
- "The mainline only works if each handoff is earned."
- )
+ if next_step is None:
+ bottom_text = (
+ f"{NAV_BOTTOM_MARKER}\n"
+ "## What To Open Next\n\n"
+ f"{next_line}\n\n"
+ "This is the end of the guarded mainline route."
+ )
+ else:
+ bottom_text = (
+ f"{NAV_BOTTOM_MARKER}\n"
+ "## What To Open Next\n\n"
+ f"{next_line}\n\n"
+ "When you finish this notebook, open the next notebook shown above. "
+ "Stay on the guarded mainline route."
+ )
top_cell = markdown_cell(top_text)
bottom_cell = markdown_cell(bottom_text)
@@ -234,15 +263,15 @@ def main() -> None:
[
(
"Read the rest of this notebook, then open `PROFESSIONAL_PATH.ipynb`. That notebook explains the backward-designed apprenticeship model behind the entire course. After that, return and begin the technical sequence at `00_circuit_literacy.ipynb`.\n\nThe reason for this order is simple. If you do not know the target profession, the beginner material feels either trivial or arbitrary. Once you know the target profession, the same material reads as deliberate foundation-building.",
- "Read the rest of this notebook, then open `COURSE_BLUEPRINT.ipynb`. That is the first serious orientation notebook in the enforced mainline path. After that, follow the notebook-to-notebook handoff from inside the notebooks themselves instead of guessing from the filesystem.\n\nIf you later want the deeper mastery-map background, use `reference/PROFESSIONAL_PATH.ipynb` as an optional side reference. It is not the next required notebook in the first-pass learner journey.",
+ "Read the rest of this notebook, then open `COURSE_BLUEPRINT.ipynb`. That is the first serious orientation notebook in the enforced mainline path. After that, follow the notebook-to-notebook handoff from inside the notebooks themselves instead of guessing from the filesystem.",
),
(
"After this notebook, open `PROFESSIONAL_PATH.ipynb`. Then move into `00_circuit_literacy.ipynb`.",
- "After this notebook, open `COURSE_BLUEPRINT.ipynb`. Then begin `foundations/module_01_principles_and_circuit_literacy/lecture.ipynb`. If you want the deeper mastery map later, use `reference/PROFESSIONAL_PATH.ipynb` as an optional side reference.",
+ "After this notebook, open `COURSE_BLUEPRINT.ipynb`. Then begin `foundations/module_01_principles_and_circuit_literacy/lecture.ipynb`.",
),
(
"Open `PROFESSIONAL_PATH.ipynb` next. Then begin the technical sequence.",
- "Open `COURSE_BLUEPRINT.ipynb` next. Then follow the mainline handoff from notebook to notebook. `reference/PROFESSIONAL_PATH.ipynb` is optional and not required for the first pass.",
+ "Open `COURSE_BLUEPRINT.ipynb` next. Then follow the mainline handoff from notebook to notebook. Do not branch away from that route on the first run.",
),
(
"'What should you open immediately after this notebook?', 'options': ['The capstone review notebook', 'The README again', 'PROFESSIONAL_PATH.ipynb'], 'correct_index': 2, 'explanation': 'The professional path notebook gives the didactical context for the whole curriculum.'",
@@ -267,8 +296,8 @@ def main() -> None:
"This notebook is the first serious orientation notebook after `START_HERE.ipynb`.",
),
(
- "5. Continue with `qiskit_engineering`, then `algorithms`, then `professional` using the same bundle rhythm",
- "5. Continue with `qiskit_engineering`, then `algorithms`, then `professional` using the same bundle rhythm\n6. Use `reference/PROFESSIONAL_PATH.ipynb` only if you want the optional deep mastery map",
+ "7. Only then return to the later single-notebook materials as transition content",
+ "7. Continue following the explicit next-notebook handoff until `COURSE_COMPLETE.ipynb`",
),
],
)
diff --git a/src/quantum_learning/course_flow.py b/src/quantum_learning/course_flow.py
index 142b5ad..efe490d 100644
--- a/src/quantum_learning/course_flow.py
+++ b/src/quantum_learning/course_flow.py
@@ -50,7 +50,7 @@ def completion_notebook_path() -> Path:
def reference_notebook_path() -> Path:
- return notebooks_root() / "reference" / "PROFESSIONAL_PATH.ipynb"
+ return notebooks_root() / ".reference" / "PROFESSIONAL_PATH.ipynb"
def legacy_archive_dir() -> Path:
@@ -66,7 +66,6 @@ def visible_notebook_root_names() -> tuple[str, ...]:
"qiskit_engineering",
"algorithms",
"professional",
- "reference",
)
diff --git a/tests/test_course_flow.py b/tests/test_course_flow.py
index cc26174..5124041 100644
--- a/tests/test_course_flow.py
+++ b/tests/test_course_flow.py
@@ -32,6 +32,7 @@ def test_visible_notebook_root_is_curated():
def test_reference_notebook_is_not_in_root():
assert reference_notebook_path().exists()
assert not (project_root() / "notebooks" / "PROFESSIONAL_PATH.ipynb").exists()
+ assert not (project_root() / "notebooks" / "reference").exists()
def test_mainline_course_notebooks_have_navigation_guardrails():
@@ -57,4 +58,29 @@ def test_start_here_does_not_contain_stale_branching_advice():
assert "Read the rest of this notebook, then open `PROFESSIONAL_PATH.ipynb`." not in text
assert "Open `PROFESSIONAL_PATH.ipynb` next." not in text
assert "`00_circuit_literacy.ipynb`" not in text
+ assert "first-pass learner journey" not in text
+ assert "optional side reference" not in text
assert "COURSE_BLUEPRINT.ipynb" in text
+
+
+def test_mainline_route_text_is_single_pass_and_non_branching():
+ notebook_paths = [
+ project_root() / "notebooks" / "START_HERE.ipynb",
+ project_root() / "notebooks" / "COURSE_BLUEPRINT.ipynb",
+ project_root() / "notebooks" / "COURSE_COMPLETE.ipynb",
+ ]
+ banned_fragments = [
+ "PROFESSIONAL_PATH.ipynb",
+ "first-pass",
+ "optional side reference",
+ "Only then return to the later single-notebook materials as transition content",
+ "If this notebook still feels unstable, repeat it before you move on.",
+ ]
+
+ for path in notebook_paths:
+ text = _notebook_text(path)
+ for fragment in banned_fragments:
+ assert fragment not in text
+
+ course_complete_text = _notebook_text(project_root() / "notebooks" / "COURSE_COMPLETE.ipynb")
+ assert "This is the end of the guarded mainline route." in course_complete_text
diff --git a/tests/test_notebook_pedagogy.py b/tests/test_notebook_pedagogy.py
index 8fcc26a..0ecc250 100644
--- a/tests/test_notebook_pedagogy.py
+++ b/tests/test_notebook_pedagogy.py
@@ -47,7 +47,7 @@ def test_legacy_single_notebook_sequence_is_hidden_from_main_view():
def test_orientation_notebooks_are_substantial():
start_stats = _notebook_stats("START_HERE.ipynb")
- path_stats = _notebook_stats("reference/PROFESSIONAL_PATH.ipynb")
+ path_stats = _notebook_stats(".reference/PROFESSIONAL_PATH.ipynb")
assert start_stats["word_count"] >= 1500
assert start_stats["quiz_blocks"] >= 2
diff --git a/tests/test_project_experience.py b/tests/test_project_experience.py
index 7f25fd9..eaba459 100644
--- a/tests/test_project_experience.py
+++ b/tests/test_project_experience.py
@@ -6,7 +6,8 @@ def test_start_here_notebook_exists():
def test_professional_path_notebook_exists():
- assert (project_root() / "notebooks" / "reference" / "PROFESSIONAL_PATH.ipynb").exists()
+ assert (project_root() / "notebooks" / ".reference" / "PROFESSIONAL_PATH.ipynb").exists()
+ assert not (project_root() / "notebooks" / "reference").exists()
def test_course_blueprint_notebook_exists():