QuantumLearning/notebooks/START_HERE.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Start Here\n",
    "\n",
    "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.\n"
   ],
   "id": "bbc2607f"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## How To Read The Course\n",
    "\n",
    "Every serious notebook in this repository is built around the same teaching loop:\n",
    "\n",
    "- extended lecture notes explain the concept and its professional purpose\n",
    "- multiple choice quizzes force retrieval instead of passive recognition\n",
    "- editable labs force you to alter the code and watch the diagram respond\n",
    "- analysis cells force you to interpret what you changed\n",
    "- 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": "700d7216"
  },
  {
   "cell_type": "markdown",
   "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",
    "\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": "d0d9c15e"
  },
  {
   "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": "ae2e065f"
  },
  {
   "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",
    "{\n",
    "    \"terminal_role\": blueprint.terminal_role,\n",
    "    \"stage_count\": len(blueprint.stages),\n",
    "    \"lesson_count\": len(curriculum),\n",
    "}\n"
   ],
   "id": "66d9c117"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The Structure You Are Entering\n",
    "\n",
    "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": "236e3bbc"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Why The Platform Is Becoming More Literary And More Interactive\n",
    "\n",
    "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": "e1dd5294"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Extended Orientation I\n",
    "\n",
    "A serious self-study notebook has to do more than present information. It has to manage attention. That is especially true in a subject like circuit design, where a beginner may not yet know which distinctions are foundational and which details are secondary. One function of this notebook is therefore to teach you how to allocate attention. You should not read the later technical notebooks the way you might skim a blog post or a quick-start guide. You should read them the way an apprentice studies a worked example in a demanding craft: slowly, with repeated passes, and with a willingness to stop at a single sentence until it becomes clear.\n",
    "\n",
    "This is also why the notebooks now contain much more lecture-style prose. Dense writing is doing practical work. It is telling you what the example is for, which misconception to avoid, which output deserves interpretation, and what ability you should be able to demonstrate at the end. Without that guidance, beginners often oscillate between two bad extremes. Either they feel intimidated by every line, or they rush through and assume that successful execution equals understanding. The course is trying to avoid both extremes.\n",
    "\n",
    "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": "d5d83991"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## How To Judge Whether A Notebook Worked\n",
    "\n",
    "The right metric is not \u201cdid I finish the notebook?\u201d The right metric is \u201cwhat can I now explain or modify that I could not explain or modify before?\u201d 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. \u201cI am lost\u201d is not yet a useful learning statement. \u201cI can draw the circuit, but I still cannot explain why that gate changes the support pattern\u201d is useful. The course is trying to move you from the first kind of statement to the second.\n"
   ],
   "id": "a07f88cd"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## What To Do When You Feel Lost\n",
    "\n",
    "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": "5c499fd3"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Extended Orientation II\n",
    "\n",
    "It is also worth being explicit about what \u201cinteractive\u201d should mean in this course. Interactivity is not a gimmick and it is not just a nicer user interface. Real interactivity means that the notebook reacts to your reasoning. A multiple choice quiz reacts by exposing whether your current explanation survives retrieval. An editable circuit lab reacts by revealing whether your explanation survives modification. A reflection box reacts by revealing whether your explanation survives translation into your own language. Those are different tests, and together they form a much stronger learning environment than code cells alone.\n",
    "\n",
    "This matters because circuit design is not one skill. It is a bundle of linked abilities: you have to read diagrams, map them to code, anticipate behavior, reason about structure, and communicate your understanding clearly enough that another engineer could review it. The course therefore uses several different interaction modes to exercise those different abilities. If you use only the code cells and ignore the quizzes or writing prompts, you are training only part of the required skill stack.\n",
    "\n",
    "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 \u201cbaby material\u201d 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": "6046bb7a"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Why The Platform Uses Multiple Choice Quizzes\n",
    "\n",
    "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": "53f413d9"
  },
  {
   "cell_type": "code",
   "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', '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": "3ef0c4f2"
  },
  {
   "cell_type": "code",
   "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": "fd484c2f"
  },
  {
   "cell_type": "code",
   "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": "fc1fa741"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## How To Continue After This Notebook\n",
    "\n",
    "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.\n"
   ],
   "id": "51e711c2"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Final Instruction\n",
    "\n",
    "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.\n"
   ],
   "id": "ecfb612f"
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "QuantumLearning (.venv)",
   "language": "python",
   "name": "quantum-learning"
  },
  "language_info": {
   "name": "python",
   "version": "3.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}