QuantumLearning/notebooks/professional/module_01_qiskit_patterns/studio.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# Qiskit Patterns and Workflow Design Studio\n"
      ],
      "id": "6e357a6d"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "The studio turns the module into a design exercise: create a small workflow artifact that you would actually trust and hand to another engineer.\n"
      ],
      "id": "ac2066c6"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Design Brief\n",
        "\n",
        "\n",
        "            Build a compact local-first pattern notebook that exposes configuration, quantum routine, execution assumptions, and result interpretation clearly enough that a reviewer could modify one layer without guessing what the other layers are doing.\n"
      ],
      "id": "d0762ea9"
    },
    {
      "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"
      ],
      "id": "3e7046de"
    },
    {
      "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",
        "    evidence_checklist,\n",
        "    feedback_iteration_panel,\n",
        "    line_coupling_map,\n",
        "    load_assessment_blueprint,\n",
        "    plot_counts,\n",
        "    plot_probabilities,\n",
        "    quiz_block,\n",
        "    reflection_box,\n",
        "    rubric_scorecard,\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"
      ],
      "id": "2e8f1586"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Studio Prompt 1: Reusable Workflow Shell\n",
        "\n",
        "\n",
        "                    Create a small pattern shell that makes the stable routine visible and parameterizes the question being asked. The challenge is clarity, not size.\n"
      ],
      "id": "4d3bedea"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "editable_code = '\\nfrom qiskit import QuantumCircuit\\n\\ndef build_agreement_probe(basis: str = \"z\") -> QuantumCircuit:\\n    circuit = QuantumCircuit(2, 2)\\n    # [1] The workflow chooses the question before the circuit is built.\\n    circuit.h(0)\\n    circuit.cx(0, 1)\\n    # [2] Basis adaptation belongs in its own visible layer.\\n    if basis == \"x\":\\n        circuit.h([0, 1])\\n    elif basis != \"z\":\\n        raise ValueError(\"basis must be \\'z\\' or \\'x\\'\")\\n    # [3] Keep the reporting contract explicit.\\n    circuit.measure([0, 1], [0, 1])\\n    return circuit\\n\\ncircuit = build_agreement_probe(basis=\"x\")\\n'\n",
        "editable_circuit_lab(\n",
        "    initial_code=editable_code,\n",
        "    context={\"QuantumCircuit\": QuantumCircuit, \"simulate_counts\": simulate_counts},\n",
        "    title='Studio 1: Workflow Shell',\n",
        "    instructions='Refine the builder until the question layer and the stable circuit layer are visibly separate.',\n",
        "    shots=256,\n",
        ")\n"
      ],
      "id": "9b4e4dc5"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Studio Prompt 2: Explicit Result Record\n",
        "\n",
        "\n",
        "                    Turn the same pattern into a notebook that would still make sense a week later by recording what was asked and how the result should be interpreted.\n"
      ],
      "id": "85b6d849"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "editable_code = '\\nfrom qiskit import QuantumCircuit\\n\\ndef build_probe(basis: str = \"z\", add_barrier: bool = True) -> QuantumCircuit:\\n    circuit = QuantumCircuit(2, 2)\\n    circuit.h(0)\\n    circuit.cx(0, 1)\\n    if add_barrier:\\n        circuit.barrier()\\n    if basis == \"x\":\\n        circuit.h([0, 1])\\n    elif basis != \"z\":\\n        raise ValueError(\"basis must be \\'z\\' or \\'x\\'\")\\n    circuit.measure([0, 1], [0, 1])\\n    return circuit\\n\\ncircuit = build_probe(basis=\"z\", add_barrier=True)\\n'\n",
        "editable_circuit_lab(\n",
        "    initial_code=editable_code,\n",
        "    context={\"QuantumCircuit\": QuantumCircuit, \"simulate_counts\": simulate_counts},\n",
        "    title='Studio 2: Result Record Pattern',\n",
        "    instructions='Structure the pattern so a downstream result record could be attached without guessing hidden assumptions.',\n",
        "    shots=256,\n",
        ")\n"
      ],
      "id": "a7edd606"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Studio Prompt 3: Interface Audit\n",
        "\n",
        "\n",
        "                    Use the reporting-contract variant to write a short interface audit. If the reporting order changes, what else in the workflow must change with it?\n"
      ],
      "id": "7b69ef17"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "editable_code = '\\nfrom qiskit import QuantumCircuit\\n\\ndef build_probe(swapped_report: bool = False) -> QuantumCircuit:\\n    circuit = QuantumCircuit(2, 2)\\n    circuit.h(0)\\n    circuit.cx(0, 1)\\n    if swapped_report:\\n        circuit.measure([0, 1], [1, 0])\\n    else:\\n        circuit.measure([0, 1], [0, 1])\\n    return circuit\\n\\ncircuit = build_probe(swapped_report=False)\\n'\n",
        "editable_circuit_lab(\n",
        "    initial_code=editable_code,\n",
        "    context={\"QuantumCircuit\": QuantumCircuit, \"simulate_counts\": simulate_counts},\n",
        "    title='Studio 3: Interface Audit',\n",
        "    instructions='Treat the reporting map as an API decision and explain what a reviewer would need to know before trusting it.',\n",
        "    shots=256,\n",
        ")\n"
      ],
      "id": "1eb2905a"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "quiz_block([{'prompt': 'What is a strong studio deliverable for this module?', 'options': ['A small, configurable workflow notebook with a clear circuit builder and a reviewable result record', 'A single screenshot of one circuit', 'A notebook with no post-processing because counts are enough'], 'correct_index': 0, 'explanation': 'The studio should produce a reusable local-first pattern artifact.'}, {'prompt': 'Why is explicit workflow prose still necessary here?', 'options': ['Because the professional value of the notebook lies in the interfaces and decision logic as much as in the circuit', 'Because the circuit is unimportant', 'Because prose replaces execution'], 'correct_index': 0, 'explanation': 'The prose tells reviewers how the pattern is meant to be used and judged.'}], heading='Studio Design Check')\n"
      ],
      "id": "708f1703"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "evidence_checklist(['The notebook states the objective or decision clearly.', 'The relevant constraints are explicit and stable.', 'Evidence is tied to a concrete circuit, output, or metric.', 'At least one uncertainty or risk is named explicitly.', 'The notebook ends with a next action or defended judgement.'], title='Qiskit Patterns and Workflow Design Evidence Checklist')\n"
      ],
      "id": "aeaecc0e"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Studio Debrief\n",
        "\n",
        "\n",
        "            A strong studio notebook in this module feels like a small internal tool. It does not only show a circuit. It states how the circuit is being asked to act inside a wider local-first workflow and how the notebook arrives at its interpretation of the result.\n"
      ],
      "id": "b001b558"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Studio Standard\n",
        "\n",
        "A strong studio notebook is compact, explicit, and reviewable. It does not hide behind volume. It makes the objective clear, the candidate or case structure visible, the evidence traceable, and the final judgement conditional in the right way. If those things are not yet present, the notebook is not finished no matter how many cells it contains.\n"
      ],
      "id": "491a885e"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## What A Finished Studio Should Feel Like\n",
        "\n",
        "The finished notebook should feel like something another engineer could open and use. They should be able to understand what the notebook is trying to decide, how the circuits were compared, what evidence was gathered, and why the recommendation or diagnosis ended where it did. That is the practical definition of \"world-class\" in this project: not theatrical polish, but concentrated clarity under real engineering burdens.\n"
      ],
      "id": "eb6860f3"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Final Check Before You Stop\n",
        "\n",
        "Before you leave a studio notebook, ask one last question: if another engineer disagreed with my conclusion, would the notebook give them enough material to locate the disagreement precisely? If the answer is yes, the studio is doing its job.\n"
      ],
      "id": "490f8170"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "reflection_box('Which part of your workflow shell would another engineer most likely need to change first?')\n"
      ],
      "id": "51daae25"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "reflection_box('How did you make the reporting contract explicit in the final studio version?')\n"
      ],
      "id": "208ce431"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "reflection_box('What information did you decide belonged in the final result record?')\n"
      ],
      "id": "d73fd36d"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "reflection_box('Name one workflow habit from this module that should survive all later capstone work.')\n"
      ],
      "id": "e0b942fd"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "feedback_iteration_panel(title='Qiskit Patterns and Workflow Design Studio Revision Loop', prompt='Write the decision or diagnosis the studio currently supports, the evidence carrying that weight, the main remaining uncertainty, and the next revision that would sharpen the notebook.')\n"
      ],
      "id": "ed223f5d"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "assessment_blueprint = load_assessment_blueprint()\n",
        "rubric_scorecard(\n",
        "    assessment_blueprint.get_rubric('module_self_review'),\n",
        "    title='Qiskit Patterns and Workflow Design Studio Self-Grading',\n",
        ")\n"
      ],
      "id": "785a1779"
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "QuantumLearning (.venv)",
      "language": "python",
      "name": "quantum-learning"
    },
    "language_info": {
      "name": "python",
      "version": "3.12"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 5
}