saymrwulf/QuantumLearning
1
0
Fork 0
mirror of https://github.com/saymrwulf/QuantumLearning.git synced 2026-06-03 23:49:52 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Fix contradictory start-here course guidance

Browse source
This commit is contained in:
saymrwulf 2026-04-15 16:49:46 +02:00
parent 881d02b236
commit 32180ddcbd
4 changed files with 192 additions and 60 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

221
notebooks/START_HERE.ipynb
View file

@ -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"
],
"id": "fa7f5f3a"
]
},
{
"cell_type": "markdown",
@ -29,6 +29,7 @@
},
{
"cell_type": "markdown",
"id": "dba3362b",
"metadata": {},
"source": [
"## How To Read The Course\n",
@ -42,25 +43,33 @@
"- 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 `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",
"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",
"The 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.\n"
],
"id": "a62cfee3"
"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"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"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"
}
},
"outputs": [],
"source": [
"from pathlib import Path\n",
@ -73,14 +82,35 @@
"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": null,
"metadata": {},
"outputs": [],
"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"
}
],
"source": [
"from quantum_learning import load_curriculum, load_mastery_blueprint\n",
"from quantum_learning.interactive import quiz_block\n",
@ -93,11 +123,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",
@ -105,11 +135,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",
@ -117,11 +147,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",
@ -133,11 +163,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",
@ -145,11 +175,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",
@ -157,11 +187,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",
@ -173,11 +203,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",
@ -185,60 +215,131 @@
"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": null,
"metadata": {},
"outputs": [],
"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=\"<h4 style='margin:0 0 0.6rem 0'>Start Here Quiz</h4>\"), VBox(children=(HTML(value='…"
]
},
"execution_count": 5,
"metadata": {},
"output_type": "execute_result"
}
],
"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', 'PROFESSIONAL_PATH.ipynb'], 'correct_index': 2, 'explanation': 'The professional path notebook gives the didactical context for the whole curriculum.'}], heading='Start Here Quiz')\n"
],
"id": "8e501151"
"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"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"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=\"<h4 style='margin:0 0 0.6rem 0'>Start Here Quiz B</h4>\"), VBox(children=(HTML(value…"
]
},
"execution_count": 7,
"metadata": {},
"output_type": "execute_result"
}
],
"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": null,
"metadata": {},
"outputs": [],
"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='<b>Write down what you expect a professional circuit designer to be able to do that…"
]
},
"execution_count": 8,
"metadata": {},
"output_type": "execute_result"
}
],
"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"
],
"id": "480ab187"
]
},
{
"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"
],
"id": "def4360d"
]
},
{
"cell_type": "markdown",
@ -252,6 +353,14 @@
"If this notebook still feels unstable, repeat it before you move on. The mainline only works if each handoff is earned.\n"
],
"id": "7efd4648"
},
{
"cell_type": "code",
"execution_count": null,
"id": "b2f4a5e3",
"metadata": {},
"outputs": [],
"source": []
}
],
"metadata": {
@ -261,8 +370,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,

12
scripts/build_course_notebooks.py
View file

@ -684,9 +684,9 @@ def build_start_here() -> dict:
"""
## What To Do In Your First Session
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`.
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.
The 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.
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),
@ -779,10 +779,10 @@ curriculum = load_curriculum()
"options": [
"The capstone review notebook",
"The README again",
"PROFESSIONAL_PATH.ipynb",
"COURSE_BLUEPRINT.ipynb",
],
"correct_index": 2,
"explanation": "The professional path notebook gives the didactical context for the whole curriculum.",
"explanation": "Course Blueprint is the next required notebook in the guarded mainline path.",
},
],
"Start Here Quiz",
@ -833,14 +833,14 @@ reflection_box("Write down what you expect a professional circuit designer to be
"""
## How To Continue After This Notebook
After this notebook, open `PROFESSIONAL_PATH.ipynb`. Then move into `00_circuit_literacy.ipynb`. 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.
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.
"""
),
markdown_cell(
"""
## Final Instruction
Open `PROFESSIONAL_PATH.ipynb` next. Then begin the technical sequence. 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. `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.
"""
),
]

10
scripts/harden_course_flow.py
View file

@ -79,8 +79,6 @@ def replace_text(path: Path, replacements: list[tuple[str, str]]) -> None:
notebook = load_notebook(path)
changed = False
for cell in notebook.get("cells", []):
if cell.get("cell_type") != "markdown":
continue
text = "".join(cell.get("source", []))
original = text
for old, new in replacements:
@ -234,6 +232,10 @@ def main() -> None:
replace_text(
entry_notebook_path(),
[
(
"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.",
),
(
"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.",
@ -242,6 +244,10 @@ def main() -> None:
"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.",
),
(
"'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.'",
"'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.'",
),
],
)
replace_text(

9
tests/test_course_flow.py
View file

@ -49,3 +49,12 @@ def test_mainline_course_notebooks_have_navigation_guardrails():
assert next_title in text
else:
assert "This notebook closes the mainline course" in text
def test_start_here_does_not_contain_stale_branching_advice():
text = _notebook_text(project_root() / "notebooks" / "START_HERE.ipynb")
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 "COURSE_BLUEPRINT.ipynb" in text