QuantumLearning/notebooks/professional/module_04_capstone_design_review/lecture.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# Capstone Circuit Design Review Lecture\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "The capstone is where the whole curriculum finally behaves like professional engineering. Earlier modules taught pieces of the job: literacy, circuit construction, algorithmic reasoning, workflow design, topology-aware redesign, and noise-aware verification. The capstone asks you to combine them into a single act of judgement. A design brief is stated. Multiple candidates are created. Each candidate is benchmarked under the declared local assumptions. A winner is recommended. Risks are named. The notebook becomes a design review rather than a guided tour.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Learning Objective\n",
        "\n",
        "\n",
        "            By the end of this lecture you should be able to define a constrained design brief, keep several plausible candidate circuits alive long enough to compare them credibly, benchmark them across ideal, compiled, and noisy lenses, and write a recommendation that names the chosen candidate, the evidence that supports it, and the conditions under which the conclusion might change.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "The first capstone skill is resisting premature attachment. Designers often fall in love with a candidate before the evidence exists. They like a particular circuit shape, a certain abstraction, or a favored intuition, and then the notebook becomes a search for confirmation. This module is built to oppose that habit. The brief comes first. The candidates come second. The recommendation comes last. That order is what protects the integrity of the comparison.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "A good design brief is tighter than a vague goal but looser than a predetermined winner. It says what the circuit should accomplish, what environment or constraint model matters, and what evidence will be used to compare success. In a local-first capstone, that often means ideal behavior, compiled burden under a declared topology, and noisy support under a local noise model. Those lenses do not tell the same story, which is precisely why the capstone needs all of them.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Candidate generation is also more disciplined than it first appears. The point is not to invent random variants and hope one looks impressive. The point is to propose alternatives that are plausible enough to deserve comparison and distinct enough to reveal tradeoffs. In this module the candidate family is intentionally small so the review burden stays visible. But the pattern is the same one you would use on larger work: define a brief, create multiple credible candidates, and let the evidence eliminate or elevate them.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Benchmarking across several lenses is what turns the notebook into a review artifact. Ideal behavior tells you whether the intended mechanism exists. Compiled cost under fixed constraints tells you what the implementation burden looks like. Noisy support tells you whether a candidate that seems elegant on paper survives a more realistic local model. None of these lenses alone is a sufficient verdict. The capstone teaches you how to hold them together without becoming vague.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Recommendation writing is the final skill. A weak recommendation says which candidate won. A strong recommendation says why it won under the declared brief and what risks remain. That risk sentence matters. It prevents the common capstone failure in which a local comparison is quietly treated as a universal theorem. Professional reviews are stronger when they are conditional in the right way. They say: under these assumptions, with this evidence, this is the candidate I recommend.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "The capstone therefore closes the course on the right standard. It does not ask whether you can produce a circuit. It asks whether you can think like the person responsible for choosing and defending one. That is the difference between notebook completion and professional design judgement.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "from pathlib import Path\n",
        "import sys\n",
        "\n",
        "project_root = Path.cwd().resolve()\n",
        "while not (project_root / \"pyproject.toml\").exists():\n",
        "    if project_root.parent == project_root:\n",
        "        raise RuntimeError(\"Could not locate the project root from this notebook.\")\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,
      "metadata": {},
      "outputs": [],
      "source": [
        "from quantum_learning import (\n",
        "    build_demo_noise_model,\n",
        "    counts_to_probabilities,\n",
        "    draw_circuit,\n",
        "    editable_circuit_lab,\n",
        "    line_coupling_map,\n",
        "    plot_counts,\n",
        "    plot_probabilities,\n",
        "    quiz_block,\n",
        "    reflection_box,\n",
        "    simulate_counts,\n",
        "    statevector_probabilities,\n",
        "    step_reference_table,\n",
        "    transpile_summary,\n",
        ")\n",
        "from qiskit import QuantumCircuit\n",
        "from qiskit.providers.basic_provider import BasicSimulator\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Code-To-Diagram Anchor\n",
        "\n",
        "\n",
        "            The capstone anchor uses a small GHZ-style design brief under line-topology and noisy local assumptions. The circuit family is intentionally limited. The goal is not breadth of search. The goal is depth of comparison and clarity of recommendation.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "step_reference_table([{'marker': '[1]', 'code_focus': 'State the design brief and the constraints before generating any candidate.', 'diagram_effect': 'Every candidate diagram is read as an answer to a shared constrained question.', 'why_it_matters': 'Capstone work starts from explicit objective, not from attachment to a favorite circuit shape.'}, {'marker': '[2]', 'code_focus': 'Generate more than one plausible candidate family.', 'diagram_effect': 'The notebook contains alternatives instead of a single self-congratulatory path.', 'why_it_matters': 'Professional design requires comparison, not only construction.'}, {'marker': '[3]', 'code_focus': 'Benchmark ideal, compiled, and noisy behavior with the same reporting contract.', 'diagram_effect': 'Each candidate can be judged across several evidence layers.', 'why_it_matters': 'Recommendations are credible only when they survive more than one lens.'}, {'marker': '[4]', 'code_focus': 'Write a recommendation that names tradeoffs, risks, and why one candidate wins.', 'diagram_effect': 'The notebook ends as a design review, not a gallery.', 'why_it_matters': 'The capstone is about defended judgment under constraints.'}])\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "LOCAL_BASIS = [\"rz\", \"sx\", \"x\", \"cx\"]\n",
        "capstone_noise = build_demo_noise_model(\n",
        "    single_qubit_error=0.01,\n",
        "    two_qubit_error=0.04,\n",
        "    readout_error=0.02,\n",
        ")\n",
        "\n",
        "def simulate_capstone_counts(circuit, shots=256):\n",
        "    return simulate_counts(\n",
        "        circuit,\n",
        "        shots=shots,\n",
        "        noise_model=capstone_noise,\n",
        "        basis_gates=LOCAL_BASIS,\n",
        "        coupling_map=line_coupling_map(circuit.num_qubits),\n",
        "        optimization_level=1,\n",
        "    )\n",
        "\n",
        "        editable_code = '\\nfrom qiskit import QuantumCircuit\\n\\ndef ghz_candidate(style: str = \"middle_root\") -> QuantumCircuit:\\n    circuit = QuantumCircuit(3, 3)\\n    if style == \"naive\":\\n        circuit.h(0)\\n        circuit.cx(0, 1)\\n        circuit.cx(0, 2)\\n    elif style == \"chain\":\\n        circuit.h(0)\\n        circuit.cx(0, 1)\\n        circuit.cx(1, 2)\\n    elif style == \"middle_root\":\\n        circuit.h(1)\\n        circuit.cx(1, 0)\\n        circuit.cx(1, 2)\\n    else:\\n        raise ValueError(\"style must be naive, chain, or middle_root\")\\n    circuit.measure([0, 1, 2], [0, 1, 2])\\n    return circuit\\n\\ncircuit = ghz_candidate(style=\"middle_root\")\\n'\n",
        "        editable_circuit_lab(\n",
        "            initial_code=editable_code,\n",
        "            context={\"QuantumCircuit\": QuantumCircuit, \"simulate_counts\": simulate_capstone_counts},\n",
        "            title='Capstone Circuit Design Review Anchor',\n",
        "            instructions='Edit one structural burden at a time and use the reference table to keep the code and the engineering story aligned.',\n",
        "            shots=256,\n",
        "        )\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "LOCAL_BASIS = [\"rz\", \"sx\", \"x\", \"cx\"]\n",
        "capstone_noise = build_demo_noise_model(\n",
        "    single_qubit_error=0.01,\n",
        "    two_qubit_error=0.04,\n",
        "    readout_error=0.02,\n",
        ")\n",
        "\n",
        "def ghz_candidate(style: str) -> QuantumCircuit:\n",
        "    circuit = QuantumCircuit(3, 3)\n",
        "    if style == \"naive\":\n",
        "        circuit.h(0)\n",
        "        circuit.cx(0, 1)\n",
        "        circuit.cx(0, 2)\n",
        "    elif style == \"chain\":\n",
        "        circuit.h(0)\n",
        "        circuit.cx(0, 1)\n",
        "        circuit.cx(1, 2)\n",
        "    elif style == \"middle_root\":\n",
        "        circuit.h(1)\n",
        "        circuit.cx(1, 0)\n",
        "        circuit.cx(1, 2)\n",
        "    else:\n",
        "        raise ValueError(\"style must be naive, chain, or middle_root\")\n",
        "    circuit.measure([0, 1, 2], [0, 1, 2])\n",
        "    return circuit\n",
        "\n",
        "def success_rate(counts: dict[str, int]) -> float:\n",
        "    probabilities = counts_to_probabilities(counts)\n",
        "    return round(probabilities.get(\"000\", 0.0) + probabilities.get(\"111\", 0.0), 3)\n",
        "\n",
        "def benchmark(style: str) -> dict[str, object]:\n",
        "    circuit = ghz_candidate(style)\n",
        "    compiled = transpile_summary(\n",
        "        circuit,\n",
        "        BasicSimulator(),\n",
        "        basis_gates=LOCAL_BASIS,\n",
        "        coupling_map=line_coupling_map(3),\n",
        "        optimization_level=1,\n",
        "    )\n",
        "    noisy_counts = simulate_counts(\n",
        "        circuit,\n",
        "        shots=256,\n",
        "        noise_model=capstone_noise,\n",
        "        basis_gates=LOCAL_BASIS,\n",
        "        coupling_map=line_coupling_map(3),\n",
        "        optimization_level=1,\n",
        "    )\n",
        "    return {\n",
        "        \"style\": style,\n",
        "        \"depth_after\": compiled[\"depth_after\"],\n",
        "        \"size_after\": compiled[\"size_after\"],\n",
        "        \"noisy_success\": success_rate(noisy_counts),\n",
        "        \"noisy_counts\": noisy_counts,\n",
        "    }\n",
        "\n",
        "[benchmark(style) for style in [\"naive\", \"chain\", \"middle_root\"]]\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "quiz_block([{'prompt': 'What distinguishes a capstone design notebook from an ordinary lab?', 'options': ['It must compare multiple plausible candidates under explicit constraints and end with a recommendation', 'It must avoid all metrics', 'It must use the largest circuit in the repo'], 'correct_index': 0, 'explanation': 'Capstone work is defined by comparative judgement and defended choice.'}, {'prompt': 'Why is a design brief necessary before candidate generation?', 'options': ['Because the winner depends on the stated objective and constraints, not on taste alone', 'Because it guarantees the first candidate is best', 'Because Qiskit requires one'], 'correct_index': 0, 'explanation': 'Without a brief, comparison becomes arbitrary.'}], heading='Lecture Checkpoint A')\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "A strong self-check for the capstone is whether you can say what would have changed your mind. If a recommendation survives only because the notebook never states what competing evidence would matter, then the recommendation is weaker than it looks. Professional judgement is strongest when it names the conditions under which it would shift.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Another self-check is whether your recommendation still sounds defensible when the circuit drawing is removed. If the only thing left is a preference for one diagram, the review is not done. A complete design review should remain legible as a brief, a set of candidates, a body of evidence, and a final recommendation with risks.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Reading Discipline For This Module\n",
        "\n",
        "The professional band demands slower reading than the earlier bands because the unit of judgment is larger. You are no longer inspecting only a circuit body. You are inspecting a design brief, a constraint model, a verification story, or a recommendation workflow. That means every notebook should be read with questions like these in mind: what burden is this stage carrying, what evidence would justify it, and what kind of failure would falsify the current explanation? If those questions stay active while you read, the notebook becomes training. If they disappear, the notebook becomes performance.\n",
        "\n",
        "Another discipline worth installing here is conditional confidence. Professional engineering rarely says only \"this works.\" It says \"under these assumptions, with this evidence, this is the choice I recommend.\" That conditional phrasing is not weakness. It is rigor. The purpose of the final band is to make that rigor normal in both your code and your prose.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Professional Review Habit\n",
        "\n",
        "Another habit worth building here is review-minded reading. Do not read these notebooks only as the author of the current code cell. Read them as the future reviewer who must decide whether the workflow, redesign, diagnosis, or recommendation is trustworthy. That reviewer wants to know what assumptions were fixed, what evidence was gathered, what remained uncertain, and what could still break if the surrounding constraints changed. Practicing that perspective now is what turns the final band into professional training instead of advanced entertainment.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Forward Link\n",
        "\n",
        "Every later notebook artifact in a real project will inherit the standards practiced here. Workflow patterns affect how experiments are reproduced. Hardware-aware redesign affects whether ideal elegance survives implementation. Verification determines whether bad results are diagnosed honestly. And capstone review determines whether a chosen circuit can actually be defended. The point of this band is not to add optional polish. It is to make the entire project behave like professional engineering work.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "quiz_block([{'prompt': 'What should a final recommendation include?', 'options': ['The winning candidate, the metrics and observations that favored it, and the risks that remain', 'Only the prettiest circuit diagram', 'Only the lowest ideal depth regardless of constraints'], 'correct_index': 0, 'explanation': 'Professional recommendations name both evidence and residual uncertainty.'}, {'prompt': 'Why benchmark ideal, compiled, and noisy behavior together?', 'options': ['Because a candidate can look good in one lens and weak in another', 'Because one lens always tells the whole story', 'Because the extra layers remove the need for prose'], 'correct_index': 0, 'explanation': 'Capstone judgement is multi-criteria, not single-metric worship.'}], heading='Lecture Checkpoint B')\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "reflection_box('Explain why a capstone recommendation must come after candidate comparison rather than before it.')\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "reflection_box('Describe one way a local comparison can still be professionally useful without claiming universal truth.')\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Mastery Gate\n",
        "\n",
        "Leave this lecture only when you can explain what evidence would justify the final professional judgment and what evidence would force you to revise it.\n"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "QuantumLearning (.venv)",
      "language": "python",
      "name": "quantum-learning"
    },
    "language_info": {
      "name": "python",
      "version": "3.12"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 5
}