"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"
" 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"
" 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"
"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"
"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"
" 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"
"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",
" instructions='Experiment with measurement order, but never change it casually. Write down exactly which string convention the notebook is reporting.',\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"
"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"
" 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"
"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"
"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"
