From af0afaa60f8efa98002eaa03d16f1763e8a166c3 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Thu, 14 May 2026 11:40:13 -0500 Subject: [PATCH 01/28] Set up Box link --- scripts/config/api-html-artifacts.json | 1 + 1 file changed, 1 insertion(+) diff --git a/scripts/config/api-html-artifacts.json b/scripts/config/api-html-artifacts.json index b4ef47fc1e6..9dae83389d6 100644 --- a/scripts/config/api-html-artifacts.json +++ b/scripts/config/api-html-artifacts.json @@ -90,6 +90,7 @@ "0.3": "https://ibm.box.com/shared/static/qiskfdazhq1dpxcl9b627x9yi60gncb4.zip" }, "qiskit-addon-aqc-tensor": { + "0.3": "https://ibm.box.com/shared/static/uzw1mzmypuqf2one830vdrvy27x2brvu.zip", "0.2": "https://ibm.box.com/shared/static/dhuyxtri674xvb3oky5rg019bd1a44hf.zip", "0.1": "https://ibm.box.com/shared/static/jnxlji7b6cguhbvp1txdi2vhym38wcnc.zip" }, From 3e50f4ef0b65f92b5b106853c833e19b09dfe69b Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Mon, 18 May 2026 12:27:08 -0500 Subject: [PATCH 02/28] Document store directive --- docs/guides/qpu-information.ipynb | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/guides/qpu-information.ipynb b/docs/guides/qpu-information.ipynb index 635c9c439e6..f4d2e1b81b6 100644 --- a/docs/guides/qpu-information.ipynb +++ b/docs/guides/qpu-information.ipynb @@ -353,13 +353,14 @@ "\n", "### Table of supported instructions\n", "\n", - "| Operation category | Name |\n", + "| Operation category | Name | Notes |\n", "| :--- | :--- |\n", - "| Single-qubit gates | [`RZ`](/docs/api/qiskit/qiskit.circuit.library.RZGate), [`SX`](/docs/api/qiskit/qiskit.circuit.library.SXGate), [`X`](/docs/api/qiskit/qiskit.circuit.library.XGate), [`ID`](/docs/api/qiskit/qiskit.circuit.library.IGate), [`delay`](/docs/api/qiskit/circuit#qiskit.circuit.Delay) |\n", - "| Two-qubit gates | [`CZ`](/docs/api/qiskit/qiskit.circuit.library.CZGate), [`ECR`](/docs/api/qiskit/qiskit.circuit.library.ECRGate)|\n", - "| Fractional gates | [`RX`](/docs/api/qiskit/qiskit.circuit.library.RXGate) (single-qubit), [`RZZ`](/docs/api/qiskit/qiskit.circuit.library.RZZGate) (two-qubit) |\n", - "| Non-unitary instructions | [`measure`](/docs/api/qiskit/circuit#qiskit.circuit.Measure), [`reset`](/docs/api/qiskit/circuit#qiskit.circuit.Reset), [`measure_*`](/docs/guides/execute-dynamic-circuits#midcircuit), [`delay`](/docs/api/qiskit/circuit#delay) |\n", - "| Control flow | [`if_else`](/docs/api/qiskit/qiskit.circuit.IfElseOp) (classical feedforward) |" + "| Single-qubit gates | [`RZ`](/docs/api/qiskit/qiskit.circuit.library.RZGate), [`SX`](/docs/api/qiskit/qiskit.circuit.library.SXGate), [`X`](/docs/api/qiskit/qiskit.circuit.library.XGate), [`ID`](/docs/api/qiskit/qiskit.circuit.library.IGate), [`delay`](/docs/api/qiskit/circuit#qiskit.circuit.Delay) | |\n", + "| Two-qubit gates | [`CZ`](/docs/api/qiskit/qiskit.circuit.library.CZGate), [`ECR`](/docs/api/qiskit/qiskit.circuit.library.ECRGate)| |\n", + "| Fractional gates | [`RX`](/docs/api/qiskit/qiskit.circuit.library.RXGate) (single-qubit), [`RZZ`](/docs/api/qiskit/qiskit.circuit.library.RZZGate) (two-qubit) | |\n", + "| Non-unitary instructions | [`measure`](/docs/api/qiskit/circuit#qiskit.circuit.Measure), [`reset`](/docs/api/qiskit/circuit#qiskit.circuit.Reset), [`measure_*`](/docs/guides/execute-dynamic-circuits#midcircuit), [`delay`](/docs/api/qiskit/circuit#delay) | |\n", + "| Control flow | [`if_else`](/docs/api/qiskit/qiskit.circuit.IfElseOp) (classical feedforward) | |\n", + "| Classical bit operations | [`store`]([/docs/api/qiskit/circuit#store) | - Requires `ibm-qiskit-runtime` v0.47 or later
- Cannot be used when measurement twirling is enabled |" ] }, { From f2b1e2f36b42fe7fa3a119910cc99cfd6f5243cd Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Thu, 21 May 2026 12:29:39 -0500 Subject: [PATCH 03/28] Update examples n stuff --- ...assical-feedforward-and-control-flow.ipynb | 84 ++++++++++++------- docs/guides/executor-options.ipynb | 4 +- docs/guides/qpu-information.ipynb | 11 ++- docs/guides/sampler-options.ipynb | 4 +- 4 files changed, 67 insertions(+), 36 deletions(-) diff --git a/docs/guides/classical-feedforward-and-control-flow.ipynb b/docs/guides/classical-feedforward-and-control-flow.ipynb index 0d2eb4eeaf6..d39f1a7578f 100644 --- a/docs/guides/classical-feedforward-and-control-flow.ipynb +++ b/docs/guides/classical-feedforward-and-control-flow.ipynb @@ -2,7 +2,6 @@ "cells": [ { "cell_type": "markdown", - "id": "943cf52c-41c8-4a2b-bf1d-6df8a90a6353", "metadata": {}, "source": [ "---\n", @@ -16,7 +15,6 @@ }, { "cell_type": "markdown", - "id": "b1d96290-2e64-43aa-bae9-c74b8529894d", "metadata": { "tags": [ "version-info" @@ -45,7 +43,6 @@ }, { "cell_type": "markdown", - "id": "85a4d698-ee2a-4b3d-9331-1b91eea49338", "metadata": {}, "source": [ "Dynamic circuits are powerful tools with which you can measure qubits in the middle of a quantum circuit execution and then perform classical logic operations within the circuit, based on the outcome of those mid-circuit measurements. This process is also known as _classical feedforward_. While these are early days of understanding how best to take advantage of dynamic circuits, the quantum research community has already identified a number of use cases, such as the following:\n", @@ -57,7 +54,6 @@ }, { "cell_type": "markdown", - "id": "5d846edf-fc09-4808-bd62-3a8cfdcc1585", "metadata": {}, "source": [ "## `if` statement\n", @@ -70,7 +66,6 @@ { "cell_type": "code", "execution_count": 1, - "id": "60924bfa-50ed-4d9d-a17b-9d64f2cc053f", "metadata": {}, "outputs": [ { @@ -105,7 +100,6 @@ }, { "cell_type": "markdown", - "id": "bef3f447-7282-4de9-9410-6b671e9902c3", "metadata": {}, "source": [ "The `with` statement can be given an assignment target which is itself a context manager that can be stored and subsequently used to create an else block, which is executed whenever the contents of the `if` block are *not* executed.\n", @@ -116,7 +110,6 @@ { "cell_type": "code", "execution_count": 2, - "id": "20f0640a-a3f7-41b3-aada-b66bc89b0555", "metadata": {}, "outputs": [ { @@ -152,7 +145,6 @@ }, { "cell_type": "markdown", - "id": "f0f00f48-a1f2-40cc-b5f5-9a122d8dd24e", "metadata": {}, "source": [ "In addition to conditioning on a single classical bit, it's also possible to condition on the value of a classical register composed of multiple bits.\n", @@ -163,7 +155,6 @@ { "cell_type": "code", "execution_count": 3, - "id": "98e8f552-4169-42a3-8182-e14e9ffb59e2", "metadata": {}, "outputs": [ { @@ -198,7 +189,6 @@ }, { "cell_type": "markdown", - "id": "ef8fd422-6bab-46c9-9455-c79244cf1fb7", "metadata": {}, "source": [ "## Classical expressions\n", @@ -213,8 +203,7 @@ }, { "cell_type": "code", - "execution_count": 4, - "id": "7581ac2f-53e9-43d0-bad0-2c80790172e1", + "execution_count": 21, "metadata": {}, "outputs": [], "source": [ @@ -231,7 +220,6 @@ "qc = QuantumCircuit(qr, mr)\n", "\n", "# Create local Bell pairs\n", - "qc.reset(qr)\n", "qc.h(qr[::2])\n", "for ctrl in range(0, num_qubits, 2):\n", " qc.cx(qr[ctrl], qr[ctrl + 1])\n", @@ -240,7 +228,7 @@ "for ctrl in range(1, num_qubits - 1, 2):\n", " qc.cx(qr[ctrl], qr[ctrl + 1])\n", "\n", - "# Measure boundary qubits between pairs,reset to 0\n", + "# Measure boundary qubits between pairs, reset to 0\n", "for k, q in enumerate(meas_qubits):\n", " qc.measure(qr[q], mr[k])\n", " qc.reset(qr[q])\n", @@ -256,16 +244,18 @@ " if not left_bits: # skip if list empty\n", " continue\n", "\n", - " # build XOR-parity expression\n", - " parity = expr.lift(\n", - " mr[left_bits[0]]\n", - " ) # lift the first bit to Value so it will be treated like a boolean.\n", - " for k in left_bits[1:]:\n", - " parity = expr.bit_xor(\n", - " mr[k], parity\n", - " ) # calculate parity with all other bits\n", - " with qc.if_test(parity): # Add X if parity is 1\n", - " qc.x(qr[tgt])\n", + " # Now compute parity using the measurement register bits\n", + " if len(left_bits) == 1:\n", + " parity = expr.equal(mr[left_bits[0]], True)\n", + " else:\n", + " # Build XOR chain for all left_bits\n", + " parity = mr[left_bits[0]]\n", + " for bit_idx in left_bits[1:]:\n", + " parity = expr.bit_xor(parity, mr[bit_idx])\n", + "\n", + " with qc.if_test(parity):\n", + " qc.x(tgt) # Apply correction to target qubit based on parity\n", + "\n", "\n", "# Re-entangle measured qubits\n", "for ctrl in range(1, num_qubits - 1, 2):\n", @@ -275,7 +265,6 @@ { "cell_type": "code", "execution_count": 5, - "id": "d0f0abdb-50d5-408d-a704-a1a555acdd85", "metadata": {}, "outputs": [ { @@ -295,7 +284,45 @@ }, { "cell_type": "markdown", - "id": "7c80c5d0-a447-4590-8426-6eb33ae2d817", + "metadata": {}, + "source": [ + "With `qiskit-ibm-runtime` v0.47.0 or later, you can use the [`store`](/docs/api/qiskit/circuit#store) directive, which lets you break down complex classical bit operations into multi-step computations by creating temporary variables. Operations are automatically parallelized, making your code significantly more efficient at runtime.\n", + "\n", + "Example:" + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit.circuit import QuantumCircuit, ClassicalRegister\n", + "from qiskit.circuit.classical import expr\n", + "\n", + "qc = QuantumCircuit(4, 4)\n", + "creg = ClassicalRegister(4, \"creg\")\n", + "temp = ClassicalRegister(4, \"temp\")\n", + "qc.add_register(creg, temp)\n", + "\n", + "# Measure qubits\n", + "qc.measure_all()\n", + "\n", + "# Store the negation in temporary variable (parallelized)\n", + "qc.store(temp, expr.bit_not(creg))\n", + "\n", + "# Now compute parity using the stored result\n", + "parity = expr.bit_xor(\n", + " expr.bit_xor(expr.bit_xor(temp[0], temp[1]), temp[2]),\n", + " temp[3]\n", + ")\n", + "\n", + "with qc.if_test(parity):\n", + " qc.x(0) # Apply correction based on parity\n" + ] + }, + { + "cell_type": "markdown", "metadata": {}, "source": [ "## Next steps\n", @@ -304,13 +331,14 @@ "- Learn how to implement accurate dynamic decoupling by using [stretch](/docs/guides/stretch).\n", "- Use [circuit schedule visualization](/docs/guides/qiskit-runtime-circuit-timing) to debug and optimize your dynamic circuits.\n", "- [Execute dynamic circuits](/docs/guides/execute-dynamic-circuits).\n", + "- Not all functions are compatible with dynamic circuits. Check the feature compatibility section for [Sampler](/docs/guides/sampler-options#feature-compatibility) or [Executor](/docs/guides/executor-options#feature-compatibility) for details. \n", "" ] } ], "metadata": { "kernelspec": { - "display_name": "Python 3", + "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, @@ -324,7 +352,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3" + "version": "3.12.3" } }, "nbformat": 4, diff --git a/docs/guides/executor-options.ipynb b/docs/guides/executor-options.ipynb index e3f6f293612..764f32b3602 100644 --- a/docs/guides/executor-options.ipynb +++ b/docs/guides/executor-options.ipynb @@ -240,7 +240,9 @@ " - Dynamical decoupling\n", "\n", " Other notes:\n", - " - Gate twirling can be applied to dynamic circuits, but only to gates not inside conditional blocks. Measurement twirling can only be applied to terminal measurements.\n", + " - Gate twirling can be applied to dynamic circuits, but only to gates not inside conditional blocks. \n", + " - Measurement twirling can only be applied to terminal measurements.\n", + " - Measurement twirling is incompatible with the [`store`](/docs/api/qiskit/circuit#store) directive.\n", " - Compatible with fractional gates when using `qiskit-ibm-runtime` v0.42.0 or later.\n", "\n", " \n", diff --git a/docs/guides/qpu-information.ipynb b/docs/guides/qpu-information.ipynb index f4d2e1b81b6..56ddac0b19f 100644 --- a/docs/guides/qpu-information.ipynb +++ b/docs/guides/qpu-information.ipynb @@ -353,14 +353,13 @@ "\n", "### Table of supported instructions\n", "\n", - "| Operation category | Name | Notes |\n", + "| Operation category | Name |\n", "| :--- | :--- |\n", - "| Single-qubit gates | [`RZ`](/docs/api/qiskit/qiskit.circuit.library.RZGate), [`SX`](/docs/api/qiskit/qiskit.circuit.library.SXGate), [`X`](/docs/api/qiskit/qiskit.circuit.library.XGate), [`ID`](/docs/api/qiskit/qiskit.circuit.library.IGate), [`delay`](/docs/api/qiskit/circuit#qiskit.circuit.Delay) | |\n", - "| Two-qubit gates | [`CZ`](/docs/api/qiskit/qiskit.circuit.library.CZGate), [`ECR`](/docs/api/qiskit/qiskit.circuit.library.ECRGate)| |\n", + "| Single-qubit gates | [`RZ`](/docs/api/qiskit/qiskit.circuit.library.RZGate), [`SX`](/docs/api/qiskit/qiskit.circuit.library.SXGate), [`X`](/docs/api/qiskit/qiskit.circuit.library.XGate), [`ID`](/docs/api/qiskit/qiskit.circuit.library.IGate), [`delay`](/docs/api/qiskit/circuit#qiskit.circuit.Delay) |\n", + "| Two-qubit gates | [`CZ`](/docs/api/qiskit/qiskit.circuit.library.CZGate), [`ECR`](/docs/api/qiskit/qiskit.circuit.library.ECRGate)|\n", "| Fractional gates | [`RX`](/docs/api/qiskit/qiskit.circuit.library.RXGate) (single-qubit), [`RZZ`](/docs/api/qiskit/qiskit.circuit.library.RZZGate) (two-qubit) | |\n", - "| Non-unitary instructions | [`measure`](/docs/api/qiskit/circuit#qiskit.circuit.Measure), [`reset`](/docs/api/qiskit/circuit#qiskit.circuit.Reset), [`measure_*`](/docs/guides/execute-dynamic-circuits#midcircuit), [`delay`](/docs/api/qiskit/circuit#delay) | |\n", - "| Control flow | [`if_else`](/docs/api/qiskit/qiskit.circuit.IfElseOp) (classical feedforward) | |\n", - "| Classical bit operations | [`store`]([/docs/api/qiskit/circuit#store) | - Requires `ibm-qiskit-runtime` v0.47 or later
- Cannot be used when measurement twirling is enabled |" + "| Non-unitary instructions | [`measure`](/docs/api/qiskit/circuit#qiskit.circuit.Measure), [`reset`](/docs/api/qiskit/circuit#qiskit.circuit.Reset), [`measure_*`](/docs/guides/execute-dynamic-circuits#midcircuit), [`delay`](/docs/api/qiskit/circuit#delay) |\n", + "| Control flow | [`if_else`](/docs/api/qiskit/qiskit.circuit.IfElseOp) (classical feedforward) |\n" ] }, { diff --git a/docs/guides/sampler-options.ipynb b/docs/guides/sampler-options.ipynb index 2ad61fb038d..362035547fe 100644 --- a/docs/guides/sampler-options.ipynb +++ b/docs/guides/sampler-options.ipynb @@ -510,7 +510,9 @@ " - Stretches\n", "\n", " Other notes:\n", - " - Gate twirling can be applied to dynamic circuits, but only to gates not inside conditional blocks. Measurement twirling can only be applied to terminal measurements.\n", + " - Gate twirling can be applied to dynamic circuits, but only to gates not inside conditional blocks. \n", + " - Measurement twirling can only be applied to terminal measurements.\n", + " - Measurement twirling is incompatible with the [`store`](/docs/api/qiskit/circuit#store) directive.\n", " - Does not work with non-Clifford entanglers.\n", " \n", "" From cc5a4da6d76c101eb67f52359cd783dcc5ce5917 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Thu, 21 May 2026 13:35:05 -0500 Subject: [PATCH 04/28] tox e fix --- ...assical-feedforward-and-control-flow.ipynb | 26 ++++++++++++++----- docs/guides/executor-options.ipynb | 2 +- docs/guides/qpu-information.ipynb | 2 +- docs/guides/sampler-options.ipynb | 2 +- 4 files changed, 23 insertions(+), 9 deletions(-) diff --git a/docs/guides/classical-feedforward-and-control-flow.ipynb b/docs/guides/classical-feedforward-and-control-flow.ipynb index d39f1a7578f..190f45cfc39 100644 --- a/docs/guides/classical-feedforward-and-control-flow.ipynb +++ b/docs/guides/classical-feedforward-and-control-flow.ipynb @@ -2,6 +2,7 @@ "cells": [ { "cell_type": "markdown", + "id": "22c0d141-0422-41e7-8d2c-ec3b8e67f802", "metadata": {}, "source": [ "---\n", @@ -15,6 +16,7 @@ }, { "cell_type": "markdown", + "id": "8dddd409-e6f5-4921-adca-fa5de2f36409", "metadata": { "tags": [ "version-info" @@ -43,6 +45,7 @@ }, { "cell_type": "markdown", + "id": "65fd8fc3-6084-4e1b-bd90-aa29c65e003b", "metadata": {}, "source": [ "Dynamic circuits are powerful tools with which you can measure qubits in the middle of a quantum circuit execution and then perform classical logic operations within the circuit, based on the outcome of those mid-circuit measurements. This process is also known as _classical feedforward_. While these are early days of understanding how best to take advantage of dynamic circuits, the quantum research community has already identified a number of use cases, such as the following:\n", @@ -54,6 +57,7 @@ }, { "cell_type": "markdown", + "id": "f59189a9-8261-47d6-b0eb-06f9620f6e73", "metadata": {}, "source": [ "## `if` statement\n", @@ -66,6 +70,7 @@ { "cell_type": "code", "execution_count": 1, + "id": "2a817111-ef61-42d3-b66a-4ef7406c639f", "metadata": {}, "outputs": [ { @@ -100,6 +105,7 @@ }, { "cell_type": "markdown", + "id": "cb629347-3f61-43f3-923f-d70c3741f57d", "metadata": {}, "source": [ "The `with` statement can be given an assignment target which is itself a context manager that can be stored and subsequently used to create an else block, which is executed whenever the contents of the `if` block are *not* executed.\n", @@ -110,6 +116,7 @@ { "cell_type": "code", "execution_count": 2, + "id": "8fc3afa5-57aa-4f68-a3aa-b8d1bb82bbaf", "metadata": {}, "outputs": [ { @@ -145,6 +152,7 @@ }, { "cell_type": "markdown", + "id": "f89aedf5-e7ee-417e-9fa5-f5e44f7adf8a", "metadata": {}, "source": [ "In addition to conditioning on a single classical bit, it's also possible to condition on the value of a classical register composed of multiple bits.\n", @@ -155,6 +163,7 @@ { "cell_type": "code", "execution_count": 3, + "id": "9de117bc-4878-4bc7-b1a4-57c0e22ad1bc", "metadata": {}, "outputs": [ { @@ -189,6 +198,7 @@ }, { "cell_type": "markdown", + "id": "88010016-7f61-4570-921f-9e670561ba18", "metadata": {}, "source": [ "## Classical expressions\n", @@ -204,6 +214,7 @@ { "cell_type": "code", "execution_count": 21, + "id": "e9f06aae-1f62-482c-b96e-9c51b0fb46ac", "metadata": {}, "outputs": [], "source": [ @@ -265,6 +276,7 @@ { "cell_type": "code", "execution_count": 5, + "id": "a0f2ba55-2e73-43f2-a753-344c588b5f0e", "metadata": {}, "outputs": [ { @@ -284,6 +296,7 @@ }, { "cell_type": "markdown", + "id": "61b1d251-7fd8-4b99-a4b3-b8f37ae44491", "metadata": {}, "source": [ "With `qiskit-ibm-runtime` v0.47.0 or later, you can use the [`store`](/docs/api/qiskit/circuit#store) directive, which lets you break down complex classical bit operations into multi-step computations by creating temporary variables. Operations are automatically parallelized, making your code significantly more efficient at runtime.\n", @@ -294,6 +307,7 @@ { "cell_type": "code", "execution_count": 22, + "id": "20293ae6-0b3a-4024-ba58-22485bb39912", "metadata": {}, "outputs": [], "source": [ @@ -313,16 +327,16 @@ "\n", "# Now compute parity using the stored result\n", "parity = expr.bit_xor(\n", - " expr.bit_xor(expr.bit_xor(temp[0], temp[1]), temp[2]),\n", - " temp[3]\n", + " expr.bit_xor(expr.bit_xor(temp[0], temp[1]), temp[2]), temp[3]\n", ")\n", "\n", "with qc.if_test(parity):\n", - " qc.x(0) # Apply correction based on parity\n" + " qc.x(0) # Apply correction based on parity" ] }, { "cell_type": "markdown", + "id": "9ccfe008-333d-44f8-9be0-1e61d045a69d", "metadata": {}, "source": [ "## Next steps\n", @@ -331,14 +345,14 @@ "- Learn how to implement accurate dynamic decoupling by using [stretch](/docs/guides/stretch).\n", "- Use [circuit schedule visualization](/docs/guides/qiskit-runtime-circuit-timing) to debug and optimize your dynamic circuits.\n", "- [Execute dynamic circuits](/docs/guides/execute-dynamic-circuits).\n", - "- Not all functions are compatible with dynamic circuits. Check the feature compatibility section for [Sampler](/docs/guides/sampler-options#feature-compatibility) or [Executor](/docs/guides/executor-options#feature-compatibility) for details. \n", + "- Not all functions are compatible with dynamic circuits. Check the feature compatibility section for [Sampler](/docs/guides/sampler-options#feature-compatibility) or [Executor](/docs/guides/executor-options#feature-compatibility) for details.\n", "" ] } ], "metadata": { "kernelspec": { - "display_name": "Python 3 (ipykernel)", + "display_name": "Python 3", "language": "python", "name": "python3" }, @@ -352,7 +366,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.12.3" + "version": "3" } }, "nbformat": 4, diff --git a/docs/guides/executor-options.ipynb b/docs/guides/executor-options.ipynb index 764f32b3602..5187e783dd1 100644 --- a/docs/guides/executor-options.ipynb +++ b/docs/guides/executor-options.ipynb @@ -240,7 +240,7 @@ " - Dynamical decoupling\n", "\n", " Other notes:\n", - " - Gate twirling can be applied to dynamic circuits, but only to gates not inside conditional blocks. \n", + " - Gate twirling can be applied to dynamic circuits, but only to gates not inside conditional blocks.\n", " - Measurement twirling can only be applied to terminal measurements.\n", " - Measurement twirling is incompatible with the [`store`](/docs/api/qiskit/circuit#store) directive.\n", " - Compatible with fractional gates when using `qiskit-ibm-runtime` v0.42.0 or later.\n", diff --git a/docs/guides/qpu-information.ipynb b/docs/guides/qpu-information.ipynb index 56ddac0b19f..bbcdc173929 100644 --- a/docs/guides/qpu-information.ipynb +++ b/docs/guides/qpu-information.ipynb @@ -359,7 +359,7 @@ "| Two-qubit gates | [`CZ`](/docs/api/qiskit/qiskit.circuit.library.CZGate), [`ECR`](/docs/api/qiskit/qiskit.circuit.library.ECRGate)|\n", "| Fractional gates | [`RX`](/docs/api/qiskit/qiskit.circuit.library.RXGate) (single-qubit), [`RZZ`](/docs/api/qiskit/qiskit.circuit.library.RZZGate) (two-qubit) | |\n", "| Non-unitary instructions | [`measure`](/docs/api/qiskit/circuit#qiskit.circuit.Measure), [`reset`](/docs/api/qiskit/circuit#qiskit.circuit.Reset), [`measure_*`](/docs/guides/execute-dynamic-circuits#midcircuit), [`delay`](/docs/api/qiskit/circuit#delay) |\n", - "| Control flow | [`if_else`](/docs/api/qiskit/qiskit.circuit.IfElseOp) (classical feedforward) |\n" + "| Control flow | [`if_else`](/docs/api/qiskit/qiskit.circuit.IfElseOp) (classical feedforward) |" ] }, { diff --git a/docs/guides/sampler-options.ipynb b/docs/guides/sampler-options.ipynb index 362035547fe..da7e0ac3bb8 100644 --- a/docs/guides/sampler-options.ipynb +++ b/docs/guides/sampler-options.ipynb @@ -510,7 +510,7 @@ " - Stretches\n", "\n", " Other notes:\n", - " - Gate twirling can be applied to dynamic circuits, but only to gates not inside conditional blocks. \n", + " - Gate twirling can be applied to dynamic circuits, but only to gates not inside conditional blocks.\n", " - Measurement twirling can only be applied to terminal measurements.\n", " - Measurement twirling is incompatible with the [`store`](/docs/api/qiskit/circuit#store) directive.\n", " - Does not work with non-Clifford entanglers.\n", From 0c63aec85343e8fe94719296086b17f5e273a03c Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Thu, 21 May 2026 15:31:52 -0500 Subject: [PATCH 05/28] correct code --- ...assical-feedforward-and-control-flow.ipynb | 91 +++++-------------- 1 file changed, 22 insertions(+), 69 deletions(-) diff --git a/docs/guides/classical-feedforward-and-control-flow.ipynb b/docs/guides/classical-feedforward-and-control-flow.ipynb index 190f45cfc39..e791cf229fc 100644 --- a/docs/guides/classical-feedforward-and-control-flow.ipynb +++ b/docs/guides/classical-feedforward-and-control-flow.ipynb @@ -2,7 +2,6 @@ "cells": [ { "cell_type": "markdown", - "id": "22c0d141-0422-41e7-8d2c-ec3b8e67f802", "metadata": {}, "source": [ "---\n", @@ -16,7 +15,6 @@ }, { "cell_type": "markdown", - "id": "8dddd409-e6f5-4921-adca-fa5de2f36409", "metadata": { "tags": [ "version-info" @@ -45,7 +43,6 @@ }, { "cell_type": "markdown", - "id": "65fd8fc3-6084-4e1b-bd90-aa29c65e003b", "metadata": {}, "source": [ "Dynamic circuits are powerful tools with which you can measure qubits in the middle of a quantum circuit execution and then perform classical logic operations within the circuit, based on the outcome of those mid-circuit measurements. This process is also known as _classical feedforward_. While these are early days of understanding how best to take advantage of dynamic circuits, the quantum research community has already identified a number of use cases, such as the following:\n", @@ -57,7 +54,6 @@ }, { "cell_type": "markdown", - "id": "f59189a9-8261-47d6-b0eb-06f9620f6e73", "metadata": {}, "source": [ "## `if` statement\n", @@ -70,7 +66,6 @@ { "cell_type": "code", "execution_count": 1, - "id": "2a817111-ef61-42d3-b66a-4ef7406c639f", "metadata": {}, "outputs": [ { @@ -105,7 +100,6 @@ }, { "cell_type": "markdown", - "id": "cb629347-3f61-43f3-923f-d70c3741f57d", "metadata": {}, "source": [ "The `with` statement can be given an assignment target which is itself a context manager that can be stored and subsequently used to create an else block, which is executed whenever the contents of the `if` block are *not* executed.\n", @@ -116,7 +110,6 @@ { "cell_type": "code", "execution_count": 2, - "id": "8fc3afa5-57aa-4f68-a3aa-b8d1bb82bbaf", "metadata": {}, "outputs": [ { @@ -152,7 +145,6 @@ }, { "cell_type": "markdown", - "id": "f89aedf5-e7ee-417e-9fa5-f5e44f7adf8a", "metadata": {}, "source": [ "In addition to conditioning on a single classical bit, it's also possible to condition on the value of a classical register composed of multiple bits.\n", @@ -163,7 +155,6 @@ { "cell_type": "code", "execution_count": 3, - "id": "9de117bc-4878-4bc7-b1a4-57c0e22ad1bc", "metadata": {}, "outputs": [ { @@ -198,7 +189,6 @@ }, { "cell_type": "markdown", - "id": "88010016-7f61-4570-921f-9e670561ba18", "metadata": {}, "source": [ "## Classical expressions\n", @@ -208,13 +198,14 @@ "The following example shows that you can use the calculation of the parity to create an n-qubit GHZ state using dynamic circuits. First, generate $n/2$ Bell pairs on adjacent qubits. Then, glue these pairs together using a layer of CNOT gates in between pairs. You then measure the target qubit of all prior CNOT gates and reset each measured qubit to the state $\\vert 0 \\rangle$. You apply $X$ to every unmeasured site for which the parity of all preceding bits is odd. Finally, CNOT gates are applied to the measured qubits to re-establish the entanglement lost in the measurement.\n", "\n", "\n", - "In the parity calculation, the first element of the constructed expression involves lifting the Python object `mr[0]` to a [`Value`](/docs/api/qiskit/circuit_classical#value) node (`lift` is used to turn arbitrary objects into classical expressions). This is not necessary for `mr[1]` and the possible following classical register, as they are inputs to `expr.bit_xor`, and any necessary lifting is done automatically in these cases. Such expressions can be built up in loops and other constructs." + "In the parity calculation, the first element of the constructed expression involves lifting the Python object `mr[0]` to a [`Value`](/docs/api/qiskit/circuit_classical#value) node (`lift` is used to turn arbitrary objects into classical expressions). This is not necessary for `mr[1]` and the possible following classical register, as they are inputs to `expr.bit_xor`, and any necessary lifting is done automatically in these cases. Such expressions can be built up in loops and other constructs.\n", + "\n", + "With `qiskit-ibm-runtime` v0.47.0 or later, you can use the [`store`](/docs/api/qiskit/circuit#store) directive, which lets you break down complex classical bit operations into multi-step computations by creating temporary variables. Operations are automatically parallelized, making your code significantly more efficient at runtime." ] }, { "cell_type": "code", "execution_count": 21, - "id": "e9f06aae-1f62-482c-b96e-9c51b0fb46ac", "metadata": {}, "outputs": [], "source": [ @@ -228,7 +219,8 @@ "\n", "qr = QuantumRegister(num_qubits, \"qr\")\n", "mr = ClassicalRegister(len(meas_qubits), \"m\")\n", - "qc = QuantumCircuit(qr, mr)\n", + "temp = ClassicalRegister(len(meas_qubits), \"temp\")\n", + "qc = QuantumCircuit(qr, mr, temp) # Fixed: Added temp register to circuit\n", "\n", "# Create local Bell pairs\n", "qc.h(qr[::2])\n", @@ -244,28 +236,31 @@ " qc.measure(qr[q], mr[k])\n", " qc.reset(qr[q])\n", "\n", + "# Store the negation in temporary variable (parallelized)\n", + "qc.store(temp, expr.bit_not(mr))\n", + "\n", + "\n", + "\n", "# Parity-conditioned X corrections\n", "# Each non-measured qubit gets flipped iff the parity (XOR) of all\n", "# preceding measurement bits is 1\n", + "\n", "for tgt in range(num_qubits):\n", " if tgt in meas_qubits: # skip measured qubits\n", " continue\n", - " # all measurement registers whose physical qubit index < tgt\n", + "# all measurement registers whose physical qubit index < tgt\n", " left_bits = [k for k, q in enumerate(meas_qubits) if q < tgt]\n", " if not left_bits: # skip if list empty\n", " continue\n", "\n", - " # Now compute parity using the measurement register bits\n", - " if len(left_bits) == 1:\n", - " parity = expr.equal(mr[left_bits[0]], True)\n", - " else:\n", - " # Build XOR chain for all left_bits\n", - " parity = mr[left_bits[0]]\n", - " for bit_idx in left_bits[1:]:\n", - " parity = expr.bit_xor(parity, mr[bit_idx])\n", + "# Compute parity using the stored result for all bits in temp (which has len(meas_qubits) = 3 bits)\n", "\n", - " with qc.if_test(parity):\n", - " qc.x(tgt) # Apply correction to target qubit based on parity\n", + "parity = temp[0]\n", + "for i in range(1, len(meas_qubits)):\n", + " parity = expr.bit_xor(parity, temp[i])\n", + "\n", + "with qc.if_test(parity):\n", + " qc.x(qr[tgt]) ## Apply correction to target qubit based on parity\n", "\n", "\n", "# Re-entangle measured qubits\n", @@ -276,7 +271,6 @@ { "cell_type": "code", "execution_count": 5, - "id": "a0f2ba55-2e73-43f2-a753-344c588b5f0e", "metadata": {}, "outputs": [ { @@ -296,47 +290,6 @@ }, { "cell_type": "markdown", - "id": "61b1d251-7fd8-4b99-a4b3-b8f37ae44491", - "metadata": {}, - "source": [ - "With `qiskit-ibm-runtime` v0.47.0 or later, you can use the [`store`](/docs/api/qiskit/circuit#store) directive, which lets you break down complex classical bit operations into multi-step computations by creating temporary variables. Operations are automatically parallelized, making your code significantly more efficient at runtime.\n", - "\n", - "Example:" - ] - }, - { - "cell_type": "code", - "execution_count": 22, - "id": "20293ae6-0b3a-4024-ba58-22485bb39912", - "metadata": {}, - "outputs": [], - "source": [ - "from qiskit.circuit import QuantumCircuit, ClassicalRegister\n", - "from qiskit.circuit.classical import expr\n", - "\n", - "qc = QuantumCircuit(4, 4)\n", - "creg = ClassicalRegister(4, \"creg\")\n", - "temp = ClassicalRegister(4, \"temp\")\n", - "qc.add_register(creg, temp)\n", - "\n", - "# Measure qubits\n", - "qc.measure_all()\n", - "\n", - "# Store the negation in temporary variable (parallelized)\n", - "qc.store(temp, expr.bit_not(creg))\n", - "\n", - "# Now compute parity using the stored result\n", - "parity = expr.bit_xor(\n", - " expr.bit_xor(expr.bit_xor(temp[0], temp[1]), temp[2]), temp[3]\n", - ")\n", - "\n", - "with qc.if_test(parity):\n", - " qc.x(0) # Apply correction based on parity" - ] - }, - { - "cell_type": "markdown", - "id": "9ccfe008-333d-44f8-9be0-1e61d045a69d", "metadata": {}, "source": [ "## Next steps\n", @@ -345,14 +298,14 @@ "- Learn how to implement accurate dynamic decoupling by using [stretch](/docs/guides/stretch).\n", "- Use [circuit schedule visualization](/docs/guides/qiskit-runtime-circuit-timing) to debug and optimize your dynamic circuits.\n", "- [Execute dynamic circuits](/docs/guides/execute-dynamic-circuits).\n", - "- Not all functions are compatible with dynamic circuits. Check the feature compatibility section for [Sampler](/docs/guides/sampler-options#feature-compatibility) or [Executor](/docs/guides/executor-options#feature-compatibility) for details.\n", + "- Not all functions are compatible with dynamic circuits. Check the feature compatibility section for [Sampler](/docs/guides/sampler-options#feature-compatibility) or [Executor](/docs/guides/executor-options#feature-compatibility) for details. \n", "" ] } ], "metadata": { "kernelspec": { - "display_name": "Python 3", + "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, @@ -366,7 +319,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3" + "version": "3.12.3" } }, "nbformat": 4, From cfb73d689d42e71d18d9e6fcf1520fb722768951 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Fri, 22 May 2026 11:36:38 -0500 Subject: [PATCH 06/28] Get real code and outputs --- ...assical-feedforward-and-control-flow.ipynb | 43 +++++++++---------- 1 file changed, 20 insertions(+), 23 deletions(-) diff --git a/docs/guides/classical-feedforward-and-control-flow.ipynb b/docs/guides/classical-feedforward-and-control-flow.ipynb index e791cf229fc..bb5139d1db0 100644 --- a/docs/guides/classical-feedforward-and-control-flow.ipynb +++ b/docs/guides/classical-feedforward-and-control-flow.ipynb @@ -195,7 +195,7 @@ "\n", "The Qiskit classical expression module [`qiskit.circuit.classical`](/docs/api/qiskit/circuit_classical) contains an exploratory representation of runtime operations on classical values during circuit execution. Due to hardware limitations, only `QuantumCircuit.if_test()` conditions are currently supported.\n", "\n", - "The following example shows that you can use the calculation of the parity to create an n-qubit GHZ state using dynamic circuits. First, generate $n/2$ Bell pairs on adjacent qubits. Then, glue these pairs together using a layer of CNOT gates in between pairs. You then measure the target qubit of all prior CNOT gates and reset each measured qubit to the state $\\vert 0 \\rangle$. You apply $X$ to every unmeasured site for which the parity of all preceding bits is odd. Finally, CNOT gates are applied to the measured qubits to re-establish the entanglement lost in the measurement.\n", + "The following example shows that you can use the calculation of the parity to create an n-qubit GHZ-like state using dynamic circuits. First, generate $n/2$ Bell pairs on adjacent qubits. Then, glue these pairs together using a layer of CNOT gates in between pairs. You then measure the target qubit of all prior CNOT gates and reset each measured qubit to the state $\\vert 0 \\rangle$. You apply $X$ to every unmeasured site for which the parity of all preceding bits is odd. Finally, CNOT gates are applied to the measured qubits to re-establish the entanglement lost in the measurement.\n", "\n", "\n", "In the parity calculation, the first element of the constructed expression involves lifting the Python object `mr[0]` to a [`Value`](/docs/api/qiskit/circuit_classical#value) node (`lift` is used to turn arbitrary objects into classical expressions). This is not necessary for `mr[1]` and the possible following classical register, as they are inputs to `expr.bit_xor`, and any necessary lifting is done automatically in these cases. Such expressions can be built up in loops and other constructs.\n", @@ -205,7 +205,7 @@ }, { "cell_type": "code", - "execution_count": 21, + "execution_count": 1, "metadata": {}, "outputs": [], "source": [ @@ -220,9 +220,10 @@ "qr = QuantumRegister(num_qubits, \"qr\")\n", "mr = ClassicalRegister(len(meas_qubits), \"m\")\n", "temp = ClassicalRegister(len(meas_qubits), \"temp\")\n", - "qc = QuantumCircuit(qr, mr, temp) # Fixed: Added temp register to circuit\n", + "qc = QuantumCircuit(qr, mr, temp)\n", "\n", "# Create local Bell pairs\n", + "qc.reset(qr)\n", "qc.h(qr[::2])\n", "for ctrl in range(0, num_qubits, 2):\n", " qc.cx(qr[ctrl], qr[ctrl + 1])\n", @@ -231,37 +232,32 @@ "for ctrl in range(1, num_qubits - 1, 2):\n", " qc.cx(qr[ctrl], qr[ctrl + 1])\n", "\n", - "# Measure boundary qubits between pairs, reset to 0\n", + "# Measure boundary qubits between pairs,reset to 0\n", "for k, q in enumerate(meas_qubits):\n", " qc.measure(qr[q], mr[k])\n", " qc.reset(qr[q])\n", "\n", - "# Store the negation in temporary variable (parallelized)\n", - "qc.store(temp, expr.bit_not(mr))\n", - "\n", - "\n", - "\n", "# Parity-conditioned X corrections\n", "# Each non-measured qubit gets flipped iff the parity (XOR) of all\n", "# preceding measurement bits is 1\n", - "\n", "for tgt in range(num_qubits):\n", " if tgt in meas_qubits: # skip measured qubits\n", " continue\n", - "# all measurement registers whose physical qubit index < tgt\n", + " # all measurement registers whose physical qubit index < tgt\n", " left_bits = [k for k, q in enumerate(meas_qubits) if q < tgt]\n", " if not left_bits: # skip if list empty\n", " continue\n", "\n", - "# Compute parity using the stored result for all bits in temp (which has len(meas_qubits) = 3 bits)\n", - "\n", - "parity = temp[0]\n", - "for i in range(1, len(meas_qubits)):\n", - " parity = expr.bit_xor(parity, temp[i])\n", - "\n", - "with qc.if_test(parity):\n", - " qc.x(qr[tgt]) ## Apply correction to target qubit based on parity\n", - "\n", + " # build XOR-parity expression\n", + " parity = expr.lift(\n", + " temp[left_bits[0]]\n", + " ) # lift the first bit to Value so it will be treated like a boolean.\n", + " for k in left_bits[1:]:\n", + " parity = expr.bit_xor(\n", + " temp[k], parity\n", + " ) # calculate parity with all other bits\n", + " with qc.if_test(parity): # Add X if parity is 1\n", + " qc.x(qr[tgt])\n", "\n", "# Re-entangle measured qubits\n", "for ctrl in range(1, num_qubits - 1, 2):\n", @@ -270,16 +266,17 @@ }, { "cell_type": "code", - "execution_count": 5, + "execution_count": 2, "metadata": {}, "outputs": [ { "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAABRUAAAKxCAYAAADNUksFAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjksIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvJkbTWQAAAAlwSFlzAAAPYQAAD2EBqD+naQAA0sBJREFUeJzs3Xd4lfX9//HXfU72YIQEIgQIKxAQCCYgUwEBRUYVBEFEoLi12hahtg60rVJEa2utq07oV4oVBwqoSACRIQlbCEQiRLKAkATIIOuc3x/8SDkmgdzJGUl4Pq6LS8+9Pu8TTu7DeZ3PMOx2u10AAAAAAAAAUEMWTxcAAAAAAAAAoGEhVAQAAAAAAABgCqEiAAAAAAAAAFMIFQEAAAAAAACYQqgIAAAAAAAAwBRCRQAAAAAAAACmECoCAAAAAAAAMIVQEQAAAAAAAIAphIoAAAAAAAAATCFUBAAAAAAAAGAKoSIAAAAAAAAAUwgVAQAAAAAAAJhCqAgAAAAAAADAFEJFAAAAAAAAAKYQKgIAAAAAAAAwhVARAAAAAAAAgCmEigAAAAAAAABMIVQEAAAAAAAAYAqhIgAAAAAAAABTCBUBAAAAAAAAmEKoCAAAAAAAAMAUQkUAAAAAAAAAphAqAgAAAAAAADCFUBEAAAAAAACAKYSKAAAAAAAAAEwhVAQAAAAAAABgCqEiAAAAAAAAAFMIFQEAAAAAAACYQqgIAAAAAAAAwBRCRQAAAAAAAACmECoCAAAAAAAAMIVQEQAAAAAAAIAphIoAAAAAAAAATCFUBAAAAAAAAGAKoSIAAAAAAAAAUwgVAQAAAAAAAJhCqAgAAAAAAADAFC9PF4D6xW63q7y83NNl1JjVapVhGE67nt1ul4qLnXY9t/D1derPAAAAAAAA4FIIFeGgvLxcy5cv93QZNTZx4kR5eTnxZVxcrLLJM5x3PTfw+uA9yc/P02UAAAAAAIDLCMOfAQAAAAAAAJhCqAgAAAAAAADAFEJFAAAAAAAAAKYQKgIAAAAAAAAwhVARAAAAAAAAgCmEigAAAAAAAABMIVQEAAAAAAAAYAqhIgAAAAAAAABTCBUBAAAAAAAAmEKoCAAAAAAAAMAUQkUAAAAAAAAAphAqAgAAAAAAADCFUBEAAAAAAACAKYSKtZCdna158+apc+fO8vPzU9u2bfXwww+roKBAs2fPlmEYevnllx3OiYyMlGEYOnDggDZs2KDx48crLCxMhmHonXfe8dAz8bw1a9Zo6tSpys3N9XQpcJE9yTn671eH9X8rD+mrzWkqLin3dEkAAAAAAKCOvDxdQEOza9cujR49WllZWQoMDFT37t2VkZGhl156SSkpKcrJyZEkxcTEVJyTl5en1NRU+fv7a9myZXr66afVokULRUZGymKxqFevXh56Ns6xfv16bdiwQfPnz6/YZrPZtHr1aq1du1YnTpxQcHCwBgwYoEmTJsnPz6/iuNjYWL399tvavn27RowY4YnyXWJD9nGN3LJef+neS7/t1K3KY3w++0A3trxCn1w9xM3VuZ7NZtf7q1L08tL9+m7vCYd9LUP8dOeErnpoWg+1auHvoQoBAAAAAEBd0FPRhOzsbI0bN05ZWVmaM2eOMjMztWPHDmVlZWnhwoVauXKlEhISZBiGQ1C4a9cuSVJxcbEWLFig1157TVlZWUpISFBmZqb69OnjoWfkOosXL9aSJUvUpk0bzZw5U/3799cXX3yhRYsWyWazVRwXEhKijh07KjEx0YPVwplKSst126PrNP0PGyoFipJ0POesnn1zt+KmfKp9h+ihCgAAAABAQ0SoaMJDDz2ktLQ0Pfjgg3r++ecVHBxcsW/evHnq3bu3ysrKFBkZqSZNmlTs2717t6RzvfdeffVV3X333bJarZIki8Uii6Vx/TUcPXpUX375pfr166c5c+bouuuu0x133KHp06dr37592rx5s8PxcXFx2rdvn86ePeuhiuEsdrtddz+9Scu+OHzJY9OOFWjUvV8oLavADZUBAAAAAABnalxplgslJSVp2bJlCg0N1YIFC6o8JjY2VpLUu3dvh+3neyoOHz5cs2bNqvLcw4cPa/z48QoODlbz5s11xx136OTJk857Am60efNm2e12jR492mH78OHD5evrq2+//dZhe1xcnEpLSyt+Tmi4tu45rvdW/FDj4zOOF+rP/9rluoIAAAAAAIBLECrW0NKlS2Wz2TRt2jQFBQVVeYy//7n54aoLFadPn17leWfOnNGwYcOUlpampUuX6o033tDGjRs1duxYh6HCDUVKSooMw1Dnzp0dtvv4+Kh9+/ZKSUlx2N62bVuFh4c3yiHQheXlyi4urvJPY/TKsiTT5/z780M6dabEBdUAAAAAAABXYaGWGoqPj5ckDRs2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dtFW2WxM8wEAABomQkUTHnroIaWlpenBBx/U888/r+Dg//Uymjdvnnr37q2ysjJFRkaqSZMmFft2794t6VzvvVdffVV33323rFarJMlischiaVx/DUePHtWXX36pfv36ac6cObruuut0xx13aPr06dq3b582b97scHxcXJz27duns2fPeqhi1MTugznadcAz4d47nyR7pN3a2H3wpEbd84VO5l18eNvZ4nJNeiReX3yb5qbKAMC9SstsmvH4Nwr099ZbTw2p2B4V2VTP/CpOW/cc16J393qwQtfILyzVDfd9WSlMrMqLS/bpdy8muKEqAAAA52tcaZYLJSUladmyZQoNDdWCBQuqPCY2NlaS1Lt3b4ft53sqDh8+XLNmzap03saNGzVixAhdccUV8vX1VUREhG699VYlJSU590m4yebNm2W32zV69GiH7cOHD5evr6++/fZbh+1xcXEqLS2t+Dmhftq65/hl2bZZdz+9SfmFNZs3sbzcrl/O36jSUtulDwaABmhn0kkteGu3rh8UobsmdpXFYmjxM9fIMKQZj3/TKHvpPf/uXu1IOlnz49/bq8R9lw4gAQAA6htCxRpaunSpbDabpk2bpqCgoCqP8ff3l1R9qDh9+vQqz8vNzVXPnj310ksv6auvvtLChQu1b98+DRgwQGlpDa8XU0pKigzDUOfOnR22+/j4qH379kpJcVw5uG3btgoPD2cIdD23fX+2x9renZyjsrL6H7xt35+tbd+b+2CYeaJQn65r2IvRAMDF/OmNndp14KSen9NP//j9AF3ds6Ue+8d2JR855enSnK601KY3lh80fd6rHxxwQTUAAACuRahYQ/Hx8ZKkYcOGVXvM+QDwwlCxtLRU+/efm4duzJgxVZ43fvx4vfjii5o0aZKuvfZaTZs2TR999JFOnTql5cuXO+spuE1ubq6aNGkib2/vSvtCQkJ05swZlZU59uSKjY3Vzp07VV5e7q4yYdLeHzw351XR2XIdOnraY+3X1Nsf126Y9psfmf8ACgANRVmZXTMe/0Z+vlbdf2u0Nu7I0t/+/b2ny3KJLzalKfNEoenz3l+VooLCUhdUBAAA4Dqs/lxDqannehK1b9++yv1lZWXatGmTJMdQMSkpSSUlJWrfvr3CwsJq3F6LFi0kSV5etf8riouLU1ZWlqlzfHx8qh3eXVPFxcXV1n0+aPz5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T18aqZPfTFOr//+ZMDzMX/96akiDDxQlQkWnqGuo+Pvf/1579+7V6dOnVVpaqsOHD+uvf/2rmjZt6swy66Vhw4Zp8eLFCgkJ8XQpqAE/Xy+9+ZT7JtS+fWwn3TC4dvOR1heGYeiKsAB5e1kqHgMA0JA99dRTOnv2rFvbjIyMVNeuXfXmm29Kko4cOaKhQ4eqadOmlebl3rhxo2JiYmQYhvLy8qq9Zl5enuLi4hQSEqLNmzdftP1PPvlEW7durevTMOWpp55SWFiYxo8fX7Hthx9+0MCBAxUVFaW+fftq3759FfuGDRumkJAQ/e1vf3NrnQCAS2vWxFde//8zoaURfSYkVHSCuoaKlzOr1Spvb29PlwETRg5oo7tv6WrqnKzsQqUdK1BWdvVzDP5ceKi//v67AWbLAwAALvb000+7PVSUpGXLlunOO++UJDVp0kR//vOf9f7771c6bsiQIdq1a9dFr3X69GndcMMNmjx5slatWqXp06fru+++q/Z4T4SKkjRt2jStWLGi4vE999yju+++W8nJyfrd736nmTNnVuxbt26dQwAJAICrESo6QXx8vOx2u8aMGePpUgC3eHFufw3u06rGx/edukJtR/5HfaeuuPTBkgL9vfTxiyNqvIoyAABwj3vvvVfSueAuJiZGx48f15kzZ3TXXXepX79+6tWrl+6++26VlJRIkoYOHao5c+bommuuUbt27fTEE09o1apVGjx4sCIjI/XXv/614tqRkZGaO3euYmNj1blzZy1atKjaOkJCQjR48GAFBpqfliU/P1+/+MUv9NBDD2nevHnq37+/Vq9erfvuu08JCQmVjl+1apVWrFihRYsWKSYmpqK35JIlS3T11Vfrqquu0jXXXKPdu3dLkt59912NGDFCU6dOVffu3TVw4EDt379fN998s6KjozVq1Cjl5+dLOtcbceLEiRo+fLi6deumcePG6eTJk1XWffz4cSUmJur222+XJE2cOFFHjx7VoUOHTP8MAABwBkJFAKYF+Hvp85dHmQoWayo40Fsr/zlK/Xu3dPq1AQBA3bz22muSzg0x3rVrl1q2bKk5c+ZoyJAh2rZtm3bv3i2bzaa///3vFeekpqZq3bp12r17t1566SWtWrVKGzdu1KZNm/Tkk086DFE+duyYEhMTtXXrVv3jH/+45LDk2ggKCtK6det02223VWyLiorSjh071Ldv30rH33jjjRo/frzmzp2rXbt26c4779SmTZu0dOlSffPNN9qxY4eeeeYZh+slJCRo4cKF2r9/vzp16qRx48bptddeU1JSknx8fPTee/9bGXnjxo16//33deDAAbVt21a///3vq6z76NGjuuKKK+TldW6tTcMw1K5dO/3000/O+tEAAGAKqz8DqJWmwT768rUb9PDCLXrzo2SnXLNHp2b694KhiunWwinXAwAArvfJJ59oy5YtFb0Oi4qKZLVaK/bfcsstslqtat68uTp27KixY8fKMAy1adNGYWFhOnLkSMW8iLNnz5ZhGAoNDdWECRP09ddfa+DAgZ54Whf16aefavfu3br66qsrtuXk5KioqEiSNGDAALVr107SuQUJS0tL1arVuS9j+/btqx9++KHivDFjxig8PFySdPfdd2vChAnuehoAANQJoSKAWgvw99K/nhqiW0Z20J1Pfau0YwW1uo7FYuh3s3pp/n195OtjvfQJAACg3rDb7Vq+fLmioqKq3O/n51fx/1artdLjsrKyaq9dXxc4s9vtmjFjhp599tkq97viObdt21aZmZkqKyuTl5eX7Ha7fvrpp4rwEgAAd2P4M4A6u35QhA6uuEVvPjVYV0XXvJdhSFNfzZ3ZU8mf3aJnH44jUAQAoAEIDg7WqVOnKh7fdNNNWrhwYUVQlpubW+t5/t59911J53r9ffzxx7ruuuvqXK8zNGnSxOE5jx8/Xv/+978rhh7bbDYlJibW6tqrVq3SsWPHJElvvvmmRowYUeVxLVu21FVXXaV///vfkqTly5crIiJCnTt3rlW7AADUFT0VAThFgL+XZk/oql/eHKXdB3O0edcxJe7P1q4DOTqVX6Jym13+vlZFtW+q2O6hiusRquH9rpCfL7chAAAakjlz5mjkyJEKCAjQV199pRdffFGPPvqoYmJiZLFY5OXlpeeee65WYVdYWJhiY2N16tQpPfjgg9UOfS4sLFRUVJSKi4t16tQpRUREaPr06VqwYEFdn16Vpk+frpkzZ+qTTz7RAw88oDvvvFPPPfecbr75ZpWVlamkpERjxoxRXFyc6WsPGTJEt912m9LT09WlS5eKYLUqr7/+umbOnKlnn31WTZo00TvvvFOHZwUAQN3waR6AUxmGoZhuLZgXEQCARmr+/PmaP3++w7aXX365ymPXr1/v8Pjnvfl+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", "text/plain": [ - "\"Output" + "
" ] }, - "execution_count": 5, + "execution_count": 2, "metadata": {}, "output_type": "execute_result" } From 9f1e9d5247342cb9ef56688a21968e663b25f1ea Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Fri, 22 May 2026 12:28:18 -0500 Subject: [PATCH 07/28] one more time? --- ...assical-feedforward-and-control-flow.ipynb | 62 ++++++++++++++----- 1 file changed, 46 insertions(+), 16 deletions(-) diff --git a/docs/guides/classical-feedforward-and-control-flow.ipynb b/docs/guides/classical-feedforward-and-control-flow.ipynb index bb5139d1db0..104ffda206b 100644 --- a/docs/guides/classical-feedforward-and-control-flow.ipynb +++ b/docs/guides/classical-feedforward-and-control-flow.ipynb @@ -2,6 +2,7 @@ "cells": [ { "cell_type": "markdown", + "id": "943cf52c-41c8-4a2b-bf1d-6df8a90a6353", "metadata": {}, "source": [ "---\n", @@ -15,6 +16,7 @@ }, { "cell_type": "markdown", + "id": "b1d96290-2e64-43aa-bae9-c74b8529894d", "metadata": { "tags": [ "version-info" @@ -43,6 +45,7 @@ }, { "cell_type": "markdown", + "id": "85a4d698-ee2a-4b3d-9331-1b91eea49338", "metadata": {}, "source": [ "Dynamic circuits are powerful tools with which you can measure qubits in the middle of a quantum circuit execution and then perform classical logic operations within the circuit, based on the outcome of those mid-circuit measurements. This process is also known as _classical feedforward_. While these are early days of understanding how best to take advantage of dynamic circuits, the quantum research community has already identified a number of use cases, such as the following:\n", @@ -54,6 +57,7 @@ }, { "cell_type": "markdown", + "id": "5d846edf-fc09-4808-bd62-3a8cfdcc1585", "metadata": {}, "source": [ "## `if` statement\n", @@ -66,6 +70,7 @@ { "cell_type": "code", "execution_count": 1, + "id": "60924bfa-50ed-4d9d-a17b-9d64f2cc053f", "metadata": {}, "outputs": [ { @@ -100,6 +105,7 @@ }, { "cell_type": "markdown", + "id": "bef3f447-7282-4de9-9410-6b671e9902c3", "metadata": {}, "source": [ "The `with` statement can be given an assignment target which is itself a context manager that can be stored and subsequently used to create an else block, which is executed whenever the contents of the `if` block are *not* executed.\n", @@ -110,6 +116,7 @@ { "cell_type": "code", "execution_count": 2, + "id": "20f0640a-a3f7-41b3-aada-b66bc89b0555", "metadata": {}, "outputs": [ { @@ -145,6 +152,7 @@ }, { "cell_type": "markdown", + "id": "f0f00f48-a1f2-40cc-b5f5-9a122d8dd24e", "metadata": {}, "source": [ "In addition to conditioning on a single classical bit, it's also possible to condition on the value of a classical register composed of multiple bits.\n", @@ -155,6 +163,7 @@ { "cell_type": "code", "execution_count": 3, + "id": "98e8f552-4169-42a3-8182-e14e9ffb59e2", "metadata": {}, "outputs": [ { @@ -189,23 +198,23 @@ }, { "cell_type": "markdown", + "id": "ef8fd422-6bab-46c9-9455-c79244cf1fb7", "metadata": {}, "source": [ "## Classical expressions\n", "\n", "The Qiskit classical expression module [`qiskit.circuit.classical`](/docs/api/qiskit/circuit_classical) contains an exploratory representation of runtime operations on classical values during circuit execution. Due to hardware limitations, only `QuantumCircuit.if_test()` conditions are currently supported.\n", "\n", - "The following example shows that you can use the calculation of the parity to create an n-qubit GHZ-like state using dynamic circuits. First, generate $n/2$ Bell pairs on adjacent qubits. Then, glue these pairs together using a layer of CNOT gates in between pairs. You then measure the target qubit of all prior CNOT gates and reset each measured qubit to the state $\\vert 0 \\rangle$. You apply $X$ to every unmeasured site for which the parity of all preceding bits is odd. Finally, CNOT gates are applied to the measured qubits to re-establish the entanglement lost in the measurement.\n", + "The following example shows that you can use the calculation of the parity to create an n-qubit GHZ state using dynamic circuits. First, generate $n/2$ Bell pairs on adjacent qubits. Then, glue these pairs together using a layer of CNOT gates in between pairs. You then measure the target qubit of all prior CNOT gates and reset each measured qubit to the state $\\vert 0 \\rangle$. You apply $X$ to every unmeasured site for which the parity of all preceding bits is odd. Finally, CNOT gates are applied to the measured qubits to re-establish the entanglement lost in the measurement.\n", "\n", "\n", - "In the parity calculation, the first element of the constructed expression involves lifting the Python object `mr[0]` to a [`Value`](/docs/api/qiskit/circuit_classical#value) node (`lift` is used to turn arbitrary objects into classical expressions). This is not necessary for `mr[1]` and the possible following classical register, as they are inputs to `expr.bit_xor`, and any necessary lifting is done automatically in these cases. Such expressions can be built up in loops and other constructs.\n", - "\n", - "With `qiskit-ibm-runtime` v0.47.0 or later, you can use the [`store`](/docs/api/qiskit/circuit#store) directive, which lets you break down complex classical bit operations into multi-step computations by creating temporary variables. Operations are automatically parallelized, making your code significantly more efficient at runtime." + "In the parity calculation, the first element of the constructed expression involves lifting the Python object `mr[0]` to a [`Value`](/docs/api/qiskit/circuit_classical#value) node (`lift` is used to turn arbitrary objects into classical expressions). This is not necessary for `mr[1]` and the possible following classical register, as they are inputs to `expr.bit_xor`, and any necessary lifting is done automatically in these cases. Such expressions can be built up in loops and other constructs." ] }, { "cell_type": "code", - "execution_count": 1, + "execution_count": 4, + "id": "7581ac2f-53e9-43d0-bad0-2c80790172e1", "metadata": {}, "outputs": [], "source": [ @@ -219,8 +228,7 @@ "\n", "qr = QuantumRegister(num_qubits, \"qr\")\n", "mr = ClassicalRegister(len(meas_qubits), \"m\")\n", - "temp = ClassicalRegister(len(meas_qubits), \"temp\")\n", - "qc = QuantumCircuit(qr, mr, temp)\n", + "qc = QuantumCircuit(qr, mr)\n", "\n", "# Create local Bell pairs\n", "qc.reset(qr)\n", @@ -250,11 +258,11 @@ "\n", " # build XOR-parity expression\n", " parity = expr.lift(\n", - " temp[left_bits[0]]\n", + " mr[left_bits[0]]\n", " ) # lift the first bit to Value so it will be treated like a boolean.\n", " for k in left_bits[1:]:\n", " parity = expr.bit_xor(\n", - " temp[k], parity\n", + " mr[k], parity\n", " ) # calculate parity with all other bits\n", " with qc.if_test(parity): # Add X if parity is 1\n", " qc.x(qr[tgt])\n", @@ -266,17 +274,17 @@ }, { "cell_type": "code", - "execution_count": 2, + "execution_count": 5, + "id": "d0f0abdb-50d5-408d-a704-a1a555acdd85", "metadata": {}, "outputs": [ { "data": { - "image/png": "iVBORw0KGgoAAAANSUhEUgAABRUAAAKxCAYAAADNUksFAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjksIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvJkbTWQAAAAlwSFlzAAAPYQAAD2EBqD+naQAA0sBJREFUeJzs3Xd4lfX9//HXfU72YIQEIgQIKxAQCCYgUwEBRUYVBEFEoLi12hahtg60rVJEa2utq07oV4oVBwqoSACRIQlbCEQiRLKAkATIIOuc3x/8SDkmgdzJGUl4Pq6LS8+9Pu8TTu7DeZ3PMOx2u10AAAAAAAAAUEMWTxcAAAAAAAAAoGEhVAQAAAAAAABgCqEiAAAAAAAAAFMIFQEAAAAAAACYQqgIAAAAAAAAwBRCRQAAAAAAAACmECoCAAAAAAAAMIVQEQAAAAAAAIAphIoAAAAAAAAATCFUBAAAAAAAAGAKoSIAAAAAAAAAUwgVAQAAAAAAAJhCqAgAAAAAAADAFEJFAAAAAAAAAKYQKgIAAAAAAAAwhVARAAAAAAAAgCmEigAAAAAAAABMIVQEAAAAAAAAYAqhIgAAAAAAAABTCBUBAAAAAAAAmEKoCAAAAAAAAMAUQkUAAAAAAAAAphAqAgAAAAAAADCFUBEAAAAAAACAKYSKAAAAAAAAAEwhVAQAAAAAAABgCqEiAAAAAAAAAFMIFQEAAAAAAACYQqgIAAAAAAAAwBRCRQAAAAAAAACmECoCAAAAAAAAMIVQEQAAAAAAAIAphIoAAAAAAAAATCFUBAAAAAAAAGAKoSIAAAAAAAAAUwgVAQAAAAAAAJhCqAgAAAAAAADAFC9PF4D6xW63q7y83NNl1JjVapVhGE67nt1ul4qLnXY9t/D1derPAAAAAAAA4FIIFeGgvLxcy5cv93QZNTZx4kR5eTnxZVxcrLLJM5x3PTfw+uA9yc/P02UAAAAAAIDLCMOfAQAAAAAAAJhCqAgAAAAAAADAFEJFAAAAAAAAAKYQKgIAAAAAAAAwhVARAAAAAAAAgCmEigAAAAAAAABMIVQEAAAAAAAAYAqhIgAAAAAAAABTCBUBAAAAAAAAmEKoCAAAAAAAAMAUQkUAAAAAAAAAphAqAgAAAAAAADCFUBEAAAAAAACAKYSKtZCdna158+apc+fO8vPzU9u2bfXwww+roKBAs2fPlmEYevnllx3OiYyMlGEYOnDggDZs2KDx48crLCxMhmHonXfe8dAz8bw1a9Zo6tSpys3N9XQpcJE9yTn671eH9X8rD+mrzWkqLin3dEkAAAAAAKCOvDxdQEOza9cujR49WllZWQoMDFT37t2VkZGhl156SSkpKcrJyZEkxcTEVJyTl5en1NRU+fv7a9myZXr66afVokULRUZGymKxqFevXh56Ns6xfv16bdiwQfPnz6/YZrPZtHr1aq1du1YnTpxQcHCwBgwYoEmTJsnPz6/iuNjYWL399tvavn27RowY4YnyXWJD9nGN3LJef+neS7/t1K3KY3w++0A3trxCn1w9xM3VuZ7NZtf7q1L08tL9+m7vCYd9LUP8dOeErnpoWg+1auHvoQoBAAAAAEBd0FPRhOzsbI0bN05ZWVmaM2eOMjMztWPHDmVlZWnhwoVauXKlEhISZBiGQ1C4a9cuSVJxcbEWLFig1157TVlZWUpISFBmZqb69OnjoWfkOosXL9aSJUvUpk0bzZw5U/3799cXX3yhRYsWyWazVRwXEhKijh07KjEx0YPVwplKSst126PrNP0PGyoFipJ0POesnn1zt+KmfKp9h+ihCgAAAABAQ0SoaMJDDz2ktLQ0Pfjgg3r++ecVHBxcsW/evHnq3bu3ysrKFBkZqSZNmlTs2717t6RzvfdeffVV3X333bJarZIki8Uii6Vx/TUcPXpUX375pfr166c5c+bouuuu0x133KHp06dr37592rx5s8PxcXFx2rdvn86ePeuhiuEsdrtddz+9Scu+OHzJY9OOFWjUvV8oLavADZUBAAAAAABnalxplgslJSVp2bJlCg0N1YIFC6o8JjY2VpLUu3dvh+3neyoOHz5cs2bNqvLcw4cPa/z48QoODlbz5s11xx136OTJk857Am60efNm2e12jR492mH78OHD5evrq2+//dZhe1xcnEpLSyt+Tmi4tu45rvdW/FDj4zOOF+rP/9rluoIAAAAAAIBLECrW0NKlS2Wz2TRt2jQFBQVVeYy//7n54aoLFadPn17leWfOnNGwYcOUlpampUuX6o033tDGjRs1duxYh6HCDUVKSooMw1Dnzp0dtvv4+Kh9+/ZKSUlx2N62bVuFh4c3yiHQheXlyi4urvJPY/TKsiTT5/z780M6dabEBdUAAAAAAABXYaGWGoqPj5ckDRs2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dtFW2WxM8wEAABomQkUTHnroIaWlpenBBx/U888/r+Dg//Uymjdvnnr37q2ysjJFRkaqSZMmFft2794t6VzvvVdffVV33323rFarJMlischiaVx/DUePHtWXX36pfv36ac6cObruuut0xx13aPr06dq3b582b97scHxcXJz27duns2fPeqhi1MTugznadcAz4d47nyR7pN3a2H3wpEbd84VO5l18eNvZ4nJNeiReX3yb5qbKAMC9SstsmvH4Nwr099ZbTw2p2B4V2VTP/CpOW/cc16J393qwQtfILyzVDfd9WSlMrMqLS/bpdy8muKEqAAAA52tcaZYLJSUladmyZQoNDdWCBQuqPCY2NlaS1Lt3b4ft53sqDh8+XLNmzap03saNGzVixAhdccUV8vX1VUREhG699VYlJSU590m4yebNm2W32zV69GiH7cOHD5evr6++/fZbh+1xcXEqLS2t+Dmhftq65/hl2bZZdz+9SfmFNZs3sbzcrl/O36jSUtulDwaABmhn0kkteGu3rh8UobsmdpXFYmjxM9fIMKQZj3/TKHvpPf/uXu1IOlnz49/bq8R9lw4gAQAA6htCxRpaunSpbDabpk2bpqCgoCqP8ff3l1R9qDh9+vQqz8vNzVXPnj310ksv6auvvtLChQu1b98+DRgwQGlpDa8XU0pKigzDUOfOnR22+/j4qH379kpJcVw5uG3btgoPD2cIdD23fX+2x9renZyjsrL6H7xt35+tbd+b+2CYeaJQn65r2IvRAMDF/OmNndp14KSen9NP//j9AF3ds6Ue+8d2JR855enSnK601KY3lh80fd6rHxxwQTUAAACuRahYQ/Hx8ZKkYcOGVXvM+QDwwlCxtLRU+/efm4duzJgxVZ43fvx4vfjii5o0aZKuvfZaTZs2TR999JFOnTql5cuXO+spuE1ubq6aNGkib2/vSvtCQkJ05swZlZU59uSKjY3Vzp07VV5e7q4yYdLeHzw351XR2XIdOnraY+3X1Nsf126Y9psfmf8ACgANRVmZXTMe/0Z+vlbdf2u0Nu7I0t/+/b2ny3KJLzalKfNEoenz3l+VooLCUhdUBAAA4Dqs/lxDqannehK1b9++yv1lZWXatGmTJMdQMSkpSSUlJWrfvr3CwsJq3F6LFi0kSV5etf8riouLU1ZWlqlzfHx8qh3eXVPFxcXV1n0+aPz5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T18aqZPfTFOr//+ZMDzMX/96akiDDxQlQkWnqGuo+Pvf/1579+7V6dOnVVpaqsOHD+uvf/2rmjZt6swy66Vhw4Zp8eLFCgkJ8XQpqAE/Xy+9+ZT7JtS+fWwn3TC4dvOR1heGYeiKsAB5e1kqHgMA0JA99dRTOnv2rFvbjIyMVNeuXfXmm29Kko4cOaKhQ4eqadOmlebl3rhxo2JiYmQYhvLy8qq9Zl5enuLi4hQSEqLNmzdftP1PPvlEW7durevTMOWpp55SWFiYxo8fX7Hthx9+0MCBAxUVFaW+fftq3759FfuGDRumkJAQ/e1vf3NrnQCAS2vWxFde//8zoaURfSYkVHSCuoaKlzOr1Spvb29PlwETRg5oo7tv6WrqnKzsQqUdK1BWdvVzDP5ceKi//v67AWbLAwAALvb000+7PVSUpGXLlunOO++UJDVp0kR//vOf9f7771c6bsiQIdq1a9dFr3X69GndcMMNmjx5slatWqXp06fru+++q/Z4T4SKkjRt2jStWLGi4vE999yju+++W8nJyfrd736nmTNnVuxbt26dQwAJAICrESo6QXx8vOx2u8aMGePpUgC3eHFufw3u06rGx/edukJtR/5HfaeuuPTBkgL9vfTxiyNqvIoyAABwj3vvvVfSueAuJiZGx48f15kzZ3TXXXepX79+6tWrl+6++26VlJRIkoYOHao5c+bommuuUbt27fTEE09o1apVGjx4sCIjI/XXv/614tqRkZGaO3euYmNj1blzZy1atKjaOkJCQjR48GAFBpqfliU/P1+/+MUv9NBDD2nevHnq37+/Vq9erfvuu08JCQmVjl+1apVWrFihRYsWKSYmpqK35JIlS3T11Vfrqquu0jXXXKPdu3dLkt59912NGDFCU6dOVffu3TVw4EDt379fN998s6KjozVq1Cjl5+dLOtcbceLEiRo+fLi6deumcePG6eTJk1XWffz4cSUmJur222+XJE2cOFFHjx7VoUOHTP8MAABwBkJFAKYF+Hvp85dHmQoWayo40Fsr/zlK/Xu3dPq1AQBA3bz22muSzg0x3rVrl1q2bKk5c+ZoyJAh2rZtm3bv3i2bzaa///3vFeekpqZq3bp12r17t1566SWtWrVKGzdu1KZNm/Tkk086DFE+duyYEhMTtXXrVv3jH/+45LDk2ggKCtK6det02223VWyLiorSjh071Ldv30rH33jjjRo/frzmzp2rXbt26c4779SmTZu0dOlSffPNN9qxY4eeeeYZh+slJCRo4cKF2r9/vzp16qRx48bptddeU1JSknx8fPTee/9bGXnjxo16//33deDAAbVt21a///3vq6z76NGjuuKKK+TldW6tTcMw1K5dO/3000/O+tEAAGAKqz8DqJWmwT768rUb9PDCLXrzo2SnXLNHp2b694KhiunWwinXAwAArvfJJ59oy5YtFb0Oi4qKZLVaK/bfcsstslqtat68uTp27KixY8fKMAy1adNGYWFhOnLkSMW8iLNnz5ZhGAoNDdWECRP09ddfa+DAgZ54Whf16aefavfu3br66qsrtuXk5KioqEiSNGDAALVr107SuQUJS0tL1arVuS9j+/btqx9++KHivDFjxig8PFySdPfdd2vChAnuehoAANQJoSKAWgvw99K/nhqiW0Z20J1Pfau0YwW1uo7FYuh3s3pp/n195OtjvfQJAACg3rDb7Vq+fLmioqKq3O/n51fx/1artdLjsrKyaq9dXxc4s9vtmjFjhp599tkq97viObdt21aZmZkqKyuTl5eX7Ha7fvrpp4rwEgAAd2P4M4A6u35QhA6uuEVvPjVYV0XXvJdhSFNfzZ3ZU8mf3aJnH44jUAQAoAEIDg7WqVOnKh7fdNNNWrhwYUVQlpubW+t5/t59911J53r9ffzxx7ruuuvqXK8zNGnSxOE5jx8/Xv/+978rhh7bbDYlJibW6tqrVq3SsWPHJElvvvmmRowYUeVxLVu21FVXXaV///vfkqTly5crIiJCnTt3rlW7AADUFT0VAThFgL+XZk/oql/eHKXdB3O0edcxJe7P1q4DOTqVX6Jym13+vlZFtW+q2O6hiusRquH9rpCfL7chAAAakjlz5mjkyJEKCAjQV199pRdffFGPPvqoYmJiZLFY5OXlpeeee65WYVdYWJhiY2N16tQpPfjgg9UOfS4sLFRUVJSKi4t16tQpRUREaPr06VqwYEFdn16Vpk+frpkzZ+qTTz7RAw88oDvvvFPPPfecbr75ZpWVlamkpERjxoxRXFyc6WsPGTJEt912m9LT09WlS5eKYLUqr7/+umbOnKlnn31WTZo00TvvvFOHZwUAQN3waR6AUxmGoZhuLZgXEQCARmr+/PmaP3++w7aXX365ymPXr1/v8Pjnvfl+3qPxtttu03PPPXfJGgICApSWllaDap2jb9++2rdvn8O2KVOmaMqUKZWOnTlzpmbOnFnx+MEHH3TY//jjjzs8joiI0IcfflijOrp27aotW7bUsGoAAFyL4c8AAAAA6rWwsDDdfvvtevPNNy957MaNGxUTE6NWrVrJYmm4H3eCgoL02Wefafz48TU6ftiwYdqwYYMCAwNdXBkAAOfQUxEAAACAxx05cqTafQkJCTW+zpAhQ7Rr1666F+QGTz31VLX7HnnkET3yyCM1vta6deucUBEAADXXcL+6AwAAAAAAAOARhIoAAAAAgMbLbvd0BQDQKBEqAgAAAJc7Xx+Hh/bCQg8VAjiX3W6XCoscN/r5eaYYAGhkmFMRDqxWqyZOnOjpMmrMarV6ugQAAICGr0mw4+OMTNlPnZbRtIln6oHHBPh7KX/rHZ4uw5QA/4t8rD2cKhUXO2wyfv56BwDUCqEiHBiGIS8vXhYAAACXEyO6q+Tr+7/wxWaX7et1sk78hWcLg9sZhqHAAG9Pl+E0tq/WOm5oGSZdEe6ZYgCgkWH4MwAAAHCZM3x9ZfS9ymGbbfFSlb//gexZxzxUFVA7drtd9tSf/l979xkdVbm3Yfzek16lJNQAIWCQHiD0Gro0UQELB0HxIGIB5YBdUI8oFrArNgRUREURpdiQIj1CQEOTKgEiBBIgvcy8H3jJMSSB7GQyk2Su31osnd2e/wzZzMydpyhnzoeyLv8hzz5L5w4yDMNJlQFAxUKXNAAAAACydOusnF83/m+DzSbrZ4tl/WyxFBAg+TAPHcqJlFQpJaXAXZaunRxcDABUXISKAAAAAGS0j5TlhiGyfrU0/87z5y/8Acoxy7jbZTQMc3YZAFBhMPwZAAAAgAzDkGX0rbLcMMTZpQB2Zxl3u9wG9Xd2GQBQodBTEQAAAICk/wWLRqsWsq3fJOuGzdI5eiiinAqqemEOxa6dZAlv6OxqAKDCIVQEAAAAkMswDBktm0stm+st36o6f+68AjzcdU9kY725dZfOZ2YpwNND97Rt4uxSgYL5eMsIDJBCasuwMDgPAEoLoSIAAACAAp1PSdO5tAzJzV2Wtq11fstuncvIkjw8ZblktWgAAOBa+LUNAAAAAAAAAFMIFQEAAAAAAACYQqgIAAAAAAAAwBRCRQAAAAAAAACmECoCAAAAAAAAMIVQEQAAAAAAAIAphIoAAAAAAAAATCFUBAAAAAAAAGAKoSIAAAAAAAAAUwgVAQAAAAAAAJji7uwCULbYbDbl5OQ4u4wic3Nzk2EYdruezWaTMjLsdj2H8PKy62sAwLWVt/cByf7vBXBt3AMAAABFQ6iIPHJycrR48WJnl1FkN954o9zd7fhjnJGh7BGj7Xc9B3D/fJ7k7e3sMgBUEOXtfUAqhfcCuDTuAQAAgKJh+DMAAAAAAAAAUwgVAQAAAAAAAJhCqAgAAAAAAADAFEJFAAAAAAAAAKYQKgIAAAAAAAAwhWXiAMDOUlKztHHnSf22K0G/7TqtuL9TdPJMmiTpdFKGnn5nu9o0qapOEdVVOdDLydUCAAAAAOzJZrMpZs9pbY1NUHRsgvYcStLJM+mSpITEdD3wwia1aRKkDi2qqWHdQCdXW3yEigBgJ3sPJemtRbs179v9Ons+s8Bj0jNzNO2tbZIkby833dw/TPfc3FiRTYMdWSoAAAAAwM6SzmVo/rf79fbnu7Xn0NkCj8nIsuqVj2NzH3dtXV333NxE1/eqJ08PN0eVaheEigBQQmfPZ2ryS5v1wdf7TJ2XnpGjj775Ux9986cGd6+rd57opFrV/EqpSgAAAABAabDZbPrgq32a/PJmnUvOMnXuum1/a922vxVay18fPt1VUe1qlVKV9secigBQAj9uPKZmN3xlOlC81Ldr/lLT67/Sx9/tt1NlAAAAAIDSduzvFPW/+3v9+6lfTQeK/3T4eLJ63rlCE/67Xqlp2XassPQQKgJAMc375k/1v/t7xf2dYpfrJZ3P1KhH1+jpd7bLZrPZ5ZoAAAAAgNKx7/BZdRz1rX7YcMxu13z78z3qN35loVNqlSWEigBQDB9/t1+3P7lWVqv9w79pb23Tc+/vsPt1gfLKarU6uwQAAAAgj0Nx5xV153IdjbdPJ5N/+nX73xp47w9KSS1+z0dHYE5FADApZs9p3f7kWpVmZ8LHXv9Nza+uosE96pZeI0ApslqtOnHihA4ePKiTJ08qKytLbm5u8vPzU/369RUaGiofH58rXicmJkaffPKJHn74YVWtWtUBlQMAAACXl5mVo6GTftLxk6ml1sb67X/rnhkb9dF/u5VaGyVFqAgAJmRm5WjME2uVnW0uUdy6cIhqBPkqPiFVbW9ZWqRz7npmvbq0rq7KgV7FKRVwOJvNpn379unHH39UdHS00tPTCz3WMAyFhoaqV69e6tKli7y9vfMdExMTo5dffllZWVl65plnNH36dFWqVKkUnwEAAABwZc++u0M7950xdU5xvhPOW/qnhvcN1cBuZbOzCcOfiyEhIUFTp05Vw4YN5e3trTp16mjixIlKSUnR2LFjZRiG3njjjTznhIaGyjAM7dmzR2vWrNGQIUMUHBwswzA0d+5cJz0T5/vxxx91yy23KDEx0dmloJTYbDYlp2bpzNkM5eSU/yGML8zdqR17zb15SFKNIF+FVPdTjSDfIp9z4lSqHnxxs+m2AGfYtWuXHn74YU2bNk2//vrrZQNF6cK/DYcOHdL777+vu+++W1988YWysv43vOOfgaJ04X3U39+/VJ8D4Ax8FgIAoHz5fd8ZzfggxvR5xflOKEn/fmq9zqeUzfkV6aloUkxMjK699lrFx8fLz89PTZo00fHjx/Xaa6/pwIEDOnPmQtgQERGRe05SUpKOHDkiHx8fLVq0SE899ZSqVq2q0NBQWSwWtWjRwknPxj5Wr16tNWvWaNq0abnbrFarVqxYoZ9//lmnTp1SQECAOnbsqOHDh+fpjdKmTRt9+OGH+u2339S7d29nlF8q1iScVJ+Nq/V8kxZ6sME1BR7j+e3nGlCtppa07+rg6hzjxKlUvbd4r979co+O/X+XcA93i4b1CdWEmxqrc6vqMgzDyVWak5aerdkLYh3a5oLv9uu/97ZR7ep+Dm0XKKr09HQtXLhQ33//fZ7t/v7+atKkierXr686derIy8tLVqtVCQkJOnTokPbt26e//vpLkpSWlqbFixdry5Ytuvvuu3Xu3Lk8gWKHDh107733yt2djy0om/gsBACA63h5/h+mR66VxIlTqVrw7X5NuLmJw9osKj6dm5CQkKDBgwcrPj5ekydP1rRp0xQQECBJeuGFF/TQQw/J3d1dhmHkCQpjYmIkSRkZGXruuef0zjvvaOzYsXJzc6uwk8/Pnz9fK1euVNu2bTVw4EAdO3ZMK1eu1OHDh/XYY4/JYrnQSbZKlSoKCwtTdHQ0H6QrkLlL9umup9crKzvvz3dWtlULVxzUwhUHdV1UXX36fJR8fcrPP0Nf/HBIZ85mOLTNnByb3lu8V9MntHZou0BRJCYmasaMGTp69Gjutvr16+vaa69Vhw4d5OnpednzDx06pB9++EFr165VTk6Ojh49mvsekZOTI4lAEeUXn4UAAKh4Tiel67OVBx3e7luLduvumxqXuY45DH824f7771dcXJzuvfdevfTSS7mBoiRNnTpVLVu2VHZ2tkJDQxUYGJi7b8eOC6u4Wq1Wvf322xo3bpzc3NwkSRaLJfdDZUVx9OhRff/992rXrp0mT56sXr166bbbbtOoUaMUGxurDRs25Dk+MjJSsbGxVxwqh/Lhg6/26o4n1+ULFC/1zS9/acj9PyozK8dBlZXc+1/tdVq7ttJcFQYohqSkJD311FO5gaKnp6duu+02Pfvss+rWrdsVA0XpQgB51113acaMGQoNDZV0YVg0gSLKOz4LAQBQMX383X5lZDr+O2zsgSRt2nnS4e1eScVKs0rR7t27tWjRIgUFBem5554r8Jg2bdpIklq2bJln+8Weij179tTtt99eaBtff/21OnXqJD8/P1111VXq3LmzYmMdO9TSHjZs2CCbzaZrr702z/aePXvKy8tLv/76a57tkZGRysrKyn2dUH79dSJZdz2zvsjH/7z5uF6e90cpVmQ/mVk52vz7Kae0fexkqo4cT3ZK20BBsrOzNXPmTMXHx0uSgoKC9Pzzz2vAgAHF+kVZvXr1NHz48HznRkVFESiiXOKzEAAAFdOv2/92WtvrtxMqllsLFy6U1WrVyJEjC50o3sfHR1LhoeKoUaMKvf5rr72mESNGqEuXLlq6dKkWLlyo3r17Ky0tzT5PwIEOHDggwzDUsGHDPNs9PT1Vr149HThwIM/2OnXqqEaNGoqOjnZkmQ6RmpOjhIyMAv9URHO+2KOcHHM96t7+fHe5WMAldn+iMrOcV+dvuxKc1jZwqa+//lqHDh2SdCFQnD59umrVqlXs68XExOiVV17JNyXIe++9Vy7fBwE+CwEAUDH9tuu0E9sue98J+fV/Ea1atUrShV4ThYmLi5OUN1TMysrSrl27JEkDBw4s8LwDBw5oypQpmj17tu69997c7QMGDChx3c6QmJiowMBAeXh45NtXpUoV7du3T9nZ2Xl6n7Rp00arV69WTk5O7tDwiuDpvbF6em/5621aHNnZ1mINDz4an6IVv8ZpUPe6pVCV/WzfY37FZ/u2f1o39qnv1BoA6cI8iEuWLJEkubm5afLkyQoKCir29S5d5bl9+/Y6e/as9uzZo4SEBH3yySe688477VE64DB8FgIAoOI5ez5Th46dd1r72/c4L9AsDKFiER05ckTShSFaBcnOztb69ReGff4zVNy9e7cyMzNVr149BQcHF3juhx9+KA8PD/373/+2a82RkZG5Q9OKytPTs9Dh3UWVkZFR6HC1ix+uLz0mMjJSy5Yt0+7du9WsWbMitxUeHq7MTPstre5jsWhXREe7Xe/OumG6sVadAvddu2mNXdoIDw9XWhlY8CfH8NPJylOLde7IsVMUkF70YdPOcN67o+Tbv8B9WxcOUY0g38ueXyPIJ/e/R3+8udDj4hNS1faWpfm2v/L6e/po5tCiF1xGXH/7JPn5B+pE/AmFhITke1zRlcfnf6X3gS+//DJ3zsOhQ4eqfv3ih92XBooX51A8ffq0pk6dqoyMDP38888aMmSIqlWrVuh17P1e8E/l8e8QJVPePgtJ3AMAADhCtuUqqdKDhe6/0vfCkn4n/PPgsVJ57y3JaAlCxSJKSUmRpEKHYS1atEgJCQkKCAjI8wXr4tDnVq1aFXrtDRs2qFGjRvr444/13//+V0ePHtXVV1+tJ598Urfcckuxa46Pj9exY8dMnePl5VXs9v55jXPnzhW47+IXx0vbuTiPltnVsI8fP64MOw4l9nVzkyLsdjk19PdXr+Dq9rtgAY4fP67UnDKw2IlHFaly8U49dz5V506a+1l1uKBkqZD3hxpBvgqp7leky7i7WYp87D+lpKQp5XgZf40KYP3/n01rTo6OHTuW73FFVx6f/+XeB06ePKlt27ZJutDb6vrrry92O4UFiu7u7qpevbqGDBmiL774QjabTT///PNl3w/t/V7wT+Xx7xAlU94+C0ncAwAAOIRHhlSp8N1F/V5Y3O+EVqvK3HsvoWIR1ahRQ4mJidq2bZs6dszbk+3EiROaMmWKJKlFixZ5lvi+uPLz5ULFEydO6NixY3rkkUc0c+ZM1alTRx988IFuvfVWBQcHq3fv3sWu2ayirNZ5JZUrV1ZcXJyysrLyDfs5c+aMAgIC8v32Pjo6Wr6+vmrSpImptmrVqmX3norlTa1atcpET0WrPHXCZpOKscT9Vf7u8veoXQpV2U+yl6/OFrIvPiH1iufXCPKRu5tF2TlWxScUPkdcYdfy8/NUpdpl+zUqiOXiSvdubqpdu3a+xxVdeXz+l3sfWLVqVe5K5L179y72IiqXCxQv6tWrl7766ivl5ORo1apVGjZsWIFDSSX7vxf8U3n8O0TJlLfPQhL3AAAAjpBj+OtyY0Gv9L2wpN8JLZYc1SyF997iZEcXESoWUe/evbV7927NnDlTffr0UXh4uCRp69atGjVqlBISLkyYGRERkee8ovRUtFqtSk5O1oIFCzR06FBJF75M7dq1S88880yxQ8XidF/Nzs7W4sWLi9XeRQ0aNNDOnTu1f/9+NW7cOHd7Zmamjhw5omuuuabAWiMiIkx/Qd23b59dVwa1pacre8Rou13PEfbt2yfD29vZZUiSBkz4Xit+jTN1jpuboV0bP1atauZ/U+NIK9Yd1YB7fihwX0Fd0y919MebFVLdT/EJaarT5zPT7c98+kHdc/P7ps9zthlvfqJzySmqWaOm4uLi8j2u6Mrj87/c+8DOnTslSYZhqGfPnsW6flECRUmqVKmSIiMjtXnzZp0/f16HDx/W1VdfXeA17f1e8E/l8e8QJVPePgtJ3AMAADhCTo5VV3VaoJS07AL3X+l7YUm/E3Zrf41++aBsvfeWv25ZTjJ16lRVrVpVR48eVdOmTdW8eXNdffXVateuncLCwnK/XF268nNReipWqVJFkvKEh4ZhqHfv3vrjjz/s/VRKXceOHWUYhlasWJFn+6pVq5SRkaEuXbrk2X7s2DGdOHFCkZGRjiwTpeCemxtf+aBLXN+zXpkPFCWpTZPiL0Rhl/YbO7d9ICsrK3d+4Vq1aqlSpUqmr1HUQPGif4YxF1ebBsoDPgsBAFDxuLlZ1Oqaqk5rv01j57VdGELFIgoJCdG6des0cOBAeXt76/Dhw6pSpYrmzJmjZcuWad++fZLyhopxcXE6ffq0goKCLjuZZtOmTQvdl56ebr8n4SB169ZV3759tWXLFr388statWqVFixYoAULFqhx48bq3LlznuOjo6Pl7u6er5cnyp/+nUPUrU3Ru077ervr8XERpVeQHVWr6qM6NZwTfrq5GWrZqIpT2gYuiouLy12gpTiLs5gNFCUpLCws9/8PHjxouk3AWfgsBABAxRTZ1HmdPZzd0aUgDH82oXHjxvruu+/ybU9OTtbhw4dlsVjyrNYXEhKSO/fU5Vx33XX68MMP9cMPP+iGG26QdGFI9I8//qi2bdva7wmUktDQ0HzbRo8ereDgYP3888/avn27AgIC1K9fP40YMSJ3IvKLoqOj1bRpU/n6Xn71XJR9bm4Wff1Kb/Ubv1LRsQmXPdbX211fze6llo3K3m9bCjOsT6hmL4h1eLuDutWRjzf/XMO5zpw5k/v/NWvWNHVucQJF6UKPyIuSkpJMtQk4Ep+FAABwDcP61NcrHzv+O6Gvt7uu7WL/lZ9Lim+pdhAbGyubzabw8PBifRgcPHiwunbtqnHjxun06dOqW7eu3n//fcXGxurHH38shYrtKzQ0NN+HaYvFokGDBmnQoEGXPTcpKUn79+/X7bffXooVOl73oGrKHDzissdcaX95VeUqL63+YICenrNdH3y9T6eT8q5GabEYGtStjqbf3UqtytmQ3vHDGzslVJxwk/lh5YC91axZU8OHD1dmZmaB88EVJjk5Wa+++qrpQFGSvL29NXjwYHl6epoOMgFH4rMQAACuoVNENbUIr6Kd+85c+WA7GjmwgSoFejm0zaIgVLSD33//XVL++RSLyjAMLV26VA899JAeffRRnTt3Ti1bttTy5cuLPRF+eXFxMRnmEKpY/Hw9NPOBdnpqQmst/umw7n5mvc6nZivQ30M7v7xe9WoFOLvEYgkPvUp9O9XWDxuOOazNq+sFqncHVteE89WqVUs33nij6fP8/f113333adasWYqMjCxyoChJ7u7uGjlypOk2gfKEz0IAAJQfhmHonpsb666n1zu03btHFP2X+o7EnIp2UNJQUbqwyuWcOXN06tQpZWRkaMuWLerXr5+9SiyzoqKiNH/+/NzFalCxeHu5a+TAhgr095QkBfh6lNtA8aJZ/2kvTw/H/dP5xiMdZbEYDmsPKA2tW7fWU089ZSpQBFwFn4UAAChf7hga7tD5DccNa1RmR/kRKtqBPUJFV+Xm5iYPDw9nlwEUWdOGlTX97tYOaevfNzZS305lb94MoDgaNGhAoAgUgM9CAACUL+7uFn30TFeHdDapW9NPLz7YrtTbKS5CRTtYtWqVbDabBg4c6OxSADjAlDHNFdXW3Pxu8Qmpivs7RfEJqUU6vkmDSnppctl98wAAAAAAV9Xs6iqmv6+Z/U7o6WHRgme75478K4voMgAAJrm7W/TNa73V966V2rTzVJHOaXvL0iJfv0GdAP3wTv8y/eYBAAAAAK7svlub6nRShp56Z3uRjjfzndDD3aJFL0apW2TZXqyQnooAUAwBfp768d1rdW0X+w5PbtMkSL/OG6Ta1f3sel0AAAAAgH1Nn9BaL/+nndzc7DcP/lUBnlr6Wh8N7Rlqt2uWFkJFACgmf18PLXuzr955orP8fUs2H5aHu0VP39NaGxcMVo0gXztVCAAAAAAoTQ/e1lybPh6sZg0rl/haA7qGKParG9Tfzp1XSguhIgCUgGEYumv4Nfrjq+s19vpw+Xi7mTrf3d3Q8L71Ff3ZdXrirlbycODK0gAAAACAkotsGqzoz67TzEltVbem+VFnrRtX1afP99B3b/QtV6PWmFMRAOygXq0Avf9UV704uZ3mffOnVqyP02+7EnQ6KSPfsQF+HmrduKp6ta+lsdeHq1a18vOmAQAAAADIz8vTTVPvaKHJo5tp+bo4fbr8gKJ3JWj/X+fyHevmZqhZw8pq3zxYdwwNV7vmwTIM+w2hdhRCRQCwo8qBXpo0qpkmjWomm82mv04kK+7vVGVk5sjTw6LqVX3UoE6gLJby94YBAAAAALg8NzeLBveoq8E96kqSks5laO/hs0pNz5bFYijQz0ONwyrJ26v8R3Ll/xkAQBllGIbq1QpQvVoBzi4FAAAAAOAElQK91L5FNWeXUSqYvAsAAAAAAACAKYSKAAAAAAAAAEwhVAQAAAAAAABgCqEiAAAAAAAAAFNYqAV5uLm56cYbb3R2GUXm5uZm3wt6ecn983n2vWZp8/JydgUAKhB7vw+8OGeRzqekKMDPT1PuuinfY3uw+3sBXFp5+ywkcQ8AAADnIFREHoZhyN3ddX8sDMOQvL2dXQYAOI293wdskqy2C/91d3fP9xgoa1z9sxAAAEBRMfwZAAAAAAAAgCmEigAAAAAAAABMIVQEAAAAAAAAYAqhIgAAAAAAAABTCBUBAAAAAAAAmEKoCAAAAAAAAMAUQkUAAAAAAAAAphAqAgAAAAAAADCFUBEAAAAAAACAKYSKAAAAAAAAAEwhVAQAAAAAAABgiruzCwAAAAAAoKyxnT4j68bNsm3bISWdlS0jw9klASgKi0WGn58UUkuWzh1kNG8qw534qzTwqgIAAAAA8P9sZxKV8/Lrsv2xS7LZnF0OgGKwSdKuPcr5YZUU4C/LsKFyu36ws8uqcAgVAQAAAADQhUAx+7GnpWPHnV0KAHs5nyzr3I+ljEy53Xyjs6upUJhTEQAAAADg8mypqQSKQAVm/fRz5XyzzNllVCj0VAQAAAAAuDzbpq35A0UfHxntI2Vp2ljy83VOYQDMyc6W7VSCbJujZdu3P88u69ffyjLoWhlu9LGzB0JFAAAAAIDLs67flHdDjepyf266jKpVnFMQgJIZfr1yln0v65wP/7ftTKJsu/fIaNbEeXVVIESzAAAAAACXZktNlW37zjzb3G4ZRqAIlHNuA/tJ9erm2WbbuMVJ1VQ89FREHjabTTk5Oc4uo8jc3NxkGIazywAAAABQnp1KkLKz82wy2kU6qRjAuWw2m1LTsq98YBnh6+N+2VzA0j5S1iN/5T62HT/hiLJcAqEi8sjJydHixYudXUaR3XjjjXJ358cYAAAAQPHZUlLzbvDxkWGnORR/+eUXPfLII4qNjVVycrLmzp2rMWPG2OXaQGlITcuWf4f5zi6jyJI33SY/X49C9xtBVS85IaWUK3IdpDEAAAAAANdmteZ97O5m+hI9evRQdHS0kpOTc7clJibqhhtuUEhIiF5++WX5+vqqU6dOJa0WgBmX3s+X3u8oNkJFAAAAAABKwdatW5WUlKQPPvhAN9xwg7PLAQC7YqEWAAAAAABKQXx8vCSpShUWfAFQ8dBTEQAAAAAAOwsNDdWRI0ckSVFRUbnbbTabs0oCALsiVARQKnJyrNp35Jx27D2tlLQsSVJKWrZ+3RaviGuqyv8yE+kCAAAA5d0rr7yiFStW6N1339Wjjz6qxo0bO7skALArQkUAdpOZlaOvfjqs97/ap007TyolLTvP/qTzmeo6ZpkMQ2ocVknD+9TXuGGNVKuan5MqBgAAAErH0KFDlZSUpHfffVd9+vRRjx49nF0SANgVoSKAEsvKsmrWgt81a/4fOnkm/YrH22zSrgNJeurAdv33vRjd2DtULzzQVvVqBTigWgAAAAAAUFIs1AKgRH7fd0Yd/rVUD78SXaRA8VI5OTZ9/v0hNb/xa7375R7mmAEAAAAAoBwgVARQbJ8uO6A2N3+jbbtPl/ha51OydNfT6zV88iplZObYoToAAAAAAFBaCBUBFMtH3+zTvx5draxsq12vu/inwxo68SdlZhEsAgAAAABQVhEqAjDt+/VxGjvtV5XWSOWV6+M0dtq60rk4AAAAAAAoMUJFAKYknsvQHdPWyWoteqK4deEQHf3xZm1dOKTI53z83QF9+cOh4pQIAAAAAABKGaEiAFMeeGGzjp9MNXVOjSBfhVT3U40gX1PnTXh2g06dSTN1DgAAAAAAKH2EisWQkJCgqVOnqmHDhvL29ladOnU0ceJEpaSkaOzYsTIMQ2+88Uaec0JDQ2UYhvbs2aM1a9ZoyJAhCg4OlmEYmjt3rpOeifP9+OOPuuWWW5SYmOjsUlAEv+87o3lL/3RYe6cS0zXzw50Oaw8AAAAortWrVys5OTnPtjFjxshms6lHjx7OKQpwomfvbyPbzrG6fejVBe7/5YMBSo8eo6YNKzu4MtgLoaJJMTExat68uV588UXFx8erSZMmysrK0muvvaabbrpJu3fvliRFRETknpOUlKQjR47Ix8dHixYtUlRUlDZu3KjQ0FBVq1ZNLVq0cNKzsY/Vq1frqaeeyrPNarVq2bJlevDBBzVq1ChNmDBBCxYsUHp6ep7j2rRpI0n67bffHFYviu+tRbsd3uaHS/YpLT3b4e0CAAAAAIpv+lvb9fufZzTrP+1Vu3reUWuT/tVUPdrW1LS3til2P52MyitCRRMSEhI0ePBgxcfHa/LkyTpx4oS2bdum+Ph4zZw5U8uWLdPWrVtlGEaeoDAmJkaSlJGRoeeee07vvPOO4uPjtXXrVp04cUKtWrVy0jMqPfPnz9eCBQtUu3ZtjRkzRh06dNDKlSv14osvymr932rBVapUUVhYmKKjo51YLYriXHKmFny33+HtJp7L1GcrDzq8XQAAAABA8WVlWzX68bXy8/HQB9O75m4PD71Kz94XqU07T+rFj353YoUoKUJFE+6//37FxcXp3nvv1UsvvaSAgIDcfVOnTlXLli2VnZ2t0NBQBQYG5u7bsWOHpAu9995++22NGzdObm5ukiSLxSKLpWL9NRw9elTff/+92rVrp8mTJ6tXr1667bbbNGrUKMXGxmrDhg15jo+MjFRsbGy+XowoW9ZExyslzTk9BpetPeqUdgEAAAAAxbd992k998EO9escon/f2EgWi6H5z3aTYUijH19ragFQlD0VK80qRbt379aiRYsUFBSk5557rsBjLg7lbdmyZZ7tF3sq9uzZU7fffnu+83r06CHDMAr8M378ePs+EQfYsGGDbDabrr322jzbe/bsKS8vL/366695tkdGRiorKyv3dULZ9NuuBJdsGwAAAABQfM+8u10xe07rpcnt9PojHdW+eTU99vpv2nf4rLNLQwm5O7uA8mLhwoWyWq0aOXKk/P39CzzGx8dHUuGh4qhRowo876233tK5c+fybFu2bJn++9//atCgQSWs3PEOHDggwzDUsGHDPNs9PT1Vr149HThwIM/2OnXqqEaNGoqOjlaHDh0cWSpMcGawd/h4sk4npatqJW+n1QAAAAAAMC8726bRj6/V1oVDNOGmxlq3LV6vfPyHs8uCHRAqFtGqVaskSVFRUYUeExcXJylvqJiVlaVdu3ZJkgYOHFjgeU2aNMm37dlnn1VwcLD69+9f7JqdJTExUYGBgfLw8Mi3r0qVKtq3b5+ys7Pl7v6/H782bdpo9erVysnJyR0ajrLlr/gUp7Z/ND6FUBEAAAAAyqGzyZnKyMyRp4eblq87KhujnisEQsUiOnLkiCSpXr16Be7Pzs7W+vXrJeUNFXfv3q3MzEzVq1dPwcHBRWrr1KlTWrlypSZMmJAneDMrMjJS8fHxps7x9PQsdHh3UWVkZBRa98Wg8dJjIiMjtWzZMu3evVvNmjUrclvh4eHKzMwsUb0omr+vuldyK/hneOvCIaoR5FvgPkmqEeST+9+jP9582XbiE1LV9pal+bb37TdAnjnHTFSMsuD62yfJzz9QJ+JPKCQkJN/jis7Vn79U/l+D8l4/UFLcA3AV7fwDtSi8ee7jxMREteZnHC7KKg+pyuN2vebcp7vK08NNuw4k6vFxEfr8+0M6GHfeLte+OjxcFmUVun9YlWp6MfTq3McxMTEayv2d6+LI0eIgVCyilJQLvbTS0tIK3L9o0SIlJCQoICBA9evXz91+ceizmRWeFy5cqOzs7EKHSxdVfHy8jh0zF8J4eXmVqM2L17h0OPdFWVlZBbZzcbGaf64MXRTHjx9XRkZGMaqEaT4Zkk/Bu2oE+Sqkut8VL+HuZinScQU5dfKElE6oWN5Yc3Jy/3vs2LF8jys6V3/+Uvl/Dcp7/UBJcQ/AVZyqkiGF/++x1WrlZxyuy/CUqtjvcvfd2kRR7Wrp0dei9c0vR7Rt0VB9+HRX9bhjuV2uf+L4cclWeGejREveUZSZmZnc33ZCqFhENWrUUGJiorZt26aOHTvm2XfixAlNmTJFktSiRQsZhpG77+LKz2ZCxQULFqhx48aKjIwscc1meXp6lqhNSapcubLi4uKUlZWVbwj0mTNnFBAQkK8nY3R0tHx9fQscCn45tWrVoqeig5xyz1Rhr3R8Quplz60R5CN3N4uyc6yKTyg4mL/StaoH+8vdWrsopaIMsVxc6d7NTbVr1873uKJz9ecvlf/XoLzXD5QU9wBcRbB/YJ7HFouFn3G4LKs8dMJO12pYN1DPTYzUlt9PaeaHO2W12jT97W16bmJb3XdrE73+6a4St1GzVq3L9lSsXKlynseenp7c3/9QnOzoIkLFIurdu7d2796tmTNnqk+fPgoPv/BrrK1bt2rUqFFKSLiwiEVERESe88z2VNyzZ4+io6M1Y8aMEtdcnO6r2dnZWrx4cYnabdCggXbu3Kn9+/ercePGudszMzN15MgRXXPNNQXWGhERYXq49759+0o0RBxFN+XlLXpp3u8F7itouPI/Hf3xZoVU91N8Qprq9PnMdNvBlb11YkdsnsAe5cOMNz/RueQU1axRU3FxcfkeV3Su/vyl8v8alPf6gZLiHoCrsP6xSzmPPpX7+GJHCcAVpaRmyb/D/BJfxzCkj57pJjeLodGPr5HVemEixRfm/q4beoXquYmRWrb2aImHQf+5b5/8fPOv6XCR9adflPPaO7mPIyIiFPezfXpJujqLswsoL6ZOnaqqVavq6NGjatq0qZo3b66rr75a7dq1U1hYmHr27Ckp/8rPZnsqLliwQIZhaOTIkfZ9Ag7UsWNHGYahFStW5Nm+atUqZWRkqEuXLnm2Hzt2TCdOnChxz0yUrjZNqjqx7SACRQAAAAAoRyaPbq7Orarrybe2ac+hs7nbrVabxjyxVu5uFn34dFcnVoiSIlQsopCQEK1bt04DBw6Ut7e3Dh8+rCpVqmjOnDlatmyZ9u3bJylvqBgXF6fTp08rKCioSBNZ22w2ffLJJ+rRo4fq1q1bas+ltNWtW1d9+/bVli1b9PLLL2vVqlVasGBB7rDuzp075zk+Ojpa7u7u+Xp5omzp2rqGLBbnBHtRbWs6pV0AAAAAgHnX1L9Kz9zTWht3nNTL8/7It3/XgSRNf3ubukfW1H23mpsGDWUH40ZNaNy4sb777rt825OTk3X48GFZLJY8KxeHhITIZmKd9LVr1+rIkSOaNm2aXep1lNDQ0HzbRo8ereDgYP3888/avn27AgIC1K9fP40YMSJ3UZaLoqOj1bRpU/n6Fr56MJyvdnU/DelRV0tWHXFou54eFt0+9OorHwgAAAAAKBP2HDorn7bzLnvM8x/s1PMf7HRQRSgNhIp2EBsbK5vNpvDw8BIFYwsWLJCPj4+GDRtmx+pKX2hoaL5g0WKxaNCgQRo0aNBlz01KStL+/ft1++23l2KFsJd7bm7s8FBxRL/6Cq5SyLLTAAAAAADAKRj+bAe//35h8YpL51M0Iz09XV9++aWGDh2qgIAAe5VW5l1cTIb5FMuHnu1qqUur6g5rz9PDoofvKP59BQAAAAAASgehoh3YI1T09vZWUlKSPv30U3uVVS5ERUVp/vz5qlKlirNLQRFYLIY+fLqrfLzdHNLetPGt1LRhZYe0BQAAABTV9OnTlZ6e7tA2Q0ND1ahRI73//vuSLiyE2a5dOzVp0kRNmzbV1KlTZbVaJUkHDhxQRESEPD09FRMTU+g1MzMzNWDAAPn6+uqrr766Yg07duzQwIEDJV0Ydfb888+X/ImZZBiGmjdvruXLL6zeu3XrVnXq1Em+vr4aOnRonmMXLVqkJk2aqFKlSpe95l9//aUGDRqoTp06ueslFOajjz7Snj17SvIUTBszZoxq166t8ePH527bvHmzWrZsqfDwcPXs2VPHjh2TJKWlpSkiIkL+/v5asmSJJOk///mPy2UNcAxCRTuwR6joqtzc3OThUfjS7yh7rq53lZ6f2NbUOfEJqYr7O0XxCalFPqdtsyBNvb2F2fIAAACAUvfUU085PFSULoRkd955pySpcuXK+uyzz7Rr1y799ttv2rBhg+bPny9JatCggWJiYlSrVq1Cr5WVlaVhw4bp6quv1rZt2/Too4/qm2++uWz7jzzyiB5++GFJzgsVJWndunUaMGCAJKlmzZp65ZVXNHv27HzH3XTTTbnhY2GOHTum/v3765lnntGbb76pgQMHav/+/YUe74xQUZKmTJmid955R5JktVo1cuRIvfLKK9q3b58GDBigSZMmSZJ8fHwUExOTZzTg1KlTNX36dOXk5Di8blRshIp2sGrVKtlsttzf2AAV3X23NtG9txR9ha62tyxVnT6fqe0tS4t0fMO6gVr6Wh+5u/NPFAAAAMqWi73FunbtqoiICJ08eVLnz5/Xv//9b7Vr104tWrTQuHHjlJmZKUnq0aOHJk+erG7duqlu3bp64okntHz5cnXp0kWhoaGaNWtW7rVDQ0M1ZcoUtWnTRg0bNtSLL75YaB2tWrVSWFiYpAsj3yIiInT48OEiPYfs7GzdfPPN6tKli1599VVdc801WrNmjWbOnFng4qTShd58sbGx6tq1a+7rcP78eUVEROQGWPHx8RoxYoTatWun5s2b6/HHH8/z3B5//HF16tRJderU0TvvvKO5c+eqY8eOCg0N1WeffZZ7rGEYevzxx9WqVSuFh4frk08+KfS5hISEqF27dvLy8irSc/+n+Ph4DR06VG+88YZuvfVWDRkyRAsWLNDw4cN18ODBfMe///77io6O1gMPPKCIiIjcwPKll15Su3bt1Lp1a/Xv319HjlyYh3769OkaMWKEBg8erPDwcA0aNEh//PGH+vXrp/DwcN1yyy25vUvHjBmjO+64Q506dVJ4eLhGjx6ttLS0Auv+7bff5O7urqioKEnSXXfdpW+//bbQoLtatWpq0KCBfvjhB9OvEXA5fGMHYJphGHr1oQ6aOLKp3a/dpEElrf5ggGoEsRo4AAAAyp6LvcXWrVunmJgYVatWTZMnT1bXrl21ZcsW7dixQ1arVa+++mruOUeOHNEvv/yiHTt26LXXXtPy5cu1bt06rV+/Xk8++aSSkpJyj/37778VHR2tTZs26fXXX9eGDRuuWFN8fLy+/PLLKy6UeZG7u7sWL16sqVOn5m6rXr26NmzYUOg11qxZo7Zt/zdi6Z133lFAQIBiYmJy58ofPXq07rnnHm3ZskXbt29XdHS0vvjii9xzUlJStGHDBv3yyy964IEHdOzYMW3cuFFffPGF7rvvvjztGYah7du3a+XKlbrvvvuKHJiaUaNGDW3dulU9e/bM3dahQwdt3749N7D9pzvvvFORkZGaPXu2YmJiNGDAAH366afau3evNm7cqG3btmnkyJGaMGFC7jnR0dGaP3++9u7dq/Pnz+vOO+/Ul19+qV27dmn37t1asWJF7rGbN2/W999/r927d+vMmTMF9r6ULgS89erVy30cEBCgwMBAHT9+vNDn2rFjR/3888+mXh/gSlj9GUCxWCyGZk9tr9aNq2rizE1KOp9Z4mvePvRqzfpPe1UKNP9bRgAAAMBZlixZoo0bN+b2OkxLS5Ob2//mIR82bJjc3NxUuXJlhYWFadCgQTIMQ7Vr11ZwcLAOHz6siIgISdLYsWNlGIaCgoJ0ww036KefflKnTp0KbfvcuXMaPHiwpk6dWqoLYMbFxal69cIXbUxJSdHPP/+sv//+O3dbcnKy9u7dm/v4pptukiQ1bNhQ3t7eGjZsmKQLC3eeOXNGSUlJufMfXhzmHRYWpm7dumnt2rUKDQ2187MquSVLlmjr1q1q06aNJOUbYty3b19VrnxhnvjWrVvLy8srd3HWVq1a6c8//8w9dsSIEbn7xo4dq9dee02PPvqoXeqsUaOGdu3aZZdrARcRKgIoNsMwdNuQq9WrfS3dM2ODvvnlr2JdJ7SWv958rJMGdK1j5woBAACA0mez2bR48WKFh4cXuN/b2zv3/93c3PI9zs7OLvTahmEUuu/8+fPq37+/rrvuOj344IPFqLzofH19LzuPpM1mkyRt2rQpz/P7p8JeB8MwZBhGsV8HZ7LZbHrkkUc0bty4AveXxt993bp1c4dYSxd+Ds6ePXvZOTTT09Pl4+NT6H6gOBj+DKDEalf305JX+2jPNzdq0r+a6qoAzyueYxhS/84hWvpaH+1fNpxAEQAAAOVGQECAzp49m/t46NChmjlzZm5AlJiYeNnFPi7no48+kiSdOXNGX3/9tXr16lXgccnJyerfv7/69++fZ+7C0tKiRYs8vQ4DAwOVlpaWO3ekv7+/oqKi8izecvz4ccXFxRWrvblz50qSDh8+rHXr1uXO5ehsgYGB+f7u33nnHZ05c0bShQVwtm/fXqxrf/nll0pOTlZOTo7mzp2r3r17F3hcmzZtlJWVpV9++UWSNGfOHA0ePLjQMFeSdu/ezeKysDt6KgKwm0b1K2n21A568cF22nUwSb/tSlDMntM6m5ylHKtVPl7uCq93ldo0qarWjYOKFD4CAAAAZc3kyZPVp08f+fr66ocfftDs2bP18MMPKyIiQhaLRe7u7nrhhRfUsGFD09cODg5WmzZtdPbsWd17772FDn1+9dVXtWXLFqWkpOirr76SJA0fPlyPPfZYiZ5bYbp06aK4uDidOXNGVapUUZUqVXTbbbepRYsW8vf3V3R0tD755BM9+OCDatasmQzDkJ+fn+bMmaOQkBDT7eXk5KhVq1ZKSUnRa6+9VujQ571796pXr15KTU1VWlqaQkJC9Oijj+aZ19Cexo0bp8mTJ2v27NmaMWOGRo4cqdOnT+cumpKdna077rhDrVq1Mn3ttm3bql+/fjp16pQ6duyYu6LzpSwWiz7++GPdddddSk9PV61atbRgwYJCr2uz2fTzzz/nrtwN2AuhIgC7c3e3qEV4FbUIr+LsUgAAAAC7mzZtmqZNm5Zn2xtvvFHgsatXr87z+OKiJhdd2qPx1ltv1QsvvHDFGh577LFSCxAL4uHhoXvuuUcffPCBpkyZIkl677338hxTrVo1ffzxxwWef+lCKwkJCXkeXzoMePLkyXrmmWeuWFejRo2K3RuyOAYNGpRvMZv7779f999/f75jp0+fnufxSy+9lOfx+++/n+dxixYt9OGHHxapjo4dO2rnzp1FOvb7779Xu3bt8izuAtgDw58BAAAAACjjgoOD9a9//StfEFWQAwcOKCIiQllZWfLw8LBbDRMnTpS/v7/drlcc1atXV/fu3bV8+fIrHrto0SINHjz4sgvMlAdXXXWV3nrrLY0fP/6Kx6alpSkiIkIHDx7MHQ599uzZIgXVgFn0VAQAAAAAoAy4tDffP23durXI12nQoIFiYmJKXtAlPD09dffdd9v9upe6uOhLQeLj44t8nZtuuil3xemy7uJcmgV59dVX9eqrrxbpOj4+Pvn+7svLa4Dyh56KAAAAAAAAAEwhVAQAAAAAuDbDyPvYanVOHQDs79L7+dL7HcVGqAgAAAAAcGmGj0/eDalpsmVlF3wwgHLFdu583g2+vs4ppAJiTkXk4ebmphtvvNHZZRSZm5ubs0sAAAAAUN5VqZz3sc0m247fZUS2ck49gBP5+rgredNtzi6jyHx9Lh9t2bbvyLuhauWCD4RphIrIwzAMubvzYwEAAADAdRiVrpJxTbhse/blbrN+vVRGi6YyPD2dWBngeIZhyM/XfquGO5M1drdssbvzbLO0b+ukaioe0iMAAAAAgMszOnfIEyraft+l7IeelKV3lCzNGl8YMslcbEDZl50t26kE2TZtlfXHVZL1H6uJ+3jLaNXSebVVMISKAAAAAACXZ+nSUdaFX0ipaf/beOCQrAcOiWVbgIrB0r2rDC96H9sLC7UAAAAAAFyeUbWK3KY/Kvn6XPlgAOWO0aGtLP8e4+wyKhRCRQAAAAAAJFmuCb8QLPr7ObsUAHZkdGovtymTZHgwYNeeeDUBAAAAAPh/lmvCZcx9R7btO2Rdv1G2bTuk88nOLguAGW5uUkgtWTp3kKVzBxl1QpxdUYVEqAgAAAAAwD8YXp4yOrTVm3uP6nynqgrw89G9I/rrjUXLdT4lXQF+3rr3pgHOLhNAQSwWyctLBgsrlTpCRQAAAAAACnA+OU3nklMkSYavr86nZuhcSqpkGDJ8fZ1cHQA4F3MqAgAAAAAAADCFUBEAAAAAAACAKYSKAAAAAAAAAEwhVAQAAAAAAABgCqEiAAAAAAAAAFMIFQEAAAAAAACYQqgIAAAAAAAAwBRCRQAAAAAAAACmECoCAAAAAAAAMIVQEQAAAAAAAIAphIoAAAAAAAAATCFUBAAAAAAAAGAKoSIAAAAAAAAAUwgVAQAAAAAAAJhCqOjCFixYoDZt2qhy5cry8fFR48aNNWvWLNlsNmeXBgCFWr58uSIiIuTl5aXQ0FDNmjXL2SU51Nq1a3XdddepXr16MgxD//3vf51dkkO9+OKL6tixoypXrqxKlSqpS5cuWrlypbPLAgAAAFyOu7MLgPNUq1ZNTzzxhBo1aiQvLy+tW7dOEyZMkJubmyZOnOjs8gAgn+joaF133XX6z3/+o4ULF2rz5s0aP368fH19NX78eGeX5xDJyclq0qSJbr31Vk2aNMnZ5TjcqlWrdMcdd6ht27by9fXV+++/r0GDBmnNmjXq3Lmzs8sDAAAAXAahogvr169fnsdhYWFasmSJVq9eTagIoEyaNWuW2rZtq+eee06S1LhxY8XGxur55593mVBxwIABGjBggCTpoYcecnI1jrdixYo8j1944QWtXLlSX331FaEiAAAA4EAMf4YkyWazacuWLVq/fr2ioqKcXQ4AFGj9+vXq379/nm39+/fXkSNHFBcX56Sq4ExWq1Xnzp2Tn5+fs0sBAAAAXAo9FV3c2bNnVbt2bWVmZspqtWratGm6//77nV0WgHLmTNI5rVyzJd/2tPT03P9++s1P+R5fZLFYNLh3J/n5eF+2nRMnTqhGjRp5tl18fOLECYWEhJToeRSXzWbTyjVblHj2fJ7tRX3+ktSycUM1DQ91SL2lYe+Bv/TbH/vybS/qaxDo76cBPTvIYhim2p0xY4aSkpI0bty4ElQPAAAAwCxCRRcXEBCgmJgYpaamasOGDXrkkUdUq1YtjR071tmlAShHqlQKlIe7e4GhkiRlZedo556DhT6O6tjqioFiWWYYhsLD6uj9hd+poKWurvT8q1YO1LBruzug0tITVq+Wlv2yWSdPJxa4/0qvwe3DrzUdKL711luaMWOGli5d6rRAGQAAAHBVDH92cRaLRQ0bNlSLFi00fvx4TZ06VY899pizywJQDg3u3UmVAv1Nn1e7epB6dW5dpGNr1qyp+Pj4PNv+/vvv3H3O1KBuLXVp28L0eYZh6KaBUfL09CiFqhzHw91dNw2OkpvF/EeLDq2aqFFYHVPnvPTSS5oyZYqWLl2q3r17m24TAAAAQMkQKiIPq9Wq9P8fmgYAZnh7eWrEwB4y09fM3c1NIwZFyd3NrUjHd+7cWd9//32ebStXrlS9evXKRE+1vt0iVT2osqlzojq2Ut3a1UupIseqXT1Ivbu0MXVOUOWrNKBHe1PnPPnkk3rqqae0fPlyAkUAAADASQgVXdi0adP0008/6eDBg9q7d6/ee+89zZw5U6NHj3Z2aQDKqbC6tdS1XdF76/Xv0c5UCPfAAw9oy5Yteuyxx7Rnzx7NmzdPr7/+uh5++OHilGt3Hu7uumlQ0Xvr1a4RpF6ditZL86Lk5GTFxMQoJiZGmZmZio+PV0xMjPbv31+cku2ue/uWqlfEkNRiGBoxyFwvzUmTJunFF1/UggUL1KhRI8XHxys+Pl5nz54tbskAAAAAioFQ0YWdO3dO48ePV9OmTdWhQwe98847eu655zRr1ixnlwagHOvbta1qBFe54nEN69VWpzbNTF27bdu2WrJkib777ju1bNlSTz75pJ599lmNHz++uOXaXa3qQerTNfKKx7m7u+mmgVFyczP3VhwdHa1WrVqpVatWOnHihN588021atVKd955Z3FLtiuLxaIRA6Pk6XHlaZujOrZS3VrVTF3/1VdfVXp6uq6//nrVrFkz98/EiROLWzIAAACAYmChFhc2e/ZszZ4929llAKhg3N0vDGl+c97XyrFaCzzG28tTwwZ0N70whyQNHDhQAwcOLGmZpapbuxbavf+Ijhz7u9Bjru3eXtVMDpWWpB49eshmK2g5mLKjauVADerZUV99v67QY0JqBKunyV6aksr8cwcAAABcBT0VUSQrVm9WzK79shYSEADAP9WqVlV9uxXeW++6Pp2LtahLeWGxWC47rLdhvdrq2Kapg6tyrLYtr9E1DeoWuO9i8Gy2lyYAAACAsoNP87ii+FNntGbzDn327SqdOsOcVQCKpmvbFgoNqZFve4trwhTRpKETKnKsqpUCNbhnx3zbvb08NbyYvTTLE8MwdOO13eTn451v34Ae7VWtaiXHFwUAAADAbggVS5FhGDL+/0vjt99+q65duyowMFBBQUEaNmyYDhw4kHvsd999p+7du6tSpUoKDAzUddddpz///NNZpefx8/ptkqTmjcJMr2oKwHVdmFuvR57eegH+vhrat0vuv40VXWSLRmrcMG9vvaF9u+iqCtxL858C/Hx1ff+uebZdHVpbHVpX7F6aAAAAgCsgVHSAN998U0OGDNHBgwfVsGFDpaamavHixerevbtOnTqlV155RYMHD9aff/6psLAwZWdna+nSperWrZtOnTrl1NrjT53R73sPSpJ6dTY/9xUA11alUqAG9/pfb73h13aXbwE91yoqwzB0Q/9u8vO98JxdpZfmPzULr682zcIlST7eXho2oEeF76UJAAAAuAJCRQeYOnWq5s2bp2PHjmnbtm2Ki4tT27ZtdezYMd1xxx169NFHNW/ePB0/flzbtm3T0aNH1aZNG8XHx+vll192au3/7KVYlNVcAeBSkc0bqcnV9dShVROFh9VxdjkOF+Dnqxv6d1Pg//fSdEWDe3dSpUB/De3TWVcF+Dm7HAAAAAB2YNhYRrHUXBzed9999+m1117Ls2/lypW69tprC92/YsUKDRgwQC1atNCOHTuK1f7r877S+eS0Yp0rSVarVcmpF8739/WRxUIGDaB4rDabDMllhj0XxGq1uvS/o+X1+Z9PSZXNZpNhGArw8833GKjouAfg6rgHAFR0Af4+um/0DcU6193OtaAAd955Z75trVu3LtL+gwcPFrvd88lpOpecUuzz/+liuAgAgCuy2Wx53lMvfQxUdNwDcHXcAwCQH6GiAzRo0CDftuDg4Mvur1atmiQpOTm52O0G+PsU+1x6KQIAQA8VgHsAro57AEBFV5LsiOHPpejiML/CXuKS7i9Nnyz5Sb/vPajmjcI0cmhvh7cPAEBZMOPNT3QuOUWB/n569J6R+R4DFR33AFwd9wAAFI5QsRQ5O1Qs7pyK9FIEAOACeqjA1XEPwNVxDwCo6JhTEQWyx5yKzKUIAABzaQHcA3B13AMAkB+hYgVWnHHx9FIEAOB/6KECV8c9AFfHPQCgomNOxTLK2cOfi4O5FAEA+B/m0oKr4x6Aq+MeAIDC0Q0NueJPndHvew9Kknp1bu3kagAAAAAAAFBWESoi1y8bt0uSmjcKU43gKk6uBgAAAAAAAGUVcyqWoisNWy7pfnsb0KO9fH281T6isUPbBQAAAAAAQPlCqIhcVwX667o+nZ1dBgAAAAAAAMo4hj8DAAAAAAAAMIVQEQAAAAAAAIAphIoAAAAAAAAATCFUBAAAAAAAAGAKoSIAAAAAAAAAUwgVAQAAAAAAAJhCqAgAAAAAAADAFEJFAAAAAAAAAKYQKgIAAAAAAAAwhVARAAAAAAAAgCmEigAAAAAAAABMIVQEAAAAAAAAYAqhIgAAAAAAAABTCBUBAAAAAAAAmEKoCAAAAAAAAMAUQkUAAAAAAAAAphAqAgAAAAAAADCFUBEAAAAAAACAKYSKAAAAAAAAAEwhVAQAAAAAAABgCqEiAAAAAAAAAFMIFQEAAAAAAACYQqgIAAAAAAAAwBRCRQAAAAAAAACmECoCAAAAAAAAMIVQEQAAAAAAAIAphIoAAAAAAAAATCFUBAAAAAAAAGAKoSIAAAAAAAAAUwgVAQAAAAAAAJhCqAgAAAAAAADAFEJFAAAAAAAAAKYQKgIAAAAAAAAwhVARAAAAAAAAgCmEigAAAAAAAABMIVQEAAAAAAAAYAqhogtbsGCB2rRpo8qVK8vHx0eNGzfWrFmzZLPZnF0aAAAAAAAAyjB3ZxcA56lWrZqeeOIJNWrUSF5eXlq3bp0mTJggNzc3TZw40dnlAQAAAAAAoIwiVHRh/fr1y/M4LCxMS5Ys0erVqwkVAQAAAAAAUCiGP0OSZLPZtGXLFq1fv15RUVHOLgcAAAAAAABlGD0VXdzZs2dVu3ZtZWZmymq1atq0abr//vudXRYAAAAAAADKMEJFFxcQEKCYmBilpqZqw4YNeuSRR1SrVi2NHTvW2aUBAAAAAACgjCJUdHEWi0UNGzaUJLVo0UKJiYl67LHHCBUBAAAAAABQKOZURB5Wq1Xp6enOLgMAAAAAAABlGD0VXdi0adPUtWtXhYWFKSsrS2vXrtXMmTN1++23O7s0AAAAAAAAlGEVJlR85ZVXlJSUpEmTJqlSpUrOLqdcOHfunMaPH69jx47J29tbYWFheu655zR+/HhnlwYAAAAAAIAyrEKFikeOHNGYMWMIFYto9uzZmj17trPLAAAAAAAAQDnDnIookiNx8crIyHR2GQAAAAAAACgDKkxPRZSe9IxMzVv8vWRId906RNWDKju7JAAASl1SUpI2/LJSWzesUfK5RM2ePkke3n5q0qqDOnbt6ezygFKXlpambZvWatO6n5V05pRefvJ+uXl6q1HzSHXu0cfZ5QGlLjs7W7E7tmrD6h+V8Pcxvfj4vbK4e6pB45bq2rO/s8sDAKcr9z0VP/roIxmGoSNHjkiS6tevL8Mwcv989NFHucdmZGTo1VdfVadOnVSpUiV5e3urUaNGmjJlihISEvJd+/DhwzIMQ6GhobltRUZGys/PTzVq1NAdd9yhkydP5h4/f/58tW3bVv7+/qpatapGjRql+Pj4fNddvXq1DMNQjx49lJOToxdeeEFNmzaVj4+PqlWrpltuuUX79++37wtVAhu3xSo1PUO+Pt4KrnKVs8sBAKDUzZkzR7Vr19ayxR/r5ImjSk1JVkJCgk7EHdHP3y7SzMfv03vvvefsMoFSs2zZMoWEhGjxx+/q2JEDSjl/TmfOnNGp+OP69celevGJSXryySdls9mcXSpQKqKjo9WwYUN9+t6rOvznLiWfO6ukpCSdSTipret+1KynJuuOO+5QZiajuQC4rnIfKlavXl2dO3eWl5eXJCkyMlKdO3fO/VO9enVJ0t9//62OHTtq0qRJ2rx5sypVqqTw8HAdOXJEL730ktq0aaODBw8W2s7UqVN1++2368yZM2rYsKESExM1d+5c9e7dWxkZGXrggQc0evRoJSQkqEGDBkpOTtbHH3+sXr16KSMjo8Br2mw2DRs2TA899JDS0tLUtGlTJScn67PPPlPr1q21detW+79gJqVnZGrdlp2SpF6dWstiKfc/MgAAXNasWbM0fvx4paamFnpMVmamxo0bp1deecVxhQEO8tVXX2nIkCE6c+ZMocdYrTl65plndP/99xMsosLZsmWLevTokdtxpTBz587V9ddfr+zsbAdVBgBli2GrIJ8CQkNDdeTIER06dCi3Z+FFNptNUVFRWrNmjQYOHKg33ngj95jk5GRNnDhRH374oTp27KgNGzbknnf48GHVr19f7u7u8vX11aJFi9S//4Vu7keOHFHPnj118OBBXX/99frpp5/0+eef5+4/fPiwoqKidPjwYb399tt5VlRevXq1oqKi5OHhIS8vL33++ee69tprJV0YanXbbbfp22+/VVhYmGJjY+Xt7V2Kr9zl/bJxu75fu1VBVa7Sg2OHEyoCACq0DRs2qHPnzkU+3jAMbdy4Ue3bty/FqgDHOXr0qMLDw5Wenl7kcz799FPdcsstpVgV4DhpaWkKCwsrcMRZYZ5++mk98cQTpVgVAJRNLjGn4ooVK7RmzRo1a9ZMX375ZZ6Qzt/fX++++65iYmK0ceNGrV+/Pt+XiezsbE2bNi03MJSkevXqacqUKbr77rv19ddf6+WXX86zPzQ0VFOnTtWECRO0YsWKPKHiRVlZWZoxY0ZuoChJlSpV0ieffKK6devq4MGD+vzzz3XbbbcV63m/Pu8rnU9OK9a5kmSTTcnJF3pppKSm6/m3Fxb7WgAAlAeL5r5h6nibzaa77ntQI0ZPKKWKAMf68bsvTAWKkvTQo0/o0BlrKVUEONa2TWtNBYqS9MJLL8sWWFfu7i7x9RpABRPg76P7Rt9QrHNd4l+9xYsXS5JGjx5dYK8/Nzc3DRkyRNu2bdPq1asL7KEwduzYfNtat25dpP2FDav28PDQuHHj8m0PCAjQHXfcoVmzZmnFihXFDhXPJ6fpXHJKsc69VFp6htJU8DBuAAAqgpTz5/RHjPmpR/7YtkXd+t0gX/+AUqgKcJycnBxt/fUX0+cdPXxA+/buVo3adUuhKsCxNqz5wfQ5yefO6rct69W4RWQpVAQAZZdLhIo7d16YE3Du3LlasmRJgcf8/fffkqRjx47l2xcUFKSrrsq/QElwcPBl91erVk3ShSHWBalTp44CAwML3NekSRNJ0t69ewvcXxQB/j7FPley6XxyqmySfLy95MFv3QAAFdzJowdlzckxfV5OTrZSzp5WjRo1SqEqwHHOJJxUSvK5Yp2bdOqEwhs1tnNFgGPZbDb9feyvYp2bePK4Av397FwRAJS+kmRHLpEUJSUlSZJ27dp1xWMLmpTdz6/gNwfDMIq0v7BpKy+GjgW5uMDM+fPnCy/2CorbfVViLkUAgOv55ptvNPfN4p07tE9HDR482L4FAQ4WGxurl6cX79zu7ZrpgXtG2rUewNEyMjL0+H2jinVu8/B6epR7AICLcYlQ0d/fX5K0dOnSMvWB/+TJk4Xuu9hzMiCg+EOpij+n4oVeihJzKQIAXMfBfVf+5WNhvl21Rb//VbweXkBZcTbxdLHP/fW33Up78xM7VgM4ns1mk7u7h7Kzs0yfG7s/TjO4BwCUQ8ypqP/1CixI06ZNFRMToz/++KNMhYpxcXE6f/58gcHhxV6VjRo1Kvb17TGnInMpAgBcxVXBNeXt46v0tPyjFi7Hx9dPgVVr2G0eY8Bp3L0UXKO2TsXnnw7ocgyLRdXrNuAeQIUQ1qip9sXGmD4vJKwR9wAAl1NhQkUfnwtjwNPS8vfMGzZsmD755BO9++67uu+++3J7LjpbZmam3nvvPT344IN5ticnJ2vu3LmSlGdFabOKNy6euRQBAK7KT5Ede+jXVctNnRXZKUpVKlcqnZIAB+vYva+WLppr6pwmzdsopHZIKVUEOFbnqP6mQ8UateuqcdMWl+3oAgBlFXMqSmrQoIF2796tVatWqXHjvJNEX3fdderevbvWrFmjvn376t1331WzZs1y91utVm3evFnz5s3T1KlTFRYW5pCaPTw8NH36dDVr1kx9+/aVJJ09e1ZjxoxRYmKi6tevr5tuuqnY1y9O91XmUgQAuLJbB3ZWRESEzp49W6TjK1WqpI8/eFN167LqLSqG5NHXqfnmX3T48OEiHe/h4aEP5ryu9u3bl25hgINYrVbt+W2NNm7cWORzXpv9koYPH16KVQFA2VRhEqNbbrlFknTvvfeqadOm6tGjh3r06KGVK1fKMAx9+eWX6tSpkzZu3KjmzZsrNDRUHTp0UMuWLRUYGKhOnTppzpw5yszMdFjNHTt2VK9evdSvXz81aNBAbdu2Vc2aNbVkyRL5+/vr008/lbe3t8PqycjI1LotF1bK7tWpNYEiAMDlhIaG6ptvvil0EbZ/8vf319KlSwkUUaH4+/trxYoVRVrN3M3NTfPnzydQRIVisVj0zTffqEmTJkU6fsaMGQSKAFxWhUmNbr31Vr355ptq1aqVDh8+rDVr1mjNmjWKj4+XJAUFBWnNmjX66KOP1KdPH6WkpCg6OlqHDh1Sw4YNNXHiRK1Zs0bh4eEOq/li2Pn888/Ly8tLf/zxh3x9fXXTTTfpt99+U4cOHRxWiyRt2Bar1PQMBVW5Si0bN3Bo2wAAlBXdu3fX2rVr1aVLl0KP6datm9atW6euXbs6sDLAMa655hpt2rRJAwcOLHQ4Z4sWLbRixQrdfPPNDq4OKH3BwcH69ddfNWrUKHl6ehZ4TP369TV//nw98sgjDq4OAMoOw2az2ZxdhKtZvXq1oqKi1L17d61evdrZ5eTatH2XflwXrUG9OqpV06udXQ4AAE73+++/a968eTp69KgMw1BISIjGjBmTZxoVoCI7dOiQ5s6dq/379ysrK0vVq1fXrbfeqo4dOzJ/HFzCyZMnNXfuXP3+++9KT09XlSpVdP3116tfv36M7ALg8ggVnaCshoqSlJmZJXd3N94gAQAAAAAAUKgKs1AL7MPT08PZJQAAAAAAAKCMozsaAAAAAAAAAFMIFQEAAAAAAACYwpyKAAAAAAAAAEyhpyIAAHAJhmGoefPmWr58ucPanD17tho2bKiIiAiHtQkUhnsAro57AADsi56KAADAJRiGocTERFWqVMkh7WVnZ8vd3V2rV6/WpEmTFBMT45B2gcJwD8DVcQ8AgH3RUxEAALikrKwsPfzww2rXrp0iIiI0YsQIJSYm6tSpUwoNDdWmTZskSV9++aVatmyptLQ0rV69Ws2aNdNtt92mZs2aqU2bNrlfElevXq2mTZtq7NixioiI0Ndff+3EZwdcGfcAXB33AACUDKEiAABwSS+++KL8/Py0ZcsWxcTEqHnz5nr88ccVHBysBQsWaOTIkdqyZYsmTZqkL774Qj4+PpKk2NhYjR49Wn/88Yceeugh3Xzzzbo48GP37t267bbbFBMTo+HDhzvz6QFXxD0AV8c9AAAl4+7sAgAAAJxhyZIlOnv2rBYvXixJyszMVGhoqCSpa9euGjt2rDp16qT58+crPDw897zQ0FD16tVLkjRixAiNGzdOR48elSSFhYWpe/fujn0iQDFxD8DVcQ8AQMkQKgIAAJdks9n0+uuvq2/fvgXu3759u4KDg3O/KBbGMAwZhiFJ8vf3t3udQGnhHoCr4x4AgJJh+DMAAHBJQ4cO1ezZs5WamipJSk1NVWxsrCTpjTfeUGJionbs2KE5c+Zo/fr1uecdPnxYv/zyi6QL82xVr15dISEhjn8CQAlxD8DVcQ8AQMnQUxEAALikhx56SBkZGWrfvn1uD5OL21566SVt3rxZ1apV08cff6x//etf2rp1qySpadOm+uijj3T//ffL09NTCxcuzD0fKE+4B+DquAcAoGQM28UZZQEAACowwzCUmJioSpUqFfsaq1ev1qRJk3JX+iytc4DSwD0AV8c9AAD2xfBnAADgEqpXr67u3btr+fLlDmtz9uzZmjBhgoKCghzWJlAY7gG4Ou4BALAveioCAAAAAAAAMIWeigAAAAAAAABMIVQEAAAAAAAAYAqhIgAAAAAAAABTCBUBAAAAAAAAmEKoCAAAAAAAAMAUQkUAAAAAAAAAphAqAgAAAAAAADCFUBEAAAAAAACAKYSKAAAAAAAAAEwhVAQAAAAAAABgCqEiAAAAAAAAAFMIFQEAAAAAAACYQqgIAAAAAAAAwBRCRQAAAAAAAACmECoCAAAAAAAAMIVQEQAAAAAAAIAphIoAAAAAAAAATCFUBAAAAAAAAGAKoSIAAAAAAAAAUwgVAQAAAAAAAJhCqAgAAAAAAADAFEJFAAAAAAAAAKYQKgIAAAAAAAAwhVARAAAAAAAAgCmEigAAAAAAAABM+T+5+woyMspljgAAAABJRU5ErkJggg==", "text/plain": [ - "
" + "\"Output" ] }, - "execution_count": 2, + "execution_count": 5, "metadata": {}, "output_type": "execute_result" } @@ -288,6 +296,28 @@ { "cell_type": "markdown", "metadata": {}, + "source": [ + "### `Store`\n", + "\n", + "With `qiskit-ibm-runtime` v0.47.0 or later, you can use the [`store`](/docs/api/qiskit/circuit#store) instruction to save the result of a classical expression, if that expression will be used repeatedly. Operations are automatically parallelized, making your code significantly more efficient at runtime. \n", + "\n", + "For example, it is more natural and performant to write B[0]^B[1]^B[2]..., where B = ~A , than (~A[0])^(~A[1])^(~A[2])....  The former can be written in Qiskit as the following:\n", + "\n", + "```python\n", + "# Store the negation in temporary variable\n", + "qc.store(temp, expr.bit_not(creg))\n", + "\n", + "# Now compute parity using the stored result\n", + "parity = expr.bit_xor(\n", + " expr.bit_xor(temp[0], temp[1]), temp[2]\n", + ")\n", + "```" + ] + }, + { + "cell_type": "markdown", + "id": "7c80c5d0-a447-4590-8426-6eb33ae2d817", + "metadata": {}, "source": [ "## Next steps\n", "\n", @@ -295,14 +325,14 @@ "- Learn how to implement accurate dynamic decoupling by using [stretch](/docs/guides/stretch).\n", "- Use [circuit schedule visualization](/docs/guides/qiskit-runtime-circuit-timing) to debug and optimize your dynamic circuits.\n", "- [Execute dynamic circuits](/docs/guides/execute-dynamic-circuits).\n", - "- Not all functions are compatible with dynamic circuits. Check the feature compatibility section for [Sampler](/docs/guides/sampler-options#feature-compatibility) or [Executor](/docs/guides/executor-options#feature-compatibility) for details. \n", + "- Not all functions are compatible with dynamic circuits. Check the feature compatibility section for [Sampler](/docs/guides/sampler-options#feature-compatibility) or [Executor](/docs/guides/executor-options#feature-compatibility) for details.\n", "" ] } ], "metadata": { "kernelspec": { - "display_name": "Python 3 (ipykernel)", + "display_name": "Python 3", "language": "python", "name": "python3" }, @@ -316,7 +346,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.12.3" + "version": "3" } }, "nbformat": 4, From 50a7f903db73fcef53318bdbb634e6e402a04c91 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Fri, 22 May 2026 12:42:02 -0500 Subject: [PATCH 08/28] tox e fix --- docs/guides/classical-feedforward-and-control-flow.ipynb | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/guides/classical-feedforward-and-control-flow.ipynb b/docs/guides/classical-feedforward-and-control-flow.ipynb index 104ffda206b..b5ee900251d 100644 --- a/docs/guides/classical-feedforward-and-control-flow.ipynb +++ b/docs/guides/classical-feedforward-and-control-flow.ipynb @@ -295,11 +295,12 @@ }, { "cell_type": "markdown", + "id": "02ef1510-6daf-4a58-b4bb-b5bdbe774c43", "metadata": {}, "source": [ "### `Store`\n", "\n", - "With `qiskit-ibm-runtime` v0.47.0 or later, you can use the [`store`](/docs/api/qiskit/circuit#store) instruction to save the result of a classical expression, if that expression will be used repeatedly. Operations are automatically parallelized, making your code significantly more efficient at runtime. \n", + "With `qiskit-ibm-runtime` v0.47.0 or later, you can use the [`store`](/docs/api/qiskit/circuit#store) instruction to save the result of a classical expression, if that expression will be used repeatedly. Operations are automatically parallelized, making your code significantly more efficient at runtime.\n", "\n", "For example, it is more natural and performant to write B[0]^B[1]^B[2]..., where B = ~A , than (~A[0])^(~A[1])^(~A[2])....  The former can be written in Qiskit as the following:\n", "\n", From 165405aed5bcbbcf0375617838e8cf94065e517f Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Fri, 22 May 2026 13:05:44 -0500 Subject: [PATCH 09/28] put the table back how it was --- docs/guides/estimator-input-output.ipynb | 17 +++------------- docs/guides/qpu-information.ipynb | 25 +++++++++++++++++++++++- 2 files changed, 27 insertions(+), 15 deletions(-) diff --git a/docs/guides/estimator-input-output.ipynb b/docs/guides/estimator-input-output.ipynb index db3d978eb85..8ab60189156 100644 --- a/docs/guides/estimator-input-output.ipynb +++ b/docs/guides/estimator-input-output.ipynb @@ -2,7 +2,6 @@ "cells": [ { "cell_type": "markdown", - "id": "4a99b08b-5a4e-4c2c-ba72-b932d8510bf2", "metadata": {}, "source": [ "---\n", @@ -16,7 +15,6 @@ }, { "cell_type": "markdown", - "id": "0f04fa5d-aae1-4a05-832b-be5e0f03f5b2", "metadata": { "tags": [ "version-info" @@ -46,7 +44,6 @@ }, { "cell_type": "markdown", - "id": "cd5b8a3a-fc21-4eaf-923c-1576db19d569", "metadata": {}, "source": [ "This page gives an overview of the inputs and outputs of the Qiskit Runtime Estimator primitive, which executes workloads on IBM Quantum® compute resources. Estimator lets you efficiently define vectorized workloads by using a data structure called a [**Primitive Unified Bloc (PUB)**](/docs/guides/primitive-input-output#pubs). They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method for the Estimator primitive, which executes the defined workload as a job. Then, after the job has completed, the results are returned in a format that is dependent on both the PUBs used as well as the runtime options specified from the primitive." @@ -54,7 +51,6 @@ }, { "cell_type": "markdown", - "id": "d27b242b-5865-48cc-9052-577982a0b922", "metadata": {}, "source": [ "## Inputs\n", @@ -83,7 +79,6 @@ }, { "cell_type": "markdown", - "id": "6b4da5a2-093a-4069-99ba-11e2f9c1f9a1", "metadata": {}, "source": [ "---\n", @@ -94,7 +89,6 @@ { "cell_type": "code", "execution_count": 1, - "id": "f4b2c3b6-80bd-4d84-9b16-8bdb7502e06b", "metadata": {}, "outputs": [], "source": [ @@ -170,7 +164,6 @@ }, { "cell_type": "markdown", - "id": "246bd44d-8f3d-40b6-b1c1-795cc3533b32", "metadata": {}, "source": [ "## Outputs\n", @@ -223,7 +216,6 @@ { "cell_type": "code", "execution_count": 2, - "id": "defbebd5-f09f-4596-aff0-ae88cbf2555c", "metadata": {}, "outputs": [ { @@ -252,7 +244,7 @@ ], "source": [ "print(\n", - " f\"The result of the submitted job had {len(result)} PUB and has a value:\\n {result}\\n\"\n", + " f\"The result of the submitted job had {len(result)} PUBs and has a value:\\n {result}\\n\"\n", ")\n", "print(\n", " f\"The associated PubResult of this job has the following data bins:\\n {result[0].data}\\n\"\n", @@ -270,7 +262,6 @@ }, { "cell_type": "markdown", - "id": "33af7b71-0562-4bb6-8098-8ddebb206032", "metadata": {}, "source": [ "#### How the Estimator primitive calculates error\n", @@ -292,7 +283,6 @@ }, { "cell_type": "markdown", - "id": "cc748369-c7db-4d3d-a2a6-7973fa5c37fe", "metadata": {}, "source": [ "## Result metadata\n", @@ -307,7 +297,6 @@ { "cell_type": "code", "execution_count": 3, - "id": "b740caa1-bbdb-421c-aae8-e389a8e55aa1", "metadata": {}, "outputs": [ { @@ -344,7 +333,7 @@ "metadata": { "celltoolbar": "Raw Cell Format", "kernelspec": { - "display_name": "Python 3", + "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, @@ -358,7 +347,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3" + "version": "3.12.3" } }, "nbformat": 4, diff --git a/docs/guides/qpu-information.ipynb b/docs/guides/qpu-information.ipynb index bbcdc173929..c6314e440bc 100644 --- a/docs/guides/qpu-information.ipynb +++ b/docs/guides/qpu-information.ipynb @@ -330,6 +330,29 @@ "id": "42d83190-198e-4696-acb6-9cc5e57c49ab", "metadata": {}, "source": [ + "\n", + "### Supported instructions\n", + "\n", + "Each [processor family](/docs/guides/processor-types) natively supports a limited set of instructions. This set includes single- and two-qubit gates, as well as non-unitary operations such as measure and reset. Every gate in the circuit must be translated (by the transpiler) to the elements of a QPU's supported instruction set before it can run on the QPU.\n", + "\n", + "You can view the supported instruction sets for a QPU with Qiskit. The IBM Quantum Platform Compute resources page lists only the supported unitary gates (basis gates) for a QPU.\n", + "\n", + "\n", + " \n", + " \n", + "\n", + " \n", + "\n", + " \n", + " \n", + "\n", + " Navigate to the [Compute resources](https://quantum.cloud.ibm.com/computers) page to view a table of all QPUs, then click the name of any QPU to open its detailed information card. The basis gates for that QPU are listed in the Details section.\n", + " \n", + "\n", + "\n", + "\n", + "### Table of supported instructions\n", + "\n", "\n", "### Supported instructions\n", "\n", @@ -357,7 +380,7 @@ "| :--- | :--- |\n", "| Single-qubit gates | [`RZ`](/docs/api/qiskit/qiskit.circuit.library.RZGate), [`SX`](/docs/api/qiskit/qiskit.circuit.library.SXGate), [`X`](/docs/api/qiskit/qiskit.circuit.library.XGate), [`ID`](/docs/api/qiskit/qiskit.circuit.library.IGate), [`delay`](/docs/api/qiskit/circuit#qiskit.circuit.Delay) |\n", "| Two-qubit gates | [`CZ`](/docs/api/qiskit/qiskit.circuit.library.CZGate), [`ECR`](/docs/api/qiskit/qiskit.circuit.library.ECRGate)|\n", - "| Fractional gates | [`RX`](/docs/api/qiskit/qiskit.circuit.library.RXGate) (single-qubit), [`RZZ`](/docs/api/qiskit/qiskit.circuit.library.RZZGate) (two-qubit) | |\n", + "| Fractional gates | [`RX`](/docs/api/qiskit/qiskit.circuit.library.RXGate) (single-qubit), [`RZZ`](/docs/api/qiskit/qiskit.circuit.library.RZZGate) (two-qubit) |\n", "| Non-unitary instructions | [`measure`](/docs/api/qiskit/circuit#qiskit.circuit.Measure), [`reset`](/docs/api/qiskit/circuit#qiskit.circuit.Reset), [`measure_*`](/docs/guides/execute-dynamic-circuits#midcircuit), [`delay`](/docs/api/qiskit/circuit#delay) |\n", "| Control flow | [`if_else`](/docs/api/qiskit/qiskit.circuit.IfElseOp) (classical feedforward) |" ] From 82fb53da967b64b09ebdac19d740f38ae6b4d61e Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Fri, 22 May 2026 13:43:31 -0500 Subject: [PATCH 10/28] use old file --- docs/guides/qpu-information.ipynb | 23 ----------------------- 1 file changed, 23 deletions(-) diff --git a/docs/guides/qpu-information.ipynb b/docs/guides/qpu-information.ipynb index c6314e440bc..635c9c439e6 100644 --- a/docs/guides/qpu-information.ipynb +++ b/docs/guides/qpu-information.ipynb @@ -330,29 +330,6 @@ "id": "42d83190-198e-4696-acb6-9cc5e57c49ab", "metadata": {}, "source": [ - "\n", - "### Supported instructions\n", - "\n", - "Each [processor family](/docs/guides/processor-types) natively supports a limited set of instructions. This set includes single- and two-qubit gates, as well as non-unitary operations such as measure and reset. Every gate in the circuit must be translated (by the transpiler) to the elements of a QPU's supported instruction set before it can run on the QPU.\n", - "\n", - "You can view the supported instruction sets for a QPU with Qiskit. The IBM Quantum Platform Compute resources page lists only the supported unitary gates (basis gates) for a QPU.\n", - "\n", - "\n", - " \n", - " \n", - "\n", - " \n", - "\n", - " \n", - " \n", - "\n", - " Navigate to the [Compute resources](https://quantum.cloud.ibm.com/computers) page to view a table of all QPUs, then click the name of any QPU to open its detailed information card. The basis gates for that QPU are listed in the Details section.\n", - " \n", - "\n", - "\n", - "\n", - "### Table of supported instructions\n", - "\n", "\n", "### Supported instructions\n", "\n", From 2e51826f0e7f58721a998e33b755ad9893b48802 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Fri, 22 May 2026 13:58:15 -0500 Subject: [PATCH 11/28] tox -e fix --- docs/guides/estimator-input-output.ipynb | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/guides/estimator-input-output.ipynb b/docs/guides/estimator-input-output.ipynb index 8ab60189156..6a25f69327a 100644 --- a/docs/guides/estimator-input-output.ipynb +++ b/docs/guides/estimator-input-output.ipynb @@ -2,6 +2,7 @@ "cells": [ { "cell_type": "markdown", + "id": "4090580a-d66d-4536-90c5-a73af464acde", "metadata": {}, "source": [ "---\n", @@ -15,6 +16,7 @@ }, { "cell_type": "markdown", + "id": "8d490cfa-93da-4a89-a8fe-4348b5f595f4", "metadata": { "tags": [ "version-info" @@ -44,6 +46,7 @@ }, { "cell_type": "markdown", + "id": "77cd1dcb-f8c3-427b-9d8b-300728aca3cf", "metadata": {}, "source": [ "This page gives an overview of the inputs and outputs of the Qiskit Runtime Estimator primitive, which executes workloads on IBM Quantum® compute resources. Estimator lets you efficiently define vectorized workloads by using a data structure called a [**Primitive Unified Bloc (PUB)**](/docs/guides/primitive-input-output#pubs). They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method for the Estimator primitive, which executes the defined workload as a job. Then, after the job has completed, the results are returned in a format that is dependent on both the PUBs used as well as the runtime options specified from the primitive." @@ -51,6 +54,7 @@ }, { "cell_type": "markdown", + "id": "94bdb06e-f34b-4317-90fd-35ce5dad8485", "metadata": {}, "source": [ "## Inputs\n", @@ -79,6 +83,7 @@ }, { "cell_type": "markdown", + "id": "4fbb28df-0bdd-4658-8e4e-fc3ca78085f5", "metadata": {}, "source": [ "---\n", @@ -89,6 +94,7 @@ { "cell_type": "code", "execution_count": 1, + "id": "664202df-59f2-4b82-a5d3-64af1ca1d430", "metadata": {}, "outputs": [], "source": [ @@ -164,6 +170,7 @@ }, { "cell_type": "markdown", + "id": "ad2125e0-fc09-487a-baa9-1d2df07b8cb4", "metadata": {}, "source": [ "## Outputs\n", @@ -216,6 +223,7 @@ { "cell_type": "code", "execution_count": 2, + "id": "4965576a-7f79-4257-a0e6-e09ae0d947ed", "metadata": {}, "outputs": [ { @@ -262,6 +270,7 @@ }, { "cell_type": "markdown", + "id": "e1165790-ddc1-4ed0-b64e-6732c551e839", "metadata": {}, "source": [ "#### How the Estimator primitive calculates error\n", @@ -283,6 +292,7 @@ }, { "cell_type": "markdown", + "id": "429b9196-4383-4920-9b75-b8ec03af4d39", "metadata": {}, "source": [ "## Result metadata\n", @@ -297,6 +307,7 @@ { "cell_type": "code", "execution_count": 3, + "id": "1eb676a5-7d2c-4047-a332-9a3b8de70a65", "metadata": {}, "outputs": [ { @@ -333,7 +344,7 @@ "metadata": { "celltoolbar": "Raw Cell Format", "kernelspec": { - "display_name": "Python 3 (ipykernel)", + "display_name": "Python 3", "language": "python", "name": "python3" }, @@ -347,7 +358,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.12.3" + "version": "3" } }, "nbformat": 4, From 73ed890f3518a32de0203238ff1180041d6ce8d5 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Fri, 22 May 2026 15:20:36 -0500 Subject: [PATCH 12/28] review comments --- ...assical-feedforward-and-control-flow.ipynb | 5 ++--- docs/guides/execute-dynamic-circuits.ipynb | 22 +++++++++++++++++++ 2 files changed, 24 insertions(+), 3 deletions(-) diff --git a/docs/guides/classical-feedforward-and-control-flow.ipynb b/docs/guides/classical-feedforward-and-control-flow.ipynb index b5ee900251d..2dfad73f49c 100644 --- a/docs/guides/classical-feedforward-and-control-flow.ipynb +++ b/docs/guides/classical-feedforward-and-control-flow.ipynb @@ -300,9 +300,9 @@ "source": [ "### `Store`\n", "\n", - "With `qiskit-ibm-runtime` v0.47.0 or later, you can use the [`store`](/docs/api/qiskit/circuit#store) instruction to save the result of a classical expression, if that expression will be used repeatedly. Operations are automatically parallelized, making your code significantly more efficient at runtime.\n", + "You can use the [`store`](/docs/api/qiskit/circuit#store) instruction to save the result of a classical expression, if that expression will be used repeatedly. Operations are automatically parallelized, making your code significantly more efficient at runtime.\n", "\n", - "For example, it is more natural and performant to write B[0]^B[1]^B[2]..., where B = ~A , than (~A[0])^(~A[1])^(~A[2])....  The former can be written in Qiskit as the following:\n", + "For example, it is more natural and performant to write $B[0]^B[1]^B[2]...,$ where $B = ~A$, than $(~A[0])^(~A[1])^(~A[2])....$  The former can be written in Qiskit as the following:\n", "\n", "```python\n", "# Store the negation in temporary variable\n", @@ -326,7 +326,6 @@ "- Learn how to implement accurate dynamic decoupling by using [stretch](/docs/guides/stretch).\n", "- Use [circuit schedule visualization](/docs/guides/qiskit-runtime-circuit-timing) to debug and optimize your dynamic circuits.\n", "- [Execute dynamic circuits](/docs/guides/execute-dynamic-circuits).\n", - "- Not all functions are compatible with dynamic circuits. Check the feature compatibility section for [Sampler](/docs/guides/sampler-options#feature-compatibility) or [Executor](/docs/guides/executor-options#feature-compatibility) for details.\n", "" ] } diff --git a/docs/guides/execute-dynamic-circuits.ipynb b/docs/guides/execute-dynamic-circuits.ipynb index 1a608b6aaea..a83e0c2cf43 100644 --- a/docs/guides/execute-dynamic-circuits.ipynb +++ b/docs/guides/execute-dynamic-circuits.ipynb @@ -191,6 +191,27 @@ "" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## `Store`\n", + "\n", + "With `qiskit-ibm-runtime` v0.47.0 or later, you can use the [`store`](/docs/api/qiskit/circuit#store) instruction to save the result of a classical expression, if that expression will be used repeatedly. Operations are automatically parallelized, making your code significantly more efficient at runtime.\n", + "\n", + "For example, it is more natural and performant to write $B[0]^B[1]^B[2]...,$ where $B = ~A$, than $(~A[0])^(~A[1])^(~A[2])....$  The former can be written in Qiskit as the following:\n", + "\n", + "```python\n", + "# Store the negation in temporary variable\n", + "qc.store(temp, expr.bit_not(creg))\n", + "\n", + "# Now compute parity using the stored result\n", + "parity = expr.bit_xor(\n", + " expr.bit_xor(temp[0], temp[1]), temp[2]\n", + ")\n", + "```" + ] + }, { "cell_type": "markdown", "id": "88942666-966d-4eb6-81b5-2a9e1265fe0a", @@ -380,6 +401,7 @@ "- Learn how to implement accurate dynamic decoupling by using [stretch](/docs/guides/stretch).\n", "- Review the [classical feedforward and control flow](/docs/guides/classical-feedforward-and-control-flow) guide.\n", "- Use [circuit schedule visualization](/docs/guides/qiskit-runtime-circuit-timing) to debug and optimize your dynamic circuits.\n", + "- Not all functions are compatible with dynamic circuits. Check the feature compatibility section for [Sampler](/docs/guides/sampler-options#feature-compatibility) or [Executor](/docs/guides/executor-options#feature-compatibility) for details.\n", "" ] } From af324c2094d04d0baecbfbbf2de1652a504347f7 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Fri, 22 May 2026 16:13:59 -0500 Subject: [PATCH 13/28] run and save --- docs/guides/execute-dynamic-circuits.ipynb | 23 ++++------------------ 1 file changed, 4 insertions(+), 19 deletions(-) diff --git a/docs/guides/execute-dynamic-circuits.ipynb b/docs/guides/execute-dynamic-circuits.ipynb index a83e0c2cf43..dd5a860b8b2 100644 --- a/docs/guides/execute-dynamic-circuits.ipynb +++ b/docs/guides/execute-dynamic-circuits.ipynb @@ -2,7 +2,6 @@ "cells": [ { "cell_type": "markdown", - "id": "a9095a6c-e720-4b4c-9eca-4b5234186400", "metadata": {}, "source": [ "---\n", @@ -16,7 +15,6 @@ }, { "cell_type": "markdown", - "id": "0b425be3-b17e-4e41-b393-63b0a58c054f", "metadata": { "tags": [ "version-info" @@ -46,7 +44,6 @@ }, { "cell_type": "markdown", - "id": "d59d8dd9-8c61-49ab-b43c-b34f87ebcce2", "metadata": {}, "source": [ "Dynamic circuits are powerful tools with which you can measure qubits in the middle of a quantum circuit execution and then perform classical logic operations within the circuit, based on the outcome of those mid-circuit measurements. This process is also known as _classical feedforward_. While these are early days of understanding how best to take advantage of dynamic circuits, the quantum research community has already identified a number of use cases, such as the following:\n", @@ -66,7 +63,6 @@ }, { "cell_type": "markdown", - "id": "c1f79012-05ce-4854-908b-59ca6b472508", "metadata": {}, "source": [ "## Find backends that support dynamic circuits\n", @@ -83,7 +79,6 @@ { "cell_type": "code", "execution_count": 1, - "id": "0cd6971f-cb04-4ff9-89a8-7638fdcca0d1", "metadata": { "tags": [ "remove-cell" @@ -100,14 +95,13 @@ { "cell_type": "code", "execution_count": 2, - "id": "517e5e4d-3f48-4c2b-9084-222ed3cd2de7", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ - "[, , , , ]\n" + "[, , , , ]\n" ] } ], @@ -121,7 +115,6 @@ }, { "cell_type": "markdown", - "id": "5992c1cd-f28a-4f40-b3f9-09374c9f61ca", "metadata": {}, "source": [ "\n", @@ -141,7 +134,6 @@ { "cell_type": "code", "execution_count": 3, - "id": "8b1b8786-21bd-4a9c-b868-36f497738f10", "metadata": {}, "outputs": [ { @@ -180,7 +172,6 @@ }, { "cell_type": "markdown", - "id": "983e4d2b-7049-4be1-b628-eac093f96585", "metadata": {}, "source": [ "\n", @@ -214,7 +205,6 @@ }, { "cell_type": "markdown", - "id": "88942666-966d-4eb6-81b5-2a9e1265fe0a", "metadata": {}, "source": [ "## Full example\n", @@ -225,14 +215,13 @@ { "cell_type": "code", "execution_count": 4, - "id": "800ddb06-3b1a-4b9e-a92e-c782e4a3d412", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ - ">>> Job ID: d82864vtjchs73bnokf0 (DONE)\n" + ">>> Job ID: d88cakp789is7391vq0g (DONE)\n" ] } ], @@ -280,7 +269,6 @@ }, { "cell_type": "markdown", - "id": "e2ee6fb4-7b6d-4ee6-a625-0f92e40bd7f9", "metadata": {}, "source": [ "## Qiskit Runtime limitations\n", @@ -363,7 +351,6 @@ }, { "cell_type": "markdown", - "id": "fb3c25a4-bde2-4d34-bbd2-670091a33968", "metadata": {}, "source": [ "## Use dynamic circuits with Estimator\n", @@ -382,7 +369,6 @@ }, { "cell_type": "markdown", - "id": "5adac953-3305-4383-b522-901ecbd9bd31", "metadata": {}, "source": [ "## Restrictions\n", @@ -392,7 +378,6 @@ }, { "cell_type": "markdown", - "id": "b5b33172-d1b6-418c-b06d-12e4c2a75738", "metadata": {}, "source": [ "## Next steps\n", @@ -408,7 +393,7 @@ ], "metadata": { "kernelspec": { - "display_name": "Python 3", + "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, @@ -422,7 +407,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3" + "version": "3.12.3" } }, "nbformat": 4, From 32cae01f102f3bf9e6830abb4251b381de232a9b Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Fri, 22 May 2026 20:15:52 -0400 Subject: [PATCH 14/28] tox -e fix --- docs/guides/execute-dynamic-circuits.ipynb | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/guides/execute-dynamic-circuits.ipynb b/docs/guides/execute-dynamic-circuits.ipynb index dd5a860b8b2..b6c047d570c 100644 --- a/docs/guides/execute-dynamic-circuits.ipynb +++ b/docs/guides/execute-dynamic-circuits.ipynb @@ -2,6 +2,7 @@ "cells": [ { "cell_type": "markdown", + "id": "1b1f23ad-a044-44ea-8ee1-1432c2e0bf24", "metadata": {}, "source": [ "---\n", @@ -15,6 +16,7 @@ }, { "cell_type": "markdown", + "id": "e64af0ba-6625-4b38-8662-749ded869329", "metadata": { "tags": [ "version-info" @@ -44,6 +46,7 @@ }, { "cell_type": "markdown", + "id": "5353bc57-fafb-4d1e-b03c-02efe902d0c7", "metadata": {}, "source": [ "Dynamic circuits are powerful tools with which you can measure qubits in the middle of a quantum circuit execution and then perform classical logic operations within the circuit, based on the outcome of those mid-circuit measurements. This process is also known as _classical feedforward_. While these are early days of understanding how best to take advantage of dynamic circuits, the quantum research community has already identified a number of use cases, such as the following:\n", @@ -63,6 +66,7 @@ }, { "cell_type": "markdown", + "id": "0948daa8-3de7-41be-86a8-f702682996a2", "metadata": {}, "source": [ "## Find backends that support dynamic circuits\n", @@ -79,6 +83,7 @@ { "cell_type": "code", "execution_count": 1, + "id": "fa54f6c9-f3c3-4edf-883d-3568421a3313", "metadata": { "tags": [ "remove-cell" @@ -95,6 +100,7 @@ { "cell_type": "code", "execution_count": 2, + "id": "99c9878f-d02e-4156-8688-b46ef6e4b00b", "metadata": {}, "outputs": [ { @@ -115,6 +121,7 @@ }, { "cell_type": "markdown", + "id": "e57cde09-b97b-4861-bdcb-89483cae6eb4", "metadata": {}, "source": [ "\n", @@ -134,6 +141,7 @@ { "cell_type": "code", "execution_count": 3, + "id": "286576ea-53ca-4ace-9c92-3bb4ad51f770", "metadata": {}, "outputs": [ { @@ -172,6 +180,7 @@ }, { "cell_type": "markdown", + "id": "30b3dbf6-e579-4a67-93dd-662129c445a9", "metadata": {}, "source": [ "\n", @@ -184,6 +193,7 @@ }, { "cell_type": "markdown", + "id": "56f98db3-99b3-49d4-b7a9-3d9fd8278890", "metadata": {}, "source": [ "## `Store`\n", @@ -205,6 +215,7 @@ }, { "cell_type": "markdown", + "id": "0de5ec21-2b09-4692-82d3-58a469b249e4", "metadata": {}, "source": [ "## Full example\n", @@ -215,6 +226,7 @@ { "cell_type": "code", "execution_count": 4, + "id": "9c8c0e71-1b30-44d8-85a8-a4224c9dc642", "metadata": {}, "outputs": [ { @@ -269,6 +281,7 @@ }, { "cell_type": "markdown", + "id": "13e45505-3967-42fa-90cf-a362e29f8cc1", "metadata": {}, "source": [ "## Qiskit Runtime limitations\n", @@ -351,6 +364,7 @@ }, { "cell_type": "markdown", + "id": "b9cd39a7-ba82-4f7d-9641-8f6475880e9f", "metadata": {}, "source": [ "## Use dynamic circuits with Estimator\n", @@ -369,6 +383,7 @@ }, { "cell_type": "markdown", + "id": "746fd5a9-4968-4bbe-85ad-55258277ca29", "metadata": {}, "source": [ "## Restrictions\n", @@ -378,6 +393,7 @@ }, { "cell_type": "markdown", + "id": "d00af942-d88c-466a-9947-76a91e39edd6", "metadata": {}, "source": [ "## Next steps\n", @@ -393,7 +409,7 @@ ], "metadata": { "kernelspec": { - "display_name": "Python 3 (ipykernel)", + "display_name": "Python 3", "language": "python", "name": "python3" }, @@ -407,7 +423,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.12.3" + "version": "3" } }, "nbformat": 4, From ce98d94f350ebee1ac592db5abf967b7e8535aed Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Tue, 26 May 2026 08:32:25 -0500 Subject: [PATCH 15/28] Update docs/guides/classical-feedforward-and-control-flow.ipynb Co-authored-by: Fran Cabrera --- docs/guides/classical-feedforward-and-control-flow.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/classical-feedforward-and-control-flow.ipynb b/docs/guides/classical-feedforward-and-control-flow.ipynb index 2dfad73f49c..0191ca7fd48 100644 --- a/docs/guides/classical-feedforward-and-control-flow.ipynb +++ b/docs/guides/classical-feedforward-and-control-flow.ipynb @@ -302,7 +302,7 @@ "\n", "You can use the [`store`](/docs/api/qiskit/circuit#store) instruction to save the result of a classical expression, if that expression will be used repeatedly. Operations are automatically parallelized, making your code significantly more efficient at runtime.\n", "\n", - "For example, it is more natural and performant to write $B[0]^B[1]^B[2]...,$ where $B = ~A$, than $(~A[0])^(~A[1])^(~A[2])....$  The former can be written in Qiskit as the following:\n", + "For example, it is more natural and more efficient at runtime to write $B[0] \oplus B[1] \oplus B[2] \ldots$, where $B = \neg A$, than $(\neg A[0]) \oplus (\neg A[1]) \oplus (\neg A[2]) \ldots$ The former computes the negation in a single parallel step before the XOR chain, rather than evaluating each negation sequentially inside the expression. In Qiskit, this is written as follows::\n", "\n", "```python\n", "# Store the negation in temporary variable\n", From 9d4f0261225aa577359207742393d404b008c810 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Tue, 26 May 2026 09:10:32 -0500 Subject: [PATCH 16/28] fran comments --- docs/guides/estimator-input-output.ipynb | 15 ++------------- docs/guides/execute-dynamic-circuits.ipynb | 20 ++------------------ 2 files changed, 4 insertions(+), 31 deletions(-) diff --git a/docs/guides/estimator-input-output.ipynb b/docs/guides/estimator-input-output.ipynb index 6a25f69327a..8ab60189156 100644 --- a/docs/guides/estimator-input-output.ipynb +++ b/docs/guides/estimator-input-output.ipynb @@ -2,7 +2,6 @@ "cells": [ { "cell_type": "markdown", - "id": "4090580a-d66d-4536-90c5-a73af464acde", "metadata": {}, "source": [ "---\n", @@ -16,7 +15,6 @@ }, { "cell_type": "markdown", - "id": "8d490cfa-93da-4a89-a8fe-4348b5f595f4", "metadata": { "tags": [ "version-info" @@ -46,7 +44,6 @@ }, { "cell_type": "markdown", - "id": "77cd1dcb-f8c3-427b-9d8b-300728aca3cf", "metadata": {}, "source": [ "This page gives an overview of the inputs and outputs of the Qiskit Runtime Estimator primitive, which executes workloads on IBM Quantum® compute resources. Estimator lets you efficiently define vectorized workloads by using a data structure called a [**Primitive Unified Bloc (PUB)**](/docs/guides/primitive-input-output#pubs). They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method for the Estimator primitive, which executes the defined workload as a job. Then, after the job has completed, the results are returned in a format that is dependent on both the PUBs used as well as the runtime options specified from the primitive." @@ -54,7 +51,6 @@ }, { "cell_type": "markdown", - "id": "94bdb06e-f34b-4317-90fd-35ce5dad8485", "metadata": {}, "source": [ "## Inputs\n", @@ -83,7 +79,6 @@ }, { "cell_type": "markdown", - "id": "4fbb28df-0bdd-4658-8e4e-fc3ca78085f5", "metadata": {}, "source": [ "---\n", @@ -94,7 +89,6 @@ { "cell_type": "code", "execution_count": 1, - "id": "664202df-59f2-4b82-a5d3-64af1ca1d430", "metadata": {}, "outputs": [], "source": [ @@ -170,7 +164,6 @@ }, { "cell_type": "markdown", - "id": "ad2125e0-fc09-487a-baa9-1d2df07b8cb4", "metadata": {}, "source": [ "## Outputs\n", @@ -223,7 +216,6 @@ { "cell_type": "code", "execution_count": 2, - "id": "4965576a-7f79-4257-a0e6-e09ae0d947ed", "metadata": {}, "outputs": [ { @@ -270,7 +262,6 @@ }, { "cell_type": "markdown", - "id": "e1165790-ddc1-4ed0-b64e-6732c551e839", "metadata": {}, "source": [ "#### How the Estimator primitive calculates error\n", @@ -292,7 +283,6 @@ }, { "cell_type": "markdown", - "id": "429b9196-4383-4920-9b75-b8ec03af4d39", "metadata": {}, "source": [ "## Result metadata\n", @@ -307,7 +297,6 @@ { "cell_type": "code", "execution_count": 3, - "id": "1eb676a5-7d2c-4047-a332-9a3b8de70a65", "metadata": {}, "outputs": [ { @@ -344,7 +333,7 @@ "metadata": { "celltoolbar": "Raw Cell Format", "kernelspec": { - "display_name": "Python 3", + "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, @@ -358,7 +347,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3" + "version": "3.12.3" } }, "nbformat": 4, diff --git a/docs/guides/execute-dynamic-circuits.ipynb b/docs/guides/execute-dynamic-circuits.ipynb index b6c047d570c..dd5a860b8b2 100644 --- a/docs/guides/execute-dynamic-circuits.ipynb +++ b/docs/guides/execute-dynamic-circuits.ipynb @@ -2,7 +2,6 @@ "cells": [ { "cell_type": "markdown", - "id": "1b1f23ad-a044-44ea-8ee1-1432c2e0bf24", "metadata": {}, "source": [ "---\n", @@ -16,7 +15,6 @@ }, { "cell_type": "markdown", - "id": "e64af0ba-6625-4b38-8662-749ded869329", "metadata": { "tags": [ "version-info" @@ -46,7 +44,6 @@ }, { "cell_type": "markdown", - "id": "5353bc57-fafb-4d1e-b03c-02efe902d0c7", "metadata": {}, "source": [ "Dynamic circuits are powerful tools with which you can measure qubits in the middle of a quantum circuit execution and then perform classical logic operations within the circuit, based on the outcome of those mid-circuit measurements. This process is also known as _classical feedforward_. While these are early days of understanding how best to take advantage of dynamic circuits, the quantum research community has already identified a number of use cases, such as the following:\n", @@ -66,7 +63,6 @@ }, { "cell_type": "markdown", - "id": "0948daa8-3de7-41be-86a8-f702682996a2", "metadata": {}, "source": [ "## Find backends that support dynamic circuits\n", @@ -83,7 +79,6 @@ { "cell_type": "code", "execution_count": 1, - "id": "fa54f6c9-f3c3-4edf-883d-3568421a3313", "metadata": { "tags": [ "remove-cell" @@ -100,7 +95,6 @@ { "cell_type": "code", "execution_count": 2, - "id": "99c9878f-d02e-4156-8688-b46ef6e4b00b", "metadata": {}, "outputs": [ { @@ -121,7 +115,6 @@ }, { "cell_type": "markdown", - "id": "e57cde09-b97b-4861-bdcb-89483cae6eb4", "metadata": {}, "source": [ "\n", @@ -141,7 +134,6 @@ { "cell_type": "code", "execution_count": 3, - "id": "286576ea-53ca-4ace-9c92-3bb4ad51f770", "metadata": {}, "outputs": [ { @@ -180,7 +172,6 @@ }, { "cell_type": "markdown", - "id": "30b3dbf6-e579-4a67-93dd-662129c445a9", "metadata": {}, "source": [ "\n", @@ -193,7 +184,6 @@ }, { "cell_type": "markdown", - "id": "56f98db3-99b3-49d4-b7a9-3d9fd8278890", "metadata": {}, "source": [ "## `Store`\n", @@ -215,7 +205,6 @@ }, { "cell_type": "markdown", - "id": "0de5ec21-2b09-4692-82d3-58a469b249e4", "metadata": {}, "source": [ "## Full example\n", @@ -226,7 +215,6 @@ { "cell_type": "code", "execution_count": 4, - "id": "9c8c0e71-1b30-44d8-85a8-a4224c9dc642", "metadata": {}, "outputs": [ { @@ -281,7 +269,6 @@ }, { "cell_type": "markdown", - "id": "13e45505-3967-42fa-90cf-a362e29f8cc1", "metadata": {}, "source": [ "## Qiskit Runtime limitations\n", @@ -364,7 +351,6 @@ }, { "cell_type": "markdown", - "id": "b9cd39a7-ba82-4f7d-9641-8f6475880e9f", "metadata": {}, "source": [ "## Use dynamic circuits with Estimator\n", @@ -383,7 +369,6 @@ }, { "cell_type": "markdown", - "id": "746fd5a9-4968-4bbe-85ad-55258277ca29", "metadata": {}, "source": [ "## Restrictions\n", @@ -393,7 +378,6 @@ }, { "cell_type": "markdown", - "id": "d00af942-d88c-466a-9947-76a91e39edd6", "metadata": {}, "source": [ "## Next steps\n", @@ -409,7 +393,7 @@ ], "metadata": { "kernelspec": { - "display_name": "Python 3", + "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, @@ -423,7 +407,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3" + "version": "3.12.3" } }, "nbformat": 4, From 96817903bef9016c66c600b052324ac284c04a2a Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Tue, 26 May 2026 09:54:18 -0500 Subject: [PATCH 17/28] fix latex --- docs/guides/classical-feedforward-and-control-flow.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/classical-feedforward-and-control-flow.ipynb b/docs/guides/classical-feedforward-and-control-flow.ipynb index 0191ca7fd48..bb07118c3cf 100644 --- a/docs/guides/classical-feedforward-and-control-flow.ipynb +++ b/docs/guides/classical-feedforward-and-control-flow.ipynb @@ -302,7 +302,7 @@ "\n", "You can use the [`store`](/docs/api/qiskit/circuit#store) instruction to save the result of a classical expression, if that expression will be used repeatedly. Operations are automatically parallelized, making your code significantly more efficient at runtime.\n", "\n", - "For example, it is more natural and more efficient at runtime to write $B[0] \oplus B[1] \oplus B[2] \ldots$, where $B = \neg A$, than $(\neg A[0]) \oplus (\neg A[1]) \oplus (\neg A[2]) \ldots$ The former computes the negation in a single parallel step before the XOR chain, rather than evaluating each negation sequentially inside the expression. In Qiskit, this is written as follows::\n", + "For example, it is more natural and performant to write $B[0] \\oplus B[1] \\oplus B[2] \\ldots$, where $B = \\neg A$, than $(\\neg A[0]) \\oplus (\\neg A[1]) \\oplus (\\neg A[2]) \\ldots$.  The former can be written in Qiskit as follows:\n", "\n", "```python\n", "# Store the negation in temporary variable\n", From e76690ecb69a4f60b6c181ea701b8ff22189fd09 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Tue, 26 May 2026 09:57:46 -0500 Subject: [PATCH 18/28] fix latex --- docs/guides/classical-feedforward-and-control-flow.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/classical-feedforward-and-control-flow.ipynb b/docs/guides/classical-feedforward-and-control-flow.ipynb index bb07118c3cf..43cc9637eeb 100644 --- a/docs/guides/classical-feedforward-and-control-flow.ipynb +++ b/docs/guides/classical-feedforward-and-control-flow.ipynb @@ -302,7 +302,7 @@ "\n", "You can use the [`store`](/docs/api/qiskit/circuit#store) instruction to save the result of a classical expression, if that expression will be used repeatedly. Operations are automatically parallelized, making your code significantly more efficient at runtime.\n", "\n", - "For example, it is more natural and performant to write $B[0] \\oplus B[1] \\oplus B[2] \\ldots$, where $B = \\neg A$, than $(\\neg A[0]) \\oplus (\\neg A[1]) \\oplus (\\neg A[2]) \\ldots$.  The former can be written in Qiskit as follows:\n", + "For example, it is more natural and more efficient at runtime to write $B[0] \\oplus B[1] \\oplus B[2] \\ldots$, where $B = \\neg A$, than $(\\neg A[0]) \\oplus (\\neg A[1]) \\oplus (\\neg A[2]) \\ldots$.  The former computes the negation in a single parallel step before the XOR chain, instead of evaluating each negation sequentially inside the expression. The former can be written in Qiskit as follows:\n", "\n", "```python\n", "# Store the negation in temporary variable\n", From 0401c69ac95b39393aa8d122d5d993a0b0832e92 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Tue, 26 May 2026 10:04:41 -0500 Subject: [PATCH 19/28] tox -e fix --- docs/guides/estimator-input-output.ipynb | 15 +++++++++++++-- docs/guides/execute-dynamic-circuits.ipynb | 20 ++++++++++++++++++-- 2 files changed, 31 insertions(+), 4 deletions(-) diff --git a/docs/guides/estimator-input-output.ipynb b/docs/guides/estimator-input-output.ipynb index 8ab60189156..fb612ab62c2 100644 --- a/docs/guides/estimator-input-output.ipynb +++ b/docs/guides/estimator-input-output.ipynb @@ -2,6 +2,7 @@ "cells": [ { "cell_type": "markdown", + "id": "37526300-f96b-488a-b810-2b060ae83950", "metadata": {}, "source": [ "---\n", @@ -15,6 +16,7 @@ }, { "cell_type": "markdown", + "id": "3011fb2c-6fcb-4ae1-8e46-765ee1ae6636", "metadata": { "tags": [ "version-info" @@ -44,6 +46,7 @@ }, { "cell_type": "markdown", + "id": "b6174794-6257-4eae-96ba-75dc2dc31fcf", "metadata": {}, "source": [ "This page gives an overview of the inputs and outputs of the Qiskit Runtime Estimator primitive, which executes workloads on IBM Quantum® compute resources. Estimator lets you efficiently define vectorized workloads by using a data structure called a [**Primitive Unified Bloc (PUB)**](/docs/guides/primitive-input-output#pubs). They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method for the Estimator primitive, which executes the defined workload as a job. Then, after the job has completed, the results are returned in a format that is dependent on both the PUBs used as well as the runtime options specified from the primitive." @@ -51,6 +54,7 @@ }, { "cell_type": "markdown", + "id": "52aae5a4-342f-487f-9d31-903f7464358d", "metadata": {}, "source": [ "## Inputs\n", @@ -79,6 +83,7 @@ }, { "cell_type": "markdown", + "id": "f2425f71-9b64-45af-b0e0-eb35116673c1", "metadata": {}, "source": [ "---\n", @@ -89,6 +94,7 @@ { "cell_type": "code", "execution_count": 1, + "id": "3ae8df20-0f50-41aa-a5fd-ea88e224a8c6", "metadata": {}, "outputs": [], "source": [ @@ -164,6 +170,7 @@ }, { "cell_type": "markdown", + "id": "5705efc0-bfca-4b99-a346-5078465def49", "metadata": {}, "source": [ "## Outputs\n", @@ -216,6 +223,7 @@ { "cell_type": "code", "execution_count": 2, + "id": "d8630f01-c2ad-4a96-af85-431be251eeae", "metadata": {}, "outputs": [ { @@ -262,6 +270,7 @@ }, { "cell_type": "markdown", + "id": "a262acc8-65dc-4b81-a6c1-cee317618013", "metadata": {}, "source": [ "#### How the Estimator primitive calculates error\n", @@ -283,6 +292,7 @@ }, { "cell_type": "markdown", + "id": "a5a67e84-de86-4e99-809d-d90a0022608f", "metadata": {}, "source": [ "## Result metadata\n", @@ -297,6 +307,7 @@ { "cell_type": "code", "execution_count": 3, + "id": "01abcd04-5401-469b-8199-978d43ba0f16", "metadata": {}, "outputs": [ { @@ -333,7 +344,7 @@ "metadata": { "celltoolbar": "Raw Cell Format", "kernelspec": { - "display_name": "Python 3 (ipykernel)", + "display_name": "Python 3", "language": "python", "name": "python3" }, @@ -347,7 +358,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.12.3" + "version": "3" } }, "nbformat": 4, diff --git a/docs/guides/execute-dynamic-circuits.ipynb b/docs/guides/execute-dynamic-circuits.ipynb index dd5a860b8b2..c3cf3e3f481 100644 --- a/docs/guides/execute-dynamic-circuits.ipynb +++ b/docs/guides/execute-dynamic-circuits.ipynb @@ -2,6 +2,7 @@ "cells": [ { "cell_type": "markdown", + "id": "20c786a8-0de6-4b3a-9ed0-ea8906f94a84", "metadata": {}, "source": [ "---\n", @@ -15,6 +16,7 @@ }, { "cell_type": "markdown", + "id": "9e98bf3f-1b28-447f-83e3-c759b18675fc", "metadata": { "tags": [ "version-info" @@ -44,6 +46,7 @@ }, { "cell_type": "markdown", + "id": "98058581-56c6-4f7b-969d-e2cc6a4009c4", "metadata": {}, "source": [ "Dynamic circuits are powerful tools with which you can measure qubits in the middle of a quantum circuit execution and then perform classical logic operations within the circuit, based on the outcome of those mid-circuit measurements. This process is also known as _classical feedforward_. While these are early days of understanding how best to take advantage of dynamic circuits, the quantum research community has already identified a number of use cases, such as the following:\n", @@ -63,6 +66,7 @@ }, { "cell_type": "markdown", + "id": "7033b0bb-e4e2-430c-85fa-58ab56d249d1", "metadata": {}, "source": [ "## Find backends that support dynamic circuits\n", @@ -79,6 +83,7 @@ { "cell_type": "code", "execution_count": 1, + "id": "1c0dafd8-8381-4f28-bf85-29f4b590a509", "metadata": { "tags": [ "remove-cell" @@ -95,6 +100,7 @@ { "cell_type": "code", "execution_count": 2, + "id": "a8554b54-3468-48ae-bb36-dc43ee9d666f", "metadata": {}, "outputs": [ { @@ -115,6 +121,7 @@ }, { "cell_type": "markdown", + "id": "895ef8ef-8e83-4756-98a2-1f6da361c93e", "metadata": {}, "source": [ "\n", @@ -134,6 +141,7 @@ { "cell_type": "code", "execution_count": 3, + "id": "f149f3c5-3215-4669-9aa2-cad8e5214325", "metadata": {}, "outputs": [ { @@ -172,6 +180,7 @@ }, { "cell_type": "markdown", + "id": "9a903437-4b2b-4693-aad6-dea278191950", "metadata": {}, "source": [ "\n", @@ -184,6 +193,7 @@ }, { "cell_type": "markdown", + "id": "716b1a90-b442-4442-95b8-3e4f42c7d221", "metadata": {}, "source": [ "## `Store`\n", @@ -205,6 +215,7 @@ }, { "cell_type": "markdown", + "id": "5b0cd063-8212-4cf9-8bfd-7c21c1462ad7", "metadata": {}, "source": [ "## Full example\n", @@ -215,6 +226,7 @@ { "cell_type": "code", "execution_count": 4, + "id": "db772f08-ca76-4699-b78f-46e5d401bd4d", "metadata": {}, "outputs": [ { @@ -269,6 +281,7 @@ }, { "cell_type": "markdown", + "id": "1fd4a39c-2884-400d-9f20-c043d2eb07cb", "metadata": {}, "source": [ "## Qiskit Runtime limitations\n", @@ -351,6 +364,7 @@ }, { "cell_type": "markdown", + "id": "aedf4cf0-9430-4703-a41e-e062733083d6", "metadata": {}, "source": [ "## Use dynamic circuits with Estimator\n", @@ -369,6 +383,7 @@ }, { "cell_type": "markdown", + "id": "453976ed-3ef0-4b56-96ad-fa8247bb075a", "metadata": {}, "source": [ "## Restrictions\n", @@ -378,6 +393,7 @@ }, { "cell_type": "markdown", + "id": "1b5e2d54-6e5f-4629-80e7-95cffdd7d31d", "metadata": {}, "source": [ "## Next steps\n", @@ -393,7 +409,7 @@ ], "metadata": { "kernelspec": { - "display_name": "Python 3 (ipykernel)", + "display_name": "Python 3", "language": "python", "name": "python3" }, @@ -407,7 +423,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.12.3" + "version": "3" } }, "nbformat": 4, From 9fb44e2d1aa6b3d0a46075c8c296d67bcefad97a Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 27 May 2026 09:48:42 -0500 Subject: [PATCH 20/28] Code change from fran --- ...assical-feedforward-and-control-flow.ipynb | 69 +++++++++++++------ docs/guides/estimator-input-output.ipynb | 15 +--- docs/guides/execute-dynamic-circuits.ipynb | 20 +----- 3 files changed, 51 insertions(+), 53 deletions(-) diff --git a/docs/guides/classical-feedforward-and-control-flow.ipynb b/docs/guides/classical-feedforward-and-control-flow.ipynb index 43cc9637eeb..7a14511952b 100644 --- a/docs/guides/classical-feedforward-and-control-flow.ipynb +++ b/docs/guides/classical-feedforward-and-control-flow.ipynb @@ -2,7 +2,6 @@ "cells": [ { "cell_type": "markdown", - "id": "943cf52c-41c8-4a2b-bf1d-6df8a90a6353", "metadata": {}, "source": [ "---\n", @@ -16,7 +15,6 @@ }, { "cell_type": "markdown", - "id": "b1d96290-2e64-43aa-bae9-c74b8529894d", "metadata": { "tags": [ "version-info" @@ -45,7 +43,6 @@ }, { "cell_type": "markdown", - "id": "85a4d698-ee2a-4b3d-9331-1b91eea49338", "metadata": {}, "source": [ "Dynamic circuits are powerful tools with which you can measure qubits in the middle of a quantum circuit execution and then perform classical logic operations within the circuit, based on the outcome of those mid-circuit measurements. This process is also known as _classical feedforward_. While these are early days of understanding how best to take advantage of dynamic circuits, the quantum research community has already identified a number of use cases, such as the following:\n", @@ -57,7 +54,6 @@ }, { "cell_type": "markdown", - "id": "5d846edf-fc09-4808-bd62-3a8cfdcc1585", "metadata": {}, "source": [ "## `if` statement\n", @@ -70,7 +66,6 @@ { "cell_type": "code", "execution_count": 1, - "id": "60924bfa-50ed-4d9d-a17b-9d64f2cc053f", "metadata": {}, "outputs": [ { @@ -105,7 +100,6 @@ }, { "cell_type": "markdown", - "id": "bef3f447-7282-4de9-9410-6b671e9902c3", "metadata": {}, "source": [ "The `with` statement can be given an assignment target which is itself a context manager that can be stored and subsequently used to create an else block, which is executed whenever the contents of the `if` block are *not* executed.\n", @@ -116,7 +110,6 @@ { "cell_type": "code", "execution_count": 2, - "id": "20f0640a-a3f7-41b3-aada-b66bc89b0555", "metadata": {}, "outputs": [ { @@ -152,7 +145,6 @@ }, { "cell_type": "markdown", - "id": "f0f00f48-a1f2-40cc-b5f5-9a122d8dd24e", "metadata": {}, "source": [ "In addition to conditioning on a single classical bit, it's also possible to condition on the value of a classical register composed of multiple bits.\n", @@ -163,7 +155,6 @@ { "cell_type": "code", "execution_count": 3, - "id": "98e8f552-4169-42a3-8182-e14e9ffb59e2", "metadata": {}, "outputs": [ { @@ -198,7 +189,6 @@ }, { "cell_type": "markdown", - "id": "ef8fd422-6bab-46c9-9455-c79244cf1fb7", "metadata": {}, "source": [ "## Classical expressions\n", @@ -214,7 +204,6 @@ { "cell_type": "code", "execution_count": 4, - "id": "7581ac2f-53e9-43d0-bad0-2c80790172e1", "metadata": {}, "outputs": [], "source": [ @@ -275,7 +264,6 @@ { "cell_type": "code", "execution_count": 5, - "id": "d0f0abdb-50d5-408d-a704-a1a555acdd85", "metadata": {}, "outputs": [ { @@ -295,29 +283,66 @@ }, { "cell_type": "markdown", - "id": "02ef1510-6daf-4a58-b4bb-b5bdbe774c43", "metadata": {}, "source": [ "### `Store`\n", "\n", "You can use the [`store`](/docs/api/qiskit/circuit#store) instruction to save the result of a classical expression, if that expression will be used repeatedly. Operations are automatically parallelized, making your code significantly more efficient at runtime.\n", "\n", - "For example, it is more natural and more efficient at runtime to write $B[0] \\oplus B[1] \\oplus B[2] \\ldots$, where $B = \\neg A$, than $(\\neg A[0]) \\oplus (\\neg A[1]) \\oplus (\\neg A[2]) \\ldots$.  The former computes the negation in a single parallel step before the XOR chain, instead of evaluating each negation sequentially inside the expression. The former can be written in Qiskit as follows:\n", + "For example, it is more natural and more efficient at runtime to write $B[0] \\oplus B[1] \\oplus B[2] \\ldots$, where $B = \\neg A$, than $(\\neg A[0]) \\oplus (\\neg A[1]) \\oplus (\\neg A[2]) \\ldots$.  The former computes the negation in a single parallel step before the XOR chain, instead of evaluating each negation sequentially inside the expression. The former can be written in Qiskit as follows:" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [ + { + "data": { + "image/png": "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P/xQw4YNU1RUlEwmk8aNG6fFixdX6Rpyc3M1fPhwTZgwQVOmTFGXLl302Wef6Xe/+522bdtWbv+VK1dq2bJlmjNnjpKTk629RIsWLVLnzp11ww03qGfPntq1a5ckaeHCherXr5/uuusutWrVSjfeeKP27t2rESNGKDExUTfffLNyc3MllfbCjBw5Un379tV1112noUOH6pdffqmw9p49eyomJqZK13m5efPm6bvvvtOqVavUuHFjLV++XCdPntRTTz1ld/9x48Zp//79Sk5OtgalgwcPavDgwerYsaOSkpL06quvWvc3mUz661//qs6dOysuLk6ffPKJZs6cqQ4dOqhFixZav369pNKgVLt2bf3pT39SUlKSWrdurTVr1tgrQZJ00003qVatWpKkxo0bKyoqSseOHXPqewAArnRN3kMDAEb3+uuva/78+dq0aZN1mM/DDz+sHj166J///KcsFoseeugh/f3vf9fkyZMlSUePHtW6det09uxZxcXFKScnR5s2bVJGRoZatmypBx54wHquEydOaPv27frll190ww03qFu3brrxxhvL1fHTTz/Z9FLExcXpp59+qtI1hIaGat26dTbrEhIStGPHDrv733LLLRo2bJiSk5M1adIkSdLmzZu1ePFibdy4UQEBAdq0aZPuvvtu7dmzR5K0bds27d69W7GxsRozZoyGDh2qr7/+Wg0aNNCQIUP0zjvv6A9/+IOk0iFy33//vaKiovT73/9eTzzxhLW3yZUee+wxm2Wz2ay33367wv1ff/11TZo0ydrbVVxcrLvuukv/+te/dN111+n8+fPq0qWLOnfurI4dO0oq/d5+8803+vLLLzV8+HC9+uqr2r59uz744ANNnjzZGhjPnDmjxMREzZ07V1u3btWwYcOsvS6VWbNmjXJycqyvBwDuRKABAC/xySefaMuWLdbelgsXLsjX19e6/fbbb5evr6/q1Kmj+Ph4DRkyRCaTSY0aNVJkZKTS0tKsw4sefPBBmUwm1atXT7fddpvWrFljN9C423//+1/t2rXL5jlhp06d0oULFyRJXbt2VWxsrCSpQ4cOKiwsVIMGDSRJHTt21MGDB63HDR48WFFRUZJKw+Ftt91WU5fhkP3792vPnj268847revOnTunvXv3WgPG6NGjJZVec15ennXfTp062Vyz2WzWfffdJ6l0ls/o6Gjt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", + "text/plain": [ + "
" + ] + }, + "execution_count": 1, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from qiskit.circuit import QuantumCircuit, QuantumRegister, ClassicalRegister\n", + "from qiskit.circuit.classical import expr, types\n", "\n", - "```python\n", - "# Store the negation in temporary variable\n", + "qregs = QuantumRegister(4, \"q\")\n", + "creg = ClassicalRegister(3, \"c\")\n", + "qc = QuantumCircuit(qregs, creg)\n", + "\n", + "# Declare temp as a Uint(3) variable to hold the negation of creg\n", + "temp = qc.add_var(\"temp\", expr.lift(0, types.Uint(3)))\n", + "\n", + "qc.h([0, 1, 2])\n", + "qc.measure([0, 1, 2], creg)\n", + "\n", + "# Store bit-NOT of the full 3-bit register in a single parallel step\n", "qc.store(temp, expr.bit_not(creg))\n", "\n", - "# Now compute parity using the stored result\n", + "# Compute parity of the stored result using bit-indexed XOR\n", "parity = expr.bit_xor(\n", - " expr.bit_xor(temp[0], temp[1]), temp[2]\n", + " expr.bit_xor(expr.index(temp, 0), expr.index(temp, 1)),\n", + " expr.index(temp, 2),\n", ")\n", - "```" + "\n", + "# Flip q3 if parity of ~creg is 1\n", + "with qc.if_test(parity):\n", + " qc.x(3)\n", + "\n", + "qc.measure([0, 1, 2], creg)\n", + "\n", + "qc.draw(\"mpl\")" ] }, { "cell_type": "markdown", - "id": "7c80c5d0-a447-4590-8426-6eb33ae2d817", "metadata": {}, "source": [ "## Next steps\n", @@ -332,7 +357,7 @@ ], "metadata": { "kernelspec": { - "display_name": "Python 3", + "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, @@ -346,7 +371,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3" + "version": "3.12.3" } }, "nbformat": 4, diff --git a/docs/guides/estimator-input-output.ipynb b/docs/guides/estimator-input-output.ipynb index fb612ab62c2..8ab60189156 100644 --- a/docs/guides/estimator-input-output.ipynb +++ b/docs/guides/estimator-input-output.ipynb @@ -2,7 +2,6 @@ "cells": [ { "cell_type": "markdown", - "id": "37526300-f96b-488a-b810-2b060ae83950", "metadata": {}, "source": [ "---\n", @@ -16,7 +15,6 @@ }, { "cell_type": "markdown", - "id": "3011fb2c-6fcb-4ae1-8e46-765ee1ae6636", "metadata": { "tags": [ "version-info" @@ -46,7 +44,6 @@ }, { "cell_type": "markdown", - "id": "b6174794-6257-4eae-96ba-75dc2dc31fcf", "metadata": {}, "source": [ "This page gives an overview of the inputs and outputs of the Qiskit Runtime Estimator primitive, which executes workloads on IBM Quantum® compute resources. Estimator lets you efficiently define vectorized workloads by using a data structure called a [**Primitive Unified Bloc (PUB)**](/docs/guides/primitive-input-output#pubs). They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method for the Estimator primitive, which executes the defined workload as a job. Then, after the job has completed, the results are returned in a format that is dependent on both the PUBs used as well as the runtime options specified from the primitive." @@ -54,7 +51,6 @@ }, { "cell_type": "markdown", - "id": "52aae5a4-342f-487f-9d31-903f7464358d", "metadata": {}, "source": [ "## Inputs\n", @@ -83,7 +79,6 @@ }, { "cell_type": "markdown", - "id": "f2425f71-9b64-45af-b0e0-eb35116673c1", "metadata": {}, "source": [ "---\n", @@ -94,7 +89,6 @@ { "cell_type": "code", "execution_count": 1, - "id": "3ae8df20-0f50-41aa-a5fd-ea88e224a8c6", "metadata": {}, "outputs": [], "source": [ @@ -170,7 +164,6 @@ }, { "cell_type": "markdown", - "id": "5705efc0-bfca-4b99-a346-5078465def49", "metadata": {}, "source": [ "## Outputs\n", @@ -223,7 +216,6 @@ { "cell_type": "code", "execution_count": 2, - "id": "d8630f01-c2ad-4a96-af85-431be251eeae", "metadata": {}, "outputs": [ { @@ -270,7 +262,6 @@ }, { "cell_type": "markdown", - "id": "a262acc8-65dc-4b81-a6c1-cee317618013", "metadata": {}, "source": [ "#### How the Estimator primitive calculates error\n", @@ -292,7 +283,6 @@ }, { "cell_type": "markdown", - "id": "a5a67e84-de86-4e99-809d-d90a0022608f", "metadata": {}, "source": [ "## Result metadata\n", @@ -307,7 +297,6 @@ { "cell_type": "code", "execution_count": 3, - "id": "01abcd04-5401-469b-8199-978d43ba0f16", "metadata": {}, "outputs": [ { @@ -344,7 +333,7 @@ "metadata": { "celltoolbar": "Raw Cell Format", "kernelspec": { - "display_name": "Python 3", + "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, @@ -358,7 +347,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3" + "version": "3.12.3" } }, "nbformat": 4, diff --git a/docs/guides/execute-dynamic-circuits.ipynb b/docs/guides/execute-dynamic-circuits.ipynb index c3cf3e3f481..dd5a860b8b2 100644 --- a/docs/guides/execute-dynamic-circuits.ipynb +++ b/docs/guides/execute-dynamic-circuits.ipynb @@ -2,7 +2,6 @@ "cells": [ { "cell_type": "markdown", - "id": "20c786a8-0de6-4b3a-9ed0-ea8906f94a84", "metadata": {}, "source": [ "---\n", @@ -16,7 +15,6 @@ }, { "cell_type": "markdown", - "id": "9e98bf3f-1b28-447f-83e3-c759b18675fc", "metadata": { "tags": [ "version-info" @@ -46,7 +44,6 @@ }, { "cell_type": "markdown", - "id": "98058581-56c6-4f7b-969d-e2cc6a4009c4", "metadata": {}, "source": [ "Dynamic circuits are powerful tools with which you can measure qubits in the middle of a quantum circuit execution and then perform classical logic operations within the circuit, based on the outcome of those mid-circuit measurements. This process is also known as _classical feedforward_. While these are early days of understanding how best to take advantage of dynamic circuits, the quantum research community has already identified a number of use cases, such as the following:\n", @@ -66,7 +63,6 @@ }, { "cell_type": "markdown", - "id": "7033b0bb-e4e2-430c-85fa-58ab56d249d1", "metadata": {}, "source": [ "## Find backends that support dynamic circuits\n", @@ -83,7 +79,6 @@ { "cell_type": "code", "execution_count": 1, - "id": "1c0dafd8-8381-4f28-bf85-29f4b590a509", "metadata": { "tags": [ "remove-cell" @@ -100,7 +95,6 @@ { "cell_type": "code", "execution_count": 2, - "id": "a8554b54-3468-48ae-bb36-dc43ee9d666f", "metadata": {}, "outputs": [ { @@ -121,7 +115,6 @@ }, { "cell_type": "markdown", - "id": "895ef8ef-8e83-4756-98a2-1f6da361c93e", "metadata": {}, "source": [ "\n", @@ -141,7 +134,6 @@ { "cell_type": "code", "execution_count": 3, - "id": "f149f3c5-3215-4669-9aa2-cad8e5214325", "metadata": {}, "outputs": [ { @@ -180,7 +172,6 @@ }, { "cell_type": "markdown", - "id": "9a903437-4b2b-4693-aad6-dea278191950", "metadata": {}, "source": [ "\n", @@ -193,7 +184,6 @@ }, { "cell_type": "markdown", - "id": "716b1a90-b442-4442-95b8-3e4f42c7d221", "metadata": {}, "source": [ "## `Store`\n", @@ -215,7 +205,6 @@ }, { "cell_type": "markdown", - "id": "5b0cd063-8212-4cf9-8bfd-7c21c1462ad7", "metadata": {}, "source": [ "## Full example\n", @@ -226,7 +215,6 @@ { "cell_type": "code", "execution_count": 4, - "id": "db772f08-ca76-4699-b78f-46e5d401bd4d", "metadata": {}, "outputs": [ { @@ -281,7 +269,6 @@ }, { "cell_type": "markdown", - "id": "1fd4a39c-2884-400d-9f20-c043d2eb07cb", "metadata": {}, "source": [ "## Qiskit Runtime limitations\n", @@ -364,7 +351,6 @@ }, { "cell_type": "markdown", - "id": "aedf4cf0-9430-4703-a41e-e062733083d6", "metadata": {}, "source": [ "## Use dynamic circuits with Estimator\n", @@ -383,7 +369,6 @@ }, { "cell_type": "markdown", - "id": "453976ed-3ef0-4b56-96ad-fa8247bb075a", "metadata": {}, "source": [ "## Restrictions\n", @@ -393,7 +378,6 @@ }, { "cell_type": "markdown", - "id": "1b5e2d54-6e5f-4629-80e7-95cffdd7d31d", "metadata": {}, "source": [ "## Next steps\n", @@ -409,7 +393,7 @@ ], "metadata": { "kernelspec": { - "display_name": "Python 3", + "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, @@ -423,7 +407,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3" + "version": "3.12.3" } }, "nbformat": 4, From a83f21664ea4aaed3a5e79d3bbbfa4959619bd2c Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 27 May 2026 09:56:43 -0500 Subject: [PATCH 21/28] clarifications --- .../classical-feedforward-and-control-flow.ipynb | 5 ++++- docs/guides/execute-dynamic-circuits.ipynb | 10 ++++++---- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/docs/guides/classical-feedforward-and-control-flow.ipynb b/docs/guides/classical-feedforward-and-control-flow.ipynb index 7a14511952b..a765f80d66c 100644 --- a/docs/guides/classical-feedforward-and-control-flow.ipynb +++ b/docs/guides/classical-feedforward-and-control-flow.ipynb @@ -285,11 +285,14 @@ "cell_type": "markdown", "metadata": {}, "source": [ + "\n", "### `Store`\n", "\n", "You can use the [`store`](/docs/api/qiskit/circuit#store) instruction to save the result of a classical expression, if that expression will be used repeatedly. Operations are automatically parallelized, making your code significantly more efficient at runtime.\n", "\n", - "For example, it is more natural and more efficient at runtime to write $B[0] \\oplus B[1] \\oplus B[2] \\ldots$, where $B = \\neg A$, than $(\\neg A[0]) \\oplus (\\neg A[1]) \\oplus (\\neg A[2]) \\ldots$.  The former computes the negation in a single parallel step before the XOR chain, instead of evaluating each negation sequentially inside the expression. The former can be written in Qiskit as follows:" + "For example, it is more natural and more efficient at runtime to write $B[0] \\oplus B[1] \\oplus B[2] \\ldots$, where $B = \\neg A$, than $(\\neg A[0]) \\oplus (\\neg A[1]) \\oplus (\\neg A[2]) \\ldots$.  The former computes the negation in a single parallel step before the XOR chain, instead of evaluating each negation sequentially inside the expression.\n", + "\n", + "Full example: " ] }, { diff --git a/docs/guides/execute-dynamic-circuits.ipynb b/docs/guides/execute-dynamic-circuits.ipynb index dd5a860b8b2..94c2317098d 100644 --- a/docs/guides/execute-dynamic-circuits.ipynb +++ b/docs/guides/execute-dynamic-circuits.ipynb @@ -188,19 +188,21 @@ "source": [ "## `Store`\n", "\n", - "With `qiskit-ibm-runtime` v0.47.0 or later, you can use the [`store`](/docs/api/qiskit/circuit#store) instruction to save the result of a classical expression, if that expression will be used repeatedly. Operations are automatically parallelized, making your code significantly more efficient at runtime.\n", + "With qiskit-ibm-runtime version 0.47.0 or later, you can use the [`store`](/docs/api/qiskit/circuit#store) instruction to save the result of a classical expression, if that expression will be used repeatedly. Operations are automatically parallelized, making your code significantly more efficient at runtime.\n", "\n", - "For example, it is more natural and performant to write $B[0]^B[1]^B[2]...,$ where $B = ~A$, than $(~A[0])^(~A[1])^(~A[2])....$  The former can be written in Qiskit as the following:\n", + "For example, it is more natural and more efficient at runtime to write $B[0] \\oplus B[1] \\oplus B[2] \\ldots$, where $B = \\neg A$, than $(\\neg A[0]) \\oplus (\\neg A[1]) \\oplus (\\neg A[2]) \\ldots$.  The former computes the negation in a single parallel step before the XOR chain, instead of evaluating each negation sequentially inside the expression. The former can be written in Qiskit as follows:\n", "\n", "```python\n", "# Store the negation in temporary variable\n", "qc.store(temp, expr.bit_not(creg))\n", "\n", - "# Now compute parity using the stored result\n", + "# Compute parity using the stored result\n", "parity = expr.bit_xor(\n", " expr.bit_xor(temp[0], temp[1]), temp[2]\n", ")\n", - "```" + "```\n", + "\n", + "For a full example, see the [Classical feedforward and control flow](/docs/guides/classical-feedforward-and-control-flow#store) guide. " ] }, { From 648f3734759d4e146d7133d5dd23b30365fc1cf2 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 27 May 2026 10:02:54 -0500 Subject: [PATCH 22/28] typo --- docs/guides/classical-feedforward-and-control-flow.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/classical-feedforward-and-control-flow.ipynb b/docs/guides/classical-feedforward-and-control-flow.ipynb index a765f80d66c..09c8610a3de 100644 --- a/docs/guides/classical-feedforward-and-control-flow.ipynb +++ b/docs/guides/classical-feedforward-and-control-flow.ipynb @@ -285,7 +285,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "\n", + "\n", "### `Store`\n", "\n", "You can use the [`store`](/docs/api/qiskit/circuit#store) instruction to save the result of a classical expression, if that expression will be used repeatedly. Operations are automatically parallelized, making your code significantly more efficient at runtime.\n", From 4ef9cf7b26d5b103ae4dbec01b5f6614ebabc855 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 27 May 2026 10:18:06 -0500 Subject: [PATCH 23/28] code typo --- docs/guides/classical-feedforward-and-control-flow.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/classical-feedforward-and-control-flow.ipynb b/docs/guides/classical-feedforward-and-control-flow.ipynb index 09c8610a3de..4367088e346 100644 --- a/docs/guides/classical-feedforward-and-control-flow.ipynb +++ b/docs/guides/classical-feedforward-and-control-flow.ipynb @@ -285,7 +285,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "\n", + "\n", "### `Store`\n", "\n", "You can use the [`store`](/docs/api/qiskit/circuit#store) instruction to save the result of a classical expression, if that expression will be used repeatedly. Operations are automatically parallelized, making your code significantly more efficient at runtime.\n", From 22aca76f9aebdaa5a059958a27ebac63afed862b Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 27 May 2026 10:36:20 -0500 Subject: [PATCH 24/28] tox e fix --- ...assical-feedforward-and-control-flow.ipynb | 28 +++++++++++++----- docs/guides/estimator-input-output.ipynb | 15 ++++++++-- docs/guides/execute-dynamic-circuits.ipynb | 22 ++++++++++++-- ...9b8504e-88a9-4e39-b1a4-cd5d72407396-0.avif | Bin 0 -> 3788 bytes 4 files changed, 53 insertions(+), 12 deletions(-) create mode 100644 public/docs/images/guides/classical-feedforward-and-control-flow/extracted-outputs/e9b8504e-88a9-4e39-b1a4-cd5d72407396-0.avif diff --git a/docs/guides/classical-feedforward-and-control-flow.ipynb b/docs/guides/classical-feedforward-and-control-flow.ipynb index 4367088e346..de45e255614 100644 --- a/docs/guides/classical-feedforward-and-control-flow.ipynb +++ b/docs/guides/classical-feedforward-and-control-flow.ipynb @@ -2,6 +2,7 @@ "cells": [ { "cell_type": "markdown", + "id": "295e2195-484b-49a7-83e5-fdc27d322eee", "metadata": {}, "source": [ "---\n", @@ -15,6 +16,7 @@ }, { "cell_type": "markdown", + "id": "3cea13bc-a7ca-42ba-9ce5-c59833457e68", "metadata": { "tags": [ "version-info" @@ -43,6 +45,7 @@ }, { "cell_type": "markdown", + "id": "04715d79-3a52-4dd6-864d-eb50a7840909", "metadata": {}, "source": [ "Dynamic circuits are powerful tools with which you can measure qubits in the middle of a quantum circuit execution and then perform classical logic operations within the circuit, based on the outcome of those mid-circuit measurements. This process is also known as _classical feedforward_. While these are early days of understanding how best to take advantage of dynamic circuits, the quantum research community has already identified a number of use cases, such as the following:\n", @@ -54,6 +57,7 @@ }, { "cell_type": "markdown", + "id": "5da510ac-1c5d-494b-b709-8d1030bfb92a", "metadata": {}, "source": [ "## `if` statement\n", @@ -66,6 +70,7 @@ { "cell_type": "code", "execution_count": 1, + "id": "7dc7f56a-25a1-486f-838d-a50ea6cd4beb", "metadata": {}, "outputs": [ { @@ -100,6 +105,7 @@ }, { "cell_type": "markdown", + "id": "02a3925d-f619-4759-bfa7-4d1ac0207737", "metadata": {}, "source": [ "The `with` statement can be given an assignment target which is itself a context manager that can be stored and subsequently used to create an else block, which is executed whenever the contents of the `if` block are *not* executed.\n", @@ -110,6 +116,7 @@ { "cell_type": "code", "execution_count": 2, + "id": "320e383c-9d4a-4f68-9a4c-b986cab38195", "metadata": {}, "outputs": [ { @@ -145,6 +152,7 @@ }, { "cell_type": "markdown", + "id": "1e39751a-0eb2-4c33-8f57-a3a77e0c7caa", "metadata": {}, "source": [ "In addition to conditioning on a single classical bit, it's also possible to condition on the value of a classical register composed of multiple bits.\n", @@ -155,6 +163,7 @@ { "cell_type": "code", "execution_count": 3, + "id": "b46cb721-073b-4ac1-a411-5c716d11e879", "metadata": {}, "outputs": [ { @@ -189,6 +198,7 @@ }, { "cell_type": "markdown", + "id": "cf56f5fa-da42-418d-96e8-c3e0620dc0d7", "metadata": {}, "source": [ "## Classical expressions\n", @@ -204,6 +214,7 @@ { "cell_type": "code", "execution_count": 4, + "id": "755b92e4-8a47-4a88-96ab-157a9d487465", "metadata": {}, "outputs": [], "source": [ @@ -264,6 +275,7 @@ { "cell_type": "code", "execution_count": 5, + "id": "8bea2130-e3de-4df2-acc7-43613c284c65", "metadata": {}, "outputs": [ { @@ -283,6 +295,7 @@ }, { "cell_type": "markdown", + "id": "701c58e1-765a-4012-8ca6-4af0407e713a", "metadata": {}, "source": [ "\n", @@ -292,19 +305,19 @@ "\n", "For example, it is more natural and more efficient at runtime to write $B[0] \\oplus B[1] \\oplus B[2] \\ldots$, where $B = \\neg A$, than $(\\neg A[0]) \\oplus (\\neg A[1]) \\oplus (\\neg A[2]) \\ldots$.  The former computes the negation in a single parallel step before the XOR chain, instead of evaluating each negation sequentially inside the expression.\n", "\n", - "Full example: " + "Full example:" ] }, { "cell_type": "code", "execution_count": 1, + "id": "e9b8504e-88a9-4e39-b1a4-cd5d72407396", "metadata": {}, "outputs": [ { "data": { - "image/png": "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P/xQw4YNU1RUlEwmk8aNG6fFixdX6Rpyc3M1fPhwTZgwQVOmTFGXLl302Wef6Xe/+522bdtWbv+VK1dq2bJlmjNnjpKTk629RIsWLVLnzp11ww03qGfPntq1a5ckaeHCherXr5/uuusutWrVSjfeeKP27t2rESNGKDExUTfffLNyc3MllfbCjBw5Un379tV1112noUOH6pdffqmw9p49eyomJqZK13m5efPm6bvvvtOqVavUuHFjLV++XCdPntRTTz1ld/9x48Zp//79Sk5OtgalgwcPavDgwerYsaOSkpL06quvWvc3mUz661//qs6dOysuLk6ffPKJZs6cqQ4dOqhFixZav369pNKgVLt2bf3pT39SUlKSWrdurTVr1tgrQZJ00003qVatWpKkxo0bKyoqSseOHXPqewAArnRN3kMDAEb3+uuva/78+dq0aZN1mM/DDz+sHj166J///KcsFoseeugh/f3vf9fkyZMlSUePHtW6det09uxZxcXFKScnR5s2bVJGRoZatmypBx54wHquEydOaPv27frll190ww03qFu3brrxxhvL1fHTTz/Z9FLExcXpp59+qtI1hIaGat26dTbrEhIStGPHDrv733LLLRo2bJiSk5M1adIkSdLmzZu1ePFibdy4UQEBAdq0aZPuvvtu7dmzR5K0bds27d69W7GxsRozZoyGDh2qr7/+Wg0aNNCQIUP0zjvv6A9/+IOk0iFy33//vaKiovT73/9eTzzxhLW3yZUee+wxm2Wz2ay33367wv1ff/11TZo0ydrbVVxcrLvuukv/+te/dN111+n8+fPq0qWLOnfurI4dO0oq/d5+8803+vLLLzV8+HC9+uqr2r59uz744ANNnjzZGhjPnDmjxMREzZ07V1u3btWwYcOsvS6VWbNmjXJycqyvBwDuRKABAC/xySefaMuWLdbelgsXLsjX19e6/fbbb5evr6/q1Kmj+Ph4DRkyRCaTSY0aNVJkZKTS0tKsw4sefPBBmUwm1atXT7fddpvWrFljN9C423//+1/t2rXL5jlhp06d0oULFyRJXbt2VWxsrCSpQ4cOKiwsVIMGDSRJHTt21MGDB63HDR48WFFRUZJKw+Ftt91WU5fhkP3792vPnj268847revOnTunvXv3WgPG6NGjJZVec15ennXfTp062Vyz2WzWfffdJ6l0ls/o6Gjt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", "text/plain": [ - "
" + "\"Output" ] }, "execution_count": 1, @@ -317,8 +330,8 @@ "from qiskit.circuit.classical import expr, types\n", "\n", "qregs = QuantumRegister(4, \"q\")\n", - "creg = ClassicalRegister(3, \"c\")\n", - "qc = QuantumCircuit(qregs, creg)\n", + "creg = ClassicalRegister(3, \"c\")\n", + "qc = QuantumCircuit(qregs, creg)\n", "\n", "# Declare temp as a Uint(3) variable to hold the negation of creg\n", "temp = qc.add_var(\"temp\", expr.lift(0, types.Uint(3)))\n", @@ -346,6 +359,7 @@ }, { "cell_type": "markdown", + "id": "28915e23-2c47-4b55-bd6b-1e7a24aedd86", "metadata": {}, "source": [ "## Next steps\n", @@ -360,7 +374,7 @@ ], "metadata": { "kernelspec": { - "display_name": "Python 3 (ipykernel)", + "display_name": "Python 3", "language": "python", "name": "python3" }, @@ -374,7 +388,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.12.3" + "version": "3" } }, "nbformat": 4, diff --git a/docs/guides/estimator-input-output.ipynb b/docs/guides/estimator-input-output.ipynb index 8ab60189156..a2170762b7a 100644 --- a/docs/guides/estimator-input-output.ipynb +++ b/docs/guides/estimator-input-output.ipynb @@ -2,6 +2,7 @@ "cells": [ { "cell_type": "markdown", + "id": "066d7e4d-a975-4519-b56f-095f861be3ac", "metadata": {}, "source": [ "---\n", @@ -15,6 +16,7 @@ }, { "cell_type": "markdown", + "id": "23e7dff0-fde5-4c2d-89c2-fc5ab99240fe", "metadata": { "tags": [ "version-info" @@ -44,6 +46,7 @@ }, { "cell_type": "markdown", + "id": "90d0c1e0-28e7-48da-a35f-6016fddea82c", "metadata": {}, "source": [ "This page gives an overview of the inputs and outputs of the Qiskit Runtime Estimator primitive, which executes workloads on IBM Quantum® compute resources. Estimator lets you efficiently define vectorized workloads by using a data structure called a [**Primitive Unified Bloc (PUB)**](/docs/guides/primitive-input-output#pubs). They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method for the Estimator primitive, which executes the defined workload as a job. Then, after the job has completed, the results are returned in a format that is dependent on both the PUBs used as well as the runtime options specified from the primitive." @@ -51,6 +54,7 @@ }, { "cell_type": "markdown", + "id": "83a5fdd8-6547-47c7-9441-a7458edc7896", "metadata": {}, "source": [ "## Inputs\n", @@ -79,6 +83,7 @@ }, { "cell_type": "markdown", + "id": "846b3109-02a1-4783-ad3f-1c22f753c324", "metadata": {}, "source": [ "---\n", @@ -89,6 +94,7 @@ { "cell_type": "code", "execution_count": 1, + "id": "2f50a9f5-2cc1-4d83-9fe1-1b3a8be0d766", "metadata": {}, "outputs": [], "source": [ @@ -164,6 +170,7 @@ }, { "cell_type": "markdown", + "id": "90dccb20-1848-4367-a12d-434110ad5a5c", "metadata": {}, "source": [ "## Outputs\n", @@ -216,6 +223,7 @@ { "cell_type": "code", "execution_count": 2, + "id": "53a4d5ae-109b-452b-bbc5-2d7940c5182c", "metadata": {}, "outputs": [ { @@ -262,6 +270,7 @@ }, { "cell_type": "markdown", + "id": "000ade51-d940-45f9-84ea-16ad283a930f", "metadata": {}, "source": [ "#### How the Estimator primitive calculates error\n", @@ -283,6 +292,7 @@ }, { "cell_type": "markdown", + "id": "c4341184-a41a-4442-bc05-838c90ea93b8", "metadata": {}, "source": [ "## Result metadata\n", @@ -297,6 +307,7 @@ { "cell_type": "code", "execution_count": 3, + "id": "626ba203-44e2-4b8f-b04d-04388b8b1fa1", "metadata": {}, "outputs": [ { @@ -333,7 +344,7 @@ "metadata": { "celltoolbar": "Raw Cell Format", "kernelspec": { - "display_name": "Python 3 (ipykernel)", + "display_name": "Python 3", "language": "python", "name": "python3" }, @@ -347,7 +358,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.12.3" + "version": "3" } }, "nbformat": 4, diff --git a/docs/guides/execute-dynamic-circuits.ipynb b/docs/guides/execute-dynamic-circuits.ipynb index 94c2317098d..a1f304d871e 100644 --- a/docs/guides/execute-dynamic-circuits.ipynb +++ b/docs/guides/execute-dynamic-circuits.ipynb @@ -2,6 +2,7 @@ "cells": [ { "cell_type": "markdown", + "id": "83596f71-5e63-4aa2-907b-75de8813d85a", "metadata": {}, "source": [ "---\n", @@ -15,6 +16,7 @@ }, { "cell_type": "markdown", + "id": "7e9dc06d-85fa-4425-9bd1-ce5085be9741", "metadata": { "tags": [ "version-info" @@ -44,6 +46,7 @@ }, { "cell_type": "markdown", + "id": "2228a8a2-02b7-4a0b-bbe8-0c2933fbe44a", "metadata": {}, "source": [ "Dynamic circuits are powerful tools with which you can measure qubits in the middle of a quantum circuit execution and then perform classical logic operations within the circuit, based on the outcome of those mid-circuit measurements. This process is also known as _classical feedforward_. While these are early days of understanding how best to take advantage of dynamic circuits, the quantum research community has already identified a number of use cases, such as the following:\n", @@ -63,6 +66,7 @@ }, { "cell_type": "markdown", + "id": "c4616d43-f296-4a84-a79c-deb37fcdac15", "metadata": {}, "source": [ "## Find backends that support dynamic circuits\n", @@ -79,6 +83,7 @@ { "cell_type": "code", "execution_count": 1, + "id": "076db590-29db-4137-a043-45485c9f46df", "metadata": { "tags": [ "remove-cell" @@ -95,6 +100,7 @@ { "cell_type": "code", "execution_count": 2, + "id": "a63f07b1-9e8a-4086-ab01-552bd444dc9b", "metadata": {}, "outputs": [ { @@ -115,6 +121,7 @@ }, { "cell_type": "markdown", + "id": "1dca7d79-99ea-42bd-86f7-182266907a85", "metadata": {}, "source": [ "\n", @@ -134,6 +141,7 @@ { "cell_type": "code", "execution_count": 3, + "id": "87dfb9c7-1dc2-4752-bdc1-17b9144369f4", "metadata": {}, "outputs": [ { @@ -172,6 +180,7 @@ }, { "cell_type": "markdown", + "id": "2b603f88-2e0e-4819-8342-8e3662949ff3", "metadata": {}, "source": [ "\n", @@ -184,6 +193,7 @@ }, { "cell_type": "markdown", + "id": "9401a5cc-49e0-48b6-8deb-88e9b7da5a5a", "metadata": {}, "source": [ "## `Store`\n", @@ -202,11 +212,12 @@ ")\n", "```\n", "\n", - "For a full example, see the [Classical feedforward and control flow](/docs/guides/classical-feedforward-and-control-flow#store) guide. " + "For a full example, see the [Classical feedforward and control flow](/docs/guides/classical-feedforward-and-control-flow#store) guide." ] }, { "cell_type": "markdown", + "id": "3f374a74-c331-40de-8594-686e471058a2", "metadata": {}, "source": [ "## Full example\n", @@ -217,6 +228,7 @@ { "cell_type": "code", "execution_count": 4, + "id": "a7a9c998-4031-432f-978b-83edc040798f", "metadata": {}, "outputs": [ { @@ -271,6 +283,7 @@ }, { "cell_type": "markdown", + "id": "c5b14dcf-edf4-4fef-bb49-e6b86f06afb0", "metadata": {}, "source": [ "## Qiskit Runtime limitations\n", @@ -353,6 +366,7 @@ }, { "cell_type": "markdown", + "id": "ca6e0493-d364-40bf-9f47-2e3feed9f82c", "metadata": {}, "source": [ "## Use dynamic circuits with Estimator\n", @@ -371,6 +385,7 @@ }, { "cell_type": "markdown", + "id": "07045397-6db8-4151-a1e4-de24a8f39ab6", "metadata": {}, "source": [ "## Restrictions\n", @@ -380,6 +395,7 @@ }, { "cell_type": "markdown", + "id": "6688e2e3-766b-4194-99db-ae097e9b8bc7", "metadata": {}, "source": [ "## Next steps\n", @@ -395,7 +411,7 @@ ], "metadata": { "kernelspec": { - "display_name": "Python 3 (ipykernel)", + "display_name": "Python 3", "language": "python", "name": "python3" }, @@ -409,7 +425,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.12.3" + "version": "3" } }, "nbformat": 4, diff --git a/public/docs/images/guides/classical-feedforward-and-control-flow/extracted-outputs/e9b8504e-88a9-4e39-b1a4-cd5d72407396-0.avif b/public/docs/images/guides/classical-feedforward-and-control-flow/extracted-outputs/e9b8504e-88a9-4e39-b1a4-cd5d72407396-0.avif new file mode 100644 index 0000000000000000000000000000000000000000..f2a91aa039a4ed8148bda7ad4acf2a2dc9fd008f GIT binary patch literal 3788 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 Ol5YmP)@~#=%>NIqf7I;& literal 0 HcmV?d00001 From b18d69977fda306668484940b36f5a8cfd95c2dd Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Thu, 28 May 2026 09:23:14 -0500 Subject: [PATCH 25/28] fran review --- ...assical-feedforward-and-control-flow.ipynb | 31 ++++++------------- docs/guides/execute-dynamic-circuits.ipynb | 14 +-------- 2 files changed, 10 insertions(+), 35 deletions(-) diff --git a/docs/guides/classical-feedforward-and-control-flow.ipynb b/docs/guides/classical-feedforward-and-control-flow.ipynb index de45e255614..b382fdce73d 100644 --- a/docs/guides/classical-feedforward-and-control-flow.ipynb +++ b/docs/guides/classical-feedforward-and-control-flow.ipynb @@ -310,39 +310,26 @@ }, { "cell_type": "code", - "execution_count": 1, - "id": "e9b8504e-88a9-4e39-b1a4-cd5d72407396", + "execution_count": null, "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 1, - "metadata": {}, - "output_type": "execute_result" - } - ], + "outputs": [], "source": [ "from qiskit.circuit import QuantumCircuit, QuantumRegister, ClassicalRegister\n", - "from qiskit.circuit.classical import expr, types\n", + "from qiskit.circuit.classical import expr\n", "\n", "qregs = QuantumRegister(4, \"q\")\n", - "creg = ClassicalRegister(3, \"c\")\n", - "qc = QuantumCircuit(qregs, creg)\n", - "\n", - "# Declare temp as a Uint(3) variable to hold the negation of creg\n", - "temp = qc.add_var(\"temp\", expr.lift(0, types.Uint(3)))\n", + "creg = ClassicalRegister(3, \"c\")\n", + "# temp is a plain ClassicalRegister used as the store target\n", + "temp = ClassicalRegister(3, \"temp\")\n", + "qc = QuantumCircuit(qregs, creg, temp)\n", "\n", "qc.h([0, 1, 2])\n", "qc.measure([0, 1, 2], creg)\n", "\n", - "# Store bit-NOT of the full 3-bit register in a single parallel step\n", + "# Store bit-NOT of the full 3-bit register into temp\n", "qc.store(temp, expr.bit_not(creg))\n", "\n", - "# Compute parity of the stored result using bit-indexed XOR\n", + "# Compute parity of temp using bit-indexed XOR\n", "parity = expr.bit_xor(\n", " expr.bit_xor(expr.index(temp, 0), expr.index(temp, 1)),\n", " expr.index(temp, 2),\n", diff --git a/docs/guides/execute-dynamic-circuits.ipynb b/docs/guides/execute-dynamic-circuits.ipynb index a1f304d871e..c30ec7eb380 100644 --- a/docs/guides/execute-dynamic-circuits.ipynb +++ b/docs/guides/execute-dynamic-circuits.ipynb @@ -200,19 +200,7 @@ "\n", "With qiskit-ibm-runtime version 0.47.0 or later, you can use the [`store`](/docs/api/qiskit/circuit#store) instruction to save the result of a classical expression, if that expression will be used repeatedly. Operations are automatically parallelized, making your code significantly more efficient at runtime.\n", "\n", - "For example, it is more natural and more efficient at runtime to write $B[0] \\oplus B[1] \\oplus B[2] \\ldots$, where $B = \\neg A$, than $(\\neg A[0]) \\oplus (\\neg A[1]) \\oplus (\\neg A[2]) \\ldots$.  The former computes the negation in a single parallel step before the XOR chain, instead of evaluating each negation sequentially inside the expression. The former can be written in Qiskit as follows:\n", - "\n", - "```python\n", - "# Store the negation in temporary variable\n", - "qc.store(temp, expr.bit_not(creg))\n", - "\n", - "# Compute parity using the stored result\n", - "parity = expr.bit_xor(\n", - " expr.bit_xor(temp[0], temp[1]), temp[2]\n", - ")\n", - "```\n", - "\n", - "For a full example, see the [Classical feedforward and control flow](/docs/guides/classical-feedforward-and-control-flow#store) guide." + "For more information, see the [Classical feedforward and control flow](/docs/guides/classical-feedforward-and-control-flow#store) guide." ] }, { From 6fe1eee941119129fa5750da76c99fb0bb1bbff9 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Thu, 28 May 2026 10:15:17 -0500 Subject: [PATCH 26/28] Run new code --- ...assical-feedforward-and-control-flow.ipynb | 50 +++++++++++------- ...64ec241-41e8-40f8-ab64-af236c6c7802-0.avif | Bin 0 -> 4576 bytes ...9b8504e-88a9-4e39-b1a4-cd5d72407396-0.avif | Bin 3788 -> 0 bytes 3 files changed, 31 insertions(+), 19 deletions(-) create mode 100644 public/docs/images/guides/classical-feedforward-and-control-flow/extracted-outputs/e64ec241-41e8-40f8-ab64-af236c6c7802-0.avif delete mode 100644 public/docs/images/guides/classical-feedforward-and-control-flow/extracted-outputs/e9b8504e-88a9-4e39-b1a4-cd5d72407396-0.avif diff --git a/docs/guides/classical-feedforward-and-control-flow.ipynb b/docs/guides/classical-feedforward-and-control-flow.ipynb index b382fdce73d..4d774c4b483 100644 --- a/docs/guides/classical-feedforward-and-control-flow.ipynb +++ b/docs/guides/classical-feedforward-and-control-flow.ipynb @@ -2,7 +2,7 @@ "cells": [ { "cell_type": "markdown", - "id": "295e2195-484b-49a7-83e5-fdc27d322eee", + "id": "96086a58-1a50-4af1-b76e-5d490157efe4", "metadata": {}, "source": [ "---\n", @@ -16,7 +16,7 @@ }, { "cell_type": "markdown", - "id": "3cea13bc-a7ca-42ba-9ce5-c59833457e68", + "id": "ef85eedb-3040-4cb0-9ae4-e6825d0b8b99", "metadata": { "tags": [ "version-info" @@ -45,7 +45,7 @@ }, { "cell_type": "markdown", - "id": "04715d79-3a52-4dd6-864d-eb50a7840909", + "id": "99f0e64b-a94a-416b-8162-30b1a9862e19", "metadata": {}, "source": [ "Dynamic circuits are powerful tools with which you can measure qubits in the middle of a quantum circuit execution and then perform classical logic operations within the circuit, based on the outcome of those mid-circuit measurements. This process is also known as _classical feedforward_. While these are early days of understanding how best to take advantage of dynamic circuits, the quantum research community has already identified a number of use cases, such as the following:\n", @@ -57,7 +57,7 @@ }, { "cell_type": "markdown", - "id": "5da510ac-1c5d-494b-b709-8d1030bfb92a", + "id": "5627c18e-0bb7-48c0-b91e-a0d7e731fb5c", "metadata": {}, "source": [ "## `if` statement\n", @@ -70,7 +70,7 @@ { "cell_type": "code", "execution_count": 1, - "id": "7dc7f56a-25a1-486f-838d-a50ea6cd4beb", + "id": "9173934e-d09d-40ae-bcff-8a582be22dcd", "metadata": {}, "outputs": [ { @@ -105,7 +105,7 @@ }, { "cell_type": "markdown", - "id": "02a3925d-f619-4759-bfa7-4d1ac0207737", + "id": "6286036e-300d-48a9-aa89-158d181a6eff", "metadata": {}, "source": [ "The `with` statement can be given an assignment target which is itself a context manager that can be stored and subsequently used to create an else block, which is executed whenever the contents of the `if` block are *not* executed.\n", @@ -116,7 +116,7 @@ { "cell_type": "code", "execution_count": 2, - "id": "320e383c-9d4a-4f68-9a4c-b986cab38195", + "id": "fcbd6923-b2bf-455b-bced-84aa539f8ac6", "metadata": {}, "outputs": [ { @@ -152,7 +152,7 @@ }, { "cell_type": "markdown", - "id": "1e39751a-0eb2-4c33-8f57-a3a77e0c7caa", + "id": "649aa80e-31f1-460a-b12d-7a451bea7851", "metadata": {}, "source": [ "In addition to conditioning on a single classical bit, it's also possible to condition on the value of a classical register composed of multiple bits.\n", @@ -163,7 +163,7 @@ { "cell_type": "code", "execution_count": 3, - "id": "b46cb721-073b-4ac1-a411-5c716d11e879", + "id": "686c8c5f-330a-4aae-b42a-852d4c4730e4", "metadata": {}, "outputs": [ { @@ -198,7 +198,7 @@ }, { "cell_type": "markdown", - "id": "cf56f5fa-da42-418d-96e8-c3e0620dc0d7", + "id": "9ff45446-8c18-414f-ae88-2718f5bf7d3f", "metadata": {}, "source": [ "## Classical expressions\n", @@ -214,7 +214,7 @@ { "cell_type": "code", "execution_count": 4, - "id": "755b92e4-8a47-4a88-96ab-157a9d487465", + "id": "c90c4755-947c-4503-9bee-0237c2b2103b", "metadata": {}, "outputs": [], "source": [ @@ -275,7 +275,7 @@ { "cell_type": "code", "execution_count": 5, - "id": "8bea2130-e3de-4df2-acc7-43613c284c65", + "id": "b5fdd320-da61-4fc5-86ed-8eefa104965e", "metadata": {}, "outputs": [ { @@ -295,7 +295,7 @@ }, { "cell_type": "markdown", - "id": "701c58e1-765a-4012-8ca6-4af0407e713a", + "id": "0d9cb9a0-c8dc-44ba-8cb2-416bf3748c45", "metadata": {}, "source": [ "\n", @@ -310,18 +310,30 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 1, + "id": "e64ec241-41e8-40f8-ab64-af236c6c7802", "metadata": {}, - "outputs": [], + "outputs": [ + { + "data": { + "text/plain": [ + "\"Output" + ] + }, + "execution_count": 1, + "metadata": {}, + "output_type": "execute_result" + } + ], "source": [ "from qiskit.circuit import QuantumCircuit, QuantumRegister, ClassicalRegister\n", "from qiskit.circuit.classical import expr\n", "\n", "qregs = QuantumRegister(4, \"q\")\n", - "creg = ClassicalRegister(3, \"c\")\n", + "creg = ClassicalRegister(3, \"c\")\n", "# temp is a plain ClassicalRegister used as the store target\n", - "temp = ClassicalRegister(3, \"temp\")\n", - "qc = QuantumCircuit(qregs, creg, temp)\n", + "temp = ClassicalRegister(3, \"temp\")\n", + "qc = QuantumCircuit(qregs, creg, temp)\n", "\n", "qc.h([0, 1, 2])\n", "qc.measure([0, 1, 2], creg)\n", @@ -346,7 +358,7 @@ }, { "cell_type": "markdown", - "id": "28915e23-2c47-4b55-bd6b-1e7a24aedd86", + "id": "9688221f-3da3-4a5b-aac9-aabf7b518d82", "metadata": {}, "source": [ "## Next steps\n", diff --git a/public/docs/images/guides/classical-feedforward-and-control-flow/extracted-outputs/e64ec241-41e8-40f8-ab64-af236c6c7802-0.avif b/public/docs/images/guides/classical-feedforward-and-control-flow/extracted-outputs/e64ec241-41e8-40f8-ab64-af236c6c7802-0.avif new file mode 100644 index 0000000000000000000000000000000000000000..e55c137ebcba3b3d39c51e31f6730fd04c5dd515 GIT binary patch literal 4576 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 Ol5YmP)@~#=%>NIqf7I;& From a4d6be8f06ab829a00501b4e364cad92fbec7762 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Thu, 28 May 2026 13:07:58 -0500 Subject: [PATCH 27/28] instruction not directive --- docs/guides/executor-options.ipynb | 2 +- docs/guides/sampler-options.ipynb | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/executor-options.ipynb b/docs/guides/executor-options.ipynb index 5187e783dd1..1ae656f60ec 100644 --- a/docs/guides/executor-options.ipynb +++ b/docs/guides/executor-options.ipynb @@ -242,7 +242,7 @@ " Other notes:\n", " - Gate twirling can be applied to dynamic circuits, but only to gates not inside conditional blocks.\n", " - Measurement twirling can only be applied to terminal measurements.\n", - " - Measurement twirling is incompatible with the [`store`](/docs/api/qiskit/circuit#store) directive.\n", + " - Measurement twirling is incompatible with the [`store`](/docs/api/qiskit/circuit#store) instruction.\n", " - Compatible with fractional gates when using `qiskit-ibm-runtime` v0.42.0 or later.\n", "\n", " \n", diff --git a/docs/guides/sampler-options.ipynb b/docs/guides/sampler-options.ipynb index da7e0ac3bb8..754a1747b5a 100644 --- a/docs/guides/sampler-options.ipynb +++ b/docs/guides/sampler-options.ipynb @@ -512,7 +512,7 @@ " Other notes:\n", " - Gate twirling can be applied to dynamic circuits, but only to gates not inside conditional blocks.\n", " - Measurement twirling can only be applied to terminal measurements.\n", - " - Measurement twirling is incompatible with the [`store`](/docs/api/qiskit/circuit#store) directive.\n", + " - Measurement twirling is incompatible with the [`store`](/docs/api/qiskit/circuit#store) instruction.\n", " - Does not work with non-Clifford entanglers.\n", " \n", "" From 53f221473915450523868d8cb8ad4803b2a18826 Mon Sep 17 00:00:00 2001 From: abbycross Date: Thu, 28 May 2026 14:09:49 -0400 Subject: [PATCH 28/28] code ticks --- docs/guides/execute-dynamic-circuits.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/execute-dynamic-circuits.ipynb b/docs/guides/execute-dynamic-circuits.ipynb index c30ec7eb380..71573112a70 100644 --- a/docs/guides/execute-dynamic-circuits.ipynb +++ b/docs/guides/execute-dynamic-circuits.ipynb @@ -198,7 +198,7 @@ "source": [ "## `Store`\n", "\n", - "With qiskit-ibm-runtime version 0.47.0 or later, you can use the [`store`](/docs/api/qiskit/circuit#store) instruction to save the result of a classical expression, if that expression will be used repeatedly. Operations are automatically parallelized, making your code significantly more efficient at runtime.\n", + "With `qiskit-ibm-runtime` version 0.47.0 or later, you can use the [`store`](/docs/api/qiskit/circuit#store) instruction to save the result of a classical expression, if that expression will be used repeatedly. Operations are automatically parallelized, making your code significantly more efficient at runtime.\n", "\n", "For more information, see the [Classical feedforward and control flow](/docs/guides/classical-feedforward-and-control-flow#store) guide." ]