\n",
"\n",
"\n",
"## Mainline Navigation\n",
"\n",
"Step 32 of 59. Follow the official walkthrough in order.\n",
"\n",
"Previous notebook: [Bernstein-Vazirani and Structured Oracles Lecture](lecture.ipynb)\n",
"\n",
"Next notebook: [Bernstein-Vazirani and Structured Oracles Problems](problems.ipynb)\n",
"\n",
"Rule: complete the mandatory cells in this notebook before you open the next one.\n"
],
"id": "d787987a"
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"
\n",
"\n",
"The lab emphasizes three things: secret variation, bit-order discipline, and comparison between candidates that are behaviorally equivalent but structurally different. That is enough to make the module feel like engineering rather than recitation.\n"
],
"id": "abc967ef"
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"
\n",
"\n",
"## Lab Protocol\n",
"\n",
"\n",
" Change one family parameter at a time. When you alter the secret, say which oracle edges should change. When you alter the reporting order, say which interface claim you are changing. When you alter the helper shape, say why the new builder is easier or harder to audit.\n"
],
"id": "faf03ccf"
},
{
"cell_type": "markdown",
"metadata": {
"ql_injected": "badge",
"ql_track": "mandatory",
"ql_role": "setup"
},
"source": [
"\n",
"
\n",
"MANDATORY SETUP · Difficulty 1/10 · Environment, import, or helper cell required by the notebook.\n",
"
\n",
"\n",
"## Lab 1: Secret Variations\n",
"\n",
"\n",
" Use the parameterized builder as a real family, not as a single example with a variable name. Try several secrets and force yourself to predict which CNOT pattern they should induce before you render the circuit.\n"
],
"id": "862e8baf"
},
{
"cell_type": "markdown",
"metadata": {
"ql_injected": "badge",
"ql_track": "mandatory",
"ql_role": "exercise"
},
"source": [
"\n",
"
\n",
"MANDATORY EXERCISE · Difficulty 2/10 · Official walkthrough runnable or written exercise.\n",
"
\n"
],
"id": "85f3642b"
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"jupyter": {
"source_hidden": true
},
"tags": [
"hide-input"
]
},
"outputs": [],
"source": [
"step_reference_table([{'marker': '[1]', 'code_focus': 'Prepare every query wire in superposition and the ancilla in |->.', 'diagram_effect': 'The diagram begins with a wide preparation fan-out instead of a single branch.', 'why_it_matters': 'Bernstein-Vazirani asks one structured question about several bits at once.'}, {'marker': '[2]', 'code_focus': 'Route only the secret-controlled query wires into the ancilla.', 'diagram_effect': 'The oracle body visually highlights which secret bits are active.', 'why_it_matters': 'The hidden string is not mystical. It is literally the connectivity pattern inside the oracle.'}, {'marker': '[3]', 'code_focus': 'Apply final Hadamards to decode the hidden pattern back onto the query register.', 'diagram_effect': 'The second Hadamard layer closes the algorithmic sandwich.', 'why_it_matters': 'This is the moment where phase-encoded structure becomes classical evidence.'}, {'marker': '[4]', 'code_focus': 'Measure the query register in a bit order you can defend.', 'diagram_effect': 'The readout layer makes the interface contract explicit.', 'why_it_matters': 'Bit-order confusion is one of the easiest ways to sabotage an otherwise correct circuit.'}])\n"
],
"id": "23a5039a"
},
{
"cell_type": "markdown",
"metadata": {
"ql_injected": "badge",
"ql_track": "mandatory",
"ql_role": "exercise"
},
"source": [
"\n",
"
\n",
"MANDATORY EXERCISE · Difficulty 2/10 · Official walkthrough runnable or written exercise.\n",
"
\n"
],
"id": "12a4181c"
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"jupyter": {
"source_hidden": true
},
"tags": [
"hide-input"
]
},
"outputs": [],
"source": [
"editable_code = '\\nfrom qiskit import QuantumCircuit\\n\\ndef bv_oracle(secret: str = \"101\") -> QuantumCircuit:\\n oracle = QuantumCircuit(4, name=f\"bv_{secret}\")\\n ancilla = 3\\n for index, bit in enumerate(reversed(secret)):\\n if bit == \"1\":\\n oracle.cx(index, ancilla)\\n return oracle\\n\\ncircuit = QuantumCircuit(4, 3)\\n# [1] Prepare the query register and phase-sensitive ancilla.\\ncircuit.h([0, 1, 2])\\ncircuit.x(3)\\ncircuit.h(3)\\n# [2] Query the structured oracle.\\ncircuit.compose(bv_oracle(\"101\"), inplace=True)\\n# [3] Decode the hidden pattern.\\ncircuit.h([0, 1, 2])\\n# [4] Measure only the recovered string.\\ncircuit.measure([0, 1, 2], [0, 1, 2])\\n'\n",
"editable_circuit_lab(\n",
" initial_code=editable_code,\n",
" context={\"QuantumCircuit\": QuantumCircuit, \"simulate_counts\": simulate_counts},\n",
" title='Lab 1: Secret Variations',\n",
" instructions='Change the secret string and predict the oracle wiring and output bitstring before you run the cell.',\n",
" shots=256,\n",
")\n"
],
"id": "74cbc3f0"
},
{
"cell_type": "markdown",
"metadata": {
"ql_injected": "badge",
"ql_track": "mandatory",
"ql_role": "exercise"
},
"source": [
"\n",
"
\n",
"MANDATORY EXERCISE · Difficulty 2/10 · Official walkthrough runnable or written exercise.\n",
"
\n",
"MANDATORY TEST · Difficulty 2/10 · Official walkthrough multiple-choice test.\n",
"
\n"
],
"id": "63b41ca3"
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"jupyter": {
"source_hidden": true
},
"tags": [
"hide-input"
]
},
"outputs": [],
"source": [
"quiz_block([{'prompt': 'If the observed bitstring is reversed relative to the intended secret, what is the most likely cause?', 'options': ['A reporting-contract mismatch between qubit order and classical readout order', 'The oracle has too many Hadamards', 'The ancilla should have been measured'], 'correct_index': 0, 'explanation': 'This module trains you to treat bit order as interface design.'}, {'prompt': \"What is the best way to debug a BV circuit that 'almost works'?\", 'options': ['Inspect which query wires actually control the ancilla and then inspect the measurement mapping', 'Add more entangling gates until the counts change', 'Ignore the secret and only inspect circuit depth'], 'correct_index': 0, 'explanation': 'The hidden string lives in the oracle connectivity and the reporting contract.'}], heading='Lab Checkpoint A')\n"
],
"id": "d7ceff6e"
},
{
"cell_type": "markdown",
"metadata": {
"ql_injected": "badge",
"ql_track": "mandatory",
"ql_role": "exercise"
},
"source": [
"\n",
"
\n",
"MANDATORY EXERCISE · Difficulty 2/10 · Official walkthrough runnable or written exercise.\n",
"
\n"
],
"id": "cb0164f8"
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"jupyter": {
"source_hidden": true
},
"tags": [
"hide-input"
]
},
"outputs": [],
"source": [
"reflection_box('Which bit-order experiment in the lab was most clarifying, and what did it teach you about interface design?')\n"
],
"id": "b2583e2f"
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"
\n",
"\n",
"## Lab 2: Bit-Order Discipline\n",
"\n",
"\n",
" This lab isolates the most common reporting failure. Keep the oracle fixed and alter only how the query wires are mapped to classical bits. Then ask whether the result is still telling the truth in the form your notebook claims.\n"
],
"id": "2a0ca570"
},
{
"cell_type": "markdown",
"metadata": {
"ql_injected": "badge",
"ql_track": "mandatory",
"ql_role": "exercise"
},
"source": [
"\n",
"
\n",
"MANDATORY EXERCISE · Difficulty 2/10 · Official walkthrough runnable or written exercise.\n",
"
\n"
],
"id": "b8c10e42"
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"jupyter": {
"source_hidden": true
},
"tags": [
"hide-input"
]
},
"outputs": [],
"source": [
"editable_code = '\\nfrom qiskit import QuantumCircuit\\n\\ndef bv_oracle(secret: str = \"110\") -> QuantumCircuit:\\n oracle = QuantumCircuit(4, name=f\"bv_{secret}\")\\n ancilla = 3\\n for index, bit in enumerate(reversed(secret)):\\n if bit == \"1\":\\n oracle.cx(index, ancilla)\\n return oracle\\n\\ncircuit = QuantumCircuit(4, 3)\\ncircuit.h([0, 1, 2])\\ncircuit.x(3)\\ncircuit.h(3)\\ncircuit.compose(bv_oracle(\"110\"), inplace=True)\\ncircuit.h([0, 1, 2])\\n# Change the measurement order only if you can explain the reporting contract.\\ncircuit.measure([0, 1, 2], [0, 1, 2])\\n'\n",
"editable_circuit_lab(\n",
" initial_code=editable_code,\n",
" context={\"QuantumCircuit\": QuantumCircuit, \"simulate_counts\": simulate_counts},\n",
" title='Lab 2: Bit Order And Reporting',\n",
" instructions='Experiment with measurement order, but never change it casually. Write down exactly which string convention the notebook is reporting.',\n",
" shots=256,\n",
")\n"
],
"id": "e46199c5"
},
{
"cell_type": "markdown",
"metadata": {
"ql_injected": "badge",
"ql_track": "mandatory",
"ql_role": "exercise"
},
"source": [
"\n",
"
\n",
"MANDATORY EXERCISE · Difficulty 2/10 · Official walkthrough runnable or written exercise.\n",
"
\n",
"\n",
"## Lab 3: Candidate Comparison\n",
"\n",
"\n",
" Compare a plain builder with one that adds a little extra presentational structure. The important question is not which one is shorter. It is which one makes the secret-routing logic easiest to audit without obscuring the global algorithmic pattern.\n"
],
"id": "3cb5348d"
},
{
"cell_type": "markdown",
"metadata": {
"ql_injected": "badge",
"ql_track": "mandatory",
"ql_role": "exercise"
},
"source": [
"\n",
"
\n",
"MANDATORY EXERCISE · Difficulty 2/10 · Official walkthrough runnable or written exercise.\n",
"
\n",
"MANDATORY TEST · Difficulty 2/10 · Official walkthrough multiple-choice test.\n",
"
\n"
],
"id": "9b519db1"
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"jupyter": {
"source_hidden": true
},
"tags": [
"hide-input"
]
},
"outputs": [],
"source": [
"quiz_block([{'prompt': 'Why compare two BV candidates that produce the same output?', 'options': ['To judge readability, interface clarity, and how well the secret structure is exposed in the code', 'Because one of them must be mathematically invalid', 'Because Qiskit requires multiple implementations'], 'correct_index': 0, 'explanation': 'Engineering quality includes more than behavioral equivalence.'}, {'prompt': 'What would make a BV builder too clever?', 'options': ['Hiding secret-bit routing behind opaque indexing so the oracle contract is no longer reviewable', 'Using a helper function at all', 'Keeping the ancilla unmeasured'], 'correct_index': 0, 'explanation': 'Abstraction is useful only while the causal burden stays visible.'}], heading='Lab Checkpoint B')\n"
],
"id": "0026769f"
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"
\n",
"\n",
"## Lab Debrief\n",
"\n",
"\n",
" If the lab worked properly, the module should now feel less like a single algorithm and more like a family-level builder exercise. You should have seen that secret changes affect the oracle body, reporting-order changes affect the external contract, and helper-shape changes affect reviewability. Those are three different categories of edit. Learning to distinguish them is the real engineering gain.\n"
],
"id": "5ea33dc8"
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"
\n",
"\n",
"## Why The Lab Is Slower Than A Tutorial\n",
"\n",
"These exercises are intentionally slower than ordinary click-through tutorials because the purpose is different. A tutorial can reward motion. A professional lab has to reward discrimination. You are being asked to notice which edit changed the semantic burden of the circuit, which edit only changed presentation, and which edit damaged the reporting contract even though the diagram still looked familiar. That is harder work, but it is the right work for someone trying to become a designer rather than a consumer of notebooks.\n"
],
"id": "39744ce8"
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"
\n",
"\n",
"## Prediction Ledger\n",
"\n",
"If the lab begins to feel messy, return to the prediction ledger idea. Before each edit, write down what should remain invariant, what should move, and which evidence will decide the question. That tiny discipline is what keeps experiments from collapsing into aimless button pushing. It also mirrors how real engineering work scales. Good engineers do not only make changes. They keep track of what they expected the change to prove.\n"
],
"id": "6f2bab6b"
},
{
"cell_type": "markdown",
"metadata": {
"ql_injected": "badge",
"ql_track": "mandatory",
"ql_role": "exercise"
},
"source": [
"\n",
"
\n",
"MANDATORY EXERCISE · Difficulty 2/10 · Official walkthrough runnable or written exercise.\n",
"
\n",
"\n",
"\n",
"## What To Open Next\n",
"\n",
"Next notebook: [Bernstein-Vazirani and Structured Oracles Problems](problems.ipynb)\n",
"\n",
"Official walkthrough rule: once every mandatory cell above is complete, open the next notebook. Anything below this cell is facultative.\n"
],
"id": "27b0123c"
},
{
"cell_type": "markdown",
"metadata": {
"ql_injected": "facultative_zone",
"ql_track": "meta",
"ql_role": "reading",
"ql_difficulty": 1,
"ql_note": "Optional-zone boundary. The official walkthrough is already complete above."
},
"source": [
"\n",
"
\n",
"META READING · Difficulty 1/10 · Optional-zone boundary. The official walkthrough is already complete above.\n",
"
\n",
"\n",
"\n",
"## Facultative Extension Zone\n",
"\n",
"You have already completed the mandatory walkthrough for **Bernstein-Vazirani and Structured Oracles Lab**. Everything below is optional. Use it only if you want deeper consolidation or extra transfer work.\n"
],
"id": "9e5f6131"
},
{
"cell_type": "markdown",
"metadata": {
"ql_injected": "facultative",
"ql_track": "facultative",
"ql_role": "reading",
"ql_difficulty": 4,
"ql_note": "Optional extension reading."
},
"source": [
"\n",
"
\n",
"\n",
"## Facultative Extension Reading\n",
"\n",
"In **Bernstein-Vazirani and Structured Oracles Lab**, the mandatory labs already gave you the official practice loop. This optional cell is for deeper experimentation discipline: decide one variable you would perturb next, one quantity you would track, and one false conclusion you want to avoid.\n"
],
"id": "d939ff46"
},
{
"cell_type": "markdown",
"metadata": {
"ql_injected": "badge",
"ql_track": "facultative",
"ql_role": "test"
},
"source": [
"\n",
"
\n"
],
"id": "83c53a07"
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"ql_injected": "facultative",
"ql_track": "facultative",
"ql_role": "test",
"ql_difficulty": 5,
"ql_note": "Optional multiple-choice extension.",
"jupyter": {
"source_hidden": true
},
"tags": [
"hide-input"
]
},
"outputs": [],
"source": [
"quiz_block([{'prompt': 'In an optional lab variant, what should you change first?', 'options': ['One design variable you can explain', 'As many gates as possible to make the result surprising', 'The notebook order itself'], 'correct_index': 0, 'explanation': 'Optional exploration is still strongest when the perturbation is controlled.'}, {'prompt': 'What makes an optional lab note useful?', 'options': ['It records what changed, what stayed fixed, and what evidence moved', 'It only reports that the circuit still ran', 'It avoids writing predictions to save time'], 'correct_index': 0, 'explanation': 'The extension is about deeper evidence discipline.'}], heading='Facultative Extension Test')\n"
],
"id": "9a166d01"
},
{
"cell_type": "markdown",
"metadata": {
"ql_injected": "badge",
"ql_track": "facultative",
"ql_role": "exercise"
},
"source": [
"\n",
"