From b08d0dee3977132b99544b047670beade5c3f22f Mon Sep 17 00:00:00 2001 From: Eric Harvey Date: Thu, 11 Jun 2026 19:29:24 -0400 Subject: [PATCH] Parse qiskit-addon-obp addon content --- docs/addons/qiskit-addon-obp/_toc.json | 71 ++ .../guides/bound-error-using-p-norm.ipynb | 470 +++++++++ docs/addons/qiskit-addon-obp/guides/index.mdx | 13 + .../qiskit-addon-obp/guides/overview.mdx | 23 + .../qiskit-addon-obp/guides/quickstart.ipynb | 44 + .../guides/simulating-circuits-with-obp.ipynb | 585 +++++++++++ .../guides/truncate-operator-terms.ipynb | 947 ++++++++++++++++++ docs/addons/qiskit-addon-obp/index.mdx | 31 + docs/addons/qiskit-addon-obp/install.mdx | 77 ++ docs/api/qiskit-addon-obp/_toc.json | 4 +- .../api/qiskit-addon-obp/qiskit-addon-obp.mdx | 6 +- docs/api/qiskit-addon-obp/release-notes.mdx | 68 +- .../utils-metadata-obp-metadata.mdx | 18 +- .../utils-metadata-slice-metadata.mdx | 4 +- docs/api/qiskit-addon-obp/utils-metadata.mdx | 8 +- ...noise-pauli-lindblad-error-instruction.mdx | 6 +- docs/api/qiskit-addon-obp/utils-noise.mdx | 6 +- .../api/qiskit-addon-obp/utils-operations.mdx | 8 +- docs/api/qiskit-addon-obp/utils-simplify.mdx | 8 +- .../api/qiskit-addon-obp/utils-truncating.mdx | 10 +- .../qiskit-addon-obp/utils-visualization.mdx | 32 +- public/docs/api/qiskit-addon-obp/objects.inv | Bin 3686 -> 2610 bytes ...6f281d4-706e-41ad-b7b5-bc7ebe106996-0.avif | Bin 0 -> 11411 bytes ...e7f454c-7d79-4c61-b1dd-6a98564fb5f1-0.avif | Bin 0 -> 6961 bytes ...f72e77f-e2c0-4cce-8575-c5aa587f78fb-0.avif | Bin 0 -> 7140 bytes ...758f393-8691-4116-94ca-1185c6188bb4-0.avif | Bin 0 -> 11411 bytes ...adc314d-452f-465c-a382-d54685ce3f2a-0.avif | Bin 0 -> 32495 bytes ...97fc3b0-d3b4-432d-96cd-7e175b7e6a52-0.avif | Bin 0 -> 11411 bytes ...c36768e-03e7-4e1b-81b3-59b6e9eab43e-0.avif | Bin 0 -> 15073 bytes ...1d36d7e-0bd5-4388-bbb8-6831bf1f02e6-0.avif | Bin 0 -> 12043 bytes ...8f118df-6718-49b2-ba80-c37ef461f71a-0.avif | Bin 0 -> 13855 bytes ...9c9069a-9038-4319-8dc6-37a1be973ebf-0.avif | Bin 0 -> 12758 bytes ...2271b0d-ddaf-4ad2-b5c6-e9e4c2a4cff7-0.avif | Bin 0 -> 16712 bytes ...0bf5050-2928-41a1-9c3d-c9d79e918f6f-0.avif | Bin 0 -> 15126 bytes ...7167f80-5d29-4c32-be97-cba733f18b1d-0.avif | Bin 0 -> 13213 bytes ...skit_addon_obp-utils-visualization-10.avif | Bin 4572 -> 4572 bytes ...skit_addon_obp-utils-visualization-12.avif | Bin 3157 -> 3160 bytes ...skit_addon_obp-utils-visualization-14.avif | Bin 3412 -> 3475 bytes ...iskit_addon_obp-utils-visualization-2.avif | Bin 4013 -> 4024 bytes ...iskit_addon_obp-utils-visualization-4.avif | Bin 4295 -> 4335 bytes ...iskit_addon_obp-utils-visualization-6.avif | Bin 3222 -> 3239 bytes ...iskit_addon_obp-utils-visualization-8.avif | Bin 3606 -> 3646 bytes .../config/historical-pages-to-latest.json | 22 +- 43 files changed, 2369 insertions(+), 92 deletions(-) create mode 100644 docs/addons/qiskit-addon-obp/_toc.json create mode 100644 docs/addons/qiskit-addon-obp/guides/bound-error-using-p-norm.ipynb create mode 100644 docs/addons/qiskit-addon-obp/guides/index.mdx create mode 100644 docs/addons/qiskit-addon-obp/guides/overview.mdx create mode 100644 docs/addons/qiskit-addon-obp/guides/quickstart.ipynb create mode 100644 docs/addons/qiskit-addon-obp/guides/simulating-circuits-with-obp.ipynb create mode 100644 docs/addons/qiskit-addon-obp/guides/truncate-operator-terms.ipynb create mode 100644 docs/addons/qiskit-addon-obp/index.mdx create mode 100644 docs/addons/qiskit-addon-obp/install.mdx create mode 100644 public/docs/images/addons/qiskit-addon-obp/guides/bound-error-using-p-norm/extracted-outputs/d6f281d4-706e-41ad-b7b5-bc7ebe106996-0.avif create mode 100644 public/docs/images/addons/qiskit-addon-obp/guides/bound-error-using-p-norm/extracted-outputs/fe7f454c-7d79-4c61-b1dd-6a98564fb5f1-0.avif create mode 100644 public/docs/images/addons/qiskit-addon-obp/guides/bound-error-using-p-norm/extracted-outputs/ff72e77f-e2c0-4cce-8575-c5aa587f78fb-0.avif create mode 100644 public/docs/images/addons/qiskit-addon-obp/guides/simulating-circuits-with-obp/extracted-outputs/8758f393-8691-4116-94ca-1185c6188bb4-0.avif create mode 100644 public/docs/images/addons/qiskit-addon-obp/guides/simulating-circuits-with-obp/extracted-outputs/dadc314d-452f-465c-a382-d54685ce3f2a-0.avif create mode 100644 public/docs/images/addons/qiskit-addon-obp/guides/truncate-operator-terms/extracted-outputs/297fc3b0-d3b4-432d-96cd-7e175b7e6a52-0.avif create mode 100644 public/docs/images/addons/qiskit-addon-obp/guides/truncate-operator-terms/extracted-outputs/4c36768e-03e7-4e1b-81b3-59b6e9eab43e-0.avif create mode 100644 public/docs/images/addons/qiskit-addon-obp/guides/truncate-operator-terms/extracted-outputs/51d36d7e-0bd5-4388-bbb8-6831bf1f02e6-0.avif create mode 100644 public/docs/images/addons/qiskit-addon-obp/guides/truncate-operator-terms/extracted-outputs/68f118df-6718-49b2-ba80-c37ef461f71a-0.avif create mode 100644 public/docs/images/addons/qiskit-addon-obp/guides/truncate-operator-terms/extracted-outputs/69c9069a-9038-4319-8dc6-37a1be973ebf-0.avif create mode 100644 public/docs/images/addons/qiskit-addon-obp/guides/truncate-operator-terms/extracted-outputs/82271b0d-ddaf-4ad2-b5c6-e9e4c2a4cff7-0.avif create mode 100644 public/docs/images/addons/qiskit-addon-obp/guides/truncate-operator-terms/extracted-outputs/b0bf5050-2928-41a1-9c3d-c9d79e918f6f-0.avif create mode 100644 public/docs/images/addons/qiskit-addon-obp/guides/truncate-operator-terms/extracted-outputs/b7167f80-5d29-4c32-be97-cba733f18b1d-0.avif diff --git a/docs/addons/qiskit-addon-obp/_toc.json b/docs/addons/qiskit-addon-obp/_toc.json new file mode 100644 index 00000000000..b55fb020f9e --- /dev/null +++ b/docs/addons/qiskit-addon-obp/_toc.json @@ -0,0 +1,71 @@ +{ + "parentUrl": "/docs/guides/addons", + "parentLabel": "Documentation", + "title": "Operator backpropagation (OBP) 0.3.0", + "collapsed": true, + "children": [ + { + "title": "", + "children": [ + { + "title": "Documentation home", + "url": "/docs/addons/qiskit-addon-obp" + }, + { + "title": "Installation instructions", + "url": "/docs/addons/qiskit-addon-obp/install" + }, + { + "title": "Guides", + "children": [ + { + "title": "Overview", + "url": "/docs/addons/qiskit-addon-obp/guides/overview" + }, + { + "title": "Quick start guide", + "url": "/docs/addons/qiskit-addon-obp/guides/quickstart" + }, + { + "title": "Bound error in experiments", + "url": "/docs/addons/qiskit-addon-obp/guides/bound-error-using-p-norm" + }, + { + "title": "Simulate circuits with OBP", + "url": "/docs/addons/qiskit-addon-obp/guides/simulating-circuits-with-obp" + }, + { + "title": "Truncate operator terms during backpropagation", + "url": "/docs/addons/qiskit-addon-obp/guides/truncate-operator-terms" + } + ] + }, + { + "title": "GitHub", + "url": "https://github.com/Qiskit/qiskit-addon-obp" + } + ], + "collapsible": false + }, + { + "title": "Tutorials", + "collapsible": false, + "children": [ + { + "title": "Operator backpropagation (OBP) for estimation of expectation values", + "url": "https://quantum.cloud.ibm.com/docs/en/tutorials/operator-back-propagation" + } + ] + }, + { + "title": "API reference", + "collapsible": false, + "children": [ + { + "title": "Python API reference", + "url": "https://quantum.cloud.ibm.com/docs/en/api/qiskit-addon-obp" + } + ] + } + ] +} diff --git a/docs/addons/qiskit-addon-obp/guides/bound-error-using-p-norm.ipynb b/docs/addons/qiskit-addon-obp/guides/bound-error-using-p-norm.ipynb new file mode 100644 index 00000000000..8aca8419b89 --- /dev/null +++ b/docs/addons/qiskit-addon-obp/guides/bound-error-using-p-norm.ipynb @@ -0,0 +1,470 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "frontmatter", + "metadata": {}, + "source": [ + "---\n", + "title: \"Use different Lp-norms for Pauli term truncation\"\n", + "description: \"Use different Lp-norms for Pauli term truncation for the latest version of Operator backpropagation (OBP)\"\n", + "---" + ] + }, + { + "cell_type": "markdown", + "id": "8a7c9df5-d836-4ecb-8aec-8a1f2faa017a", + "metadata": {}, + "source": [ + "# Use different Lp-norms for Pauli term truncation" + ] + }, + { + "cell_type": "markdown", + "id": "5958e635-64c1-4599-82ca-225b83312906", + "metadata": {}, + "source": [ + "**Note:** Before reading this guide, you should read the [Truncate Pauli terms](https://qiskit.github.io/qiskit-addon-obp/how_tos/truncate_operator_terms.html) guide, which describes the truncation of low-weight Pauli terms that is built into the [backpropagate](/docs/api/qiskit-addon-obp/qiskit-addon-obp#backpropagate) method based on a specified [TruncationErrorBudget](/docs/api/qiskit-addon-obp/utils-truncating#truncationerrorbudget)." + ] + }, + { + "cell_type": "markdown", + "id": "2780c587-cd2a-4398-8faa-de5e0c661a10", + "metadata": {}, + "source": [ + "In this guide, you will learn about the [backpropagate](/docs/api/qiskit-addon-obp/qiskit-addon-obp#backpropagate) keyword argument, `p_norm`, which can be used to change the Lp-norm used to estimate the error incurred by the truncated Pauli terms." + ] + }, + { + "cell_type": "markdown", + "id": "872aeae7-0312-41db-8ebb-f7b02838b54d", + "metadata": {}, + "source": [ + "## Construct an example circuit\n", + "\n", + "This guide uses the same example circuit as in the [Truncate Pauli terms](https://qiskit.github.io/qiskit-addon-obp/how_tos/truncate_operator_terms.html) guide:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d6f281d4-706e-41ad-b7b5-bc7ebe106996", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "\"Output" + ] + }, + "execution_count": 1, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "import rustworkx.generators\n", + "from qiskit.synthesis import LieTrotter\n", + "from qiskit_addon_utils.problem_generators import (\n", + " PauliOrderStrategy,\n", + " generate_time_evolution_circuit,\n", + " generate_xyz_hamiltonian,\n", + ")\n", + "from qiskit_addon_utils.slicing import combine_slices, slice_by_gate_types\n", + "\n", + "# Generate a linear chain of 10 qubits\n", + "num_qubits = 10\n", + "linear_chain = rustworkx.generators.path_graph(num_qubits)\n", + "\n", + "# Use an arbitrary XY model\n", + "hamiltonian = generate_xyz_hamiltonian(\n", + " linear_chain,\n", + " coupling_constants=(0.05, 0.02, 0.0),\n", + " ext_magnetic_field=(0.02, 0.08, 0.0),\n", + " pauli_order_strategy=PauliOrderStrategy.InteractionThenColor,\n", + ")\n", + "# Evolve for some time\n", + "circuit = generate_time_evolution_circuit(\n", + " hamiltonian, synthesis=LieTrotter(reps=3), time=2.0\n", + ")\n", + "# slice the circuit by gate type\n", + "slices = slice_by_gate_types(circuit)\n", + "\n", + "# For visualization purposes only, recombine the slices with barriers between them and draw the resulting circuit\n", + "combine_slices(slices, include_barriers=True).draw(\"mpl\", fold=50, scale=0.6)" + ] + }, + { + "cell_type": "markdown", + "id": "7a7c7299-0c82-4279-b3dc-4f39e8dddd7e", + "metadata": {}, + "source": [ + "Define an observable for the total magnetization:" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "ea9e7adc-b003-4762-a889-10e8d84a63d5", + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit.quantum_info import SparsePauliOp\n", + "\n", + "obs = SparsePauliOp.from_sparse_list(\n", + " [(\"Z\", [i], 1.0) for i in range(num_qubits)], num_qubits=num_qubits\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "423150d8-80d2-4b80-9665-033808d30272", + "metadata": {}, + "source": [ + "For reference, compute the exact expectation value:" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "4dc72426-2eb5-4f8d-8bba-79650da06b54", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "9.318197859862146\n" + ] + } + ], + "source": [ + "from qiskit.primitives import StatevectorEstimator\n", + "\n", + "estimator = StatevectorEstimator()\n", + "job = estimator.run([(circuit, obs)])\n", + "res = job.result()\n", + "exact_exp = res[0].data.evs\n", + "print(exact_exp)" + ] + }, + { + "cell_type": "markdown", + "id": "d21490c0-e86c-4fe0-af90-c9625813e0c0", + "metadata": {}, + "source": [ + "## Use the L1 norm\n", + "\n", + "By default, and as you have already seen in the [Truncate Pauli terms](https://qiskit.github.io/qiskit-addon-obp/how_tos/truncate_operator_terms.html) guide, `p_norm=1`, which means that the error is estimated as:\n", + "$$\n", + "|\\langle\\psi|\\Delta|\\psi\\rangle| \\leq \\sum_{P\\in\\mathcal{T}} |c_P|\n", + "$$\n", + "where $\\psi$ is the quantum state, $\\Delta$ is the real difference between the exact and truncated observable (which is unknown), $\\mathcal{T}$ is the set of Pauli terms that were truncated, and $c_P$ is the Pauli terms coefficient.\n", + "This inequality is a rigorous but very loose upper bound for most scenarios." + ] + }, + { + "cell_type": "markdown", + "id": "425293ce-49fb-4bd0-8d2f-44a3a43db967", + "metadata": {}, + "source": [ + "This guide, backpropagates six slices of the example circuit, using a constant error per slice of `0.001`. This value is to be understood as the budget within the given `p_norm`." + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "b46531b3-055b-4112-903a-11f2dd52a9ac", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "TruncationErrorBudget(per_slice_budget=[0.001], max_error_total=inf, p_norm=1)\n" + ] + } + ], + "source": [ + "from qiskit_addon_obp.utils.truncating import setup_budget\n", + "\n", + "l1_truncation_error_budget = setup_budget(max_error_per_slice=0.001, p_norm=1)\n", + "print(l1_truncation_error_budget)" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "bc252678-58a0-407e-91fe-b7c545d57ae8", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Backpropagated 6 circuit slices.\n", + "New observable contains 116 terms and 10 commuting groups.\n" + ] + } + ], + "source": [ + "from qiskit_addon_obp import backpropagate\n", + "\n", + "max_slices = 6\n", + "l1_bp_obs, l1_remaining_slices, l1_metadata = backpropagate(\n", + " obs,\n", + " slices[-max_slices:],\n", + " truncation_error_budget=l1_truncation_error_budget,\n", + ")\n", + "l1_reduced_circuit = combine_slices(\n", + " slices[:-max_slices] + l1_remaining_slices\n", + ")\n", + "print(\n", + " f\"Backpropagated {max_slices - len(l1_remaining_slices)} circuit slices.\"\n", + ")\n", + "print(\n", + " f\"New observable contains {len(l1_bp_obs)} terms and {len(l1_bp_obs.group_commuting(qubit_wise=True))} commuting groups.\"\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "9f2782f8-1e93-4319-af26-dc467d7ed459", + "metadata": {}, + "source": [ + "We can now compute the expectation value of the backpropagated observable, as well as the error with respect to the exact reference:" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "5be8c457-6569-452d-8502-0fc5e39bf918", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "9.317869899338842 0.00032796052330397174\n" + ] + } + ], + "source": [ + "estimator = StatevectorEstimator()\n", + "job = estimator.run([(l1_reduced_circuit, l1_bp_obs)])\n", + "res = job.result()\n", + "l1_exp = res[0].data.evs\n", + "l1_error = exact_exp - l1_exp\n", + "print(l1_exp, l1_error)" + ] + }, + { + "cell_type": "markdown", + "id": "c0eccc5b-dc71-45b3-ad79-3d3dcb491f2d", + "metadata": {}, + "source": [ + "Finally, we can plot the error incurred during the backpropagation of each slice, as well as the accumulated error.\n", + "The accumulated error is the sum of the slice errors. We can see that the accumulated error is a very loose upper bound to the actual error." + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "ff72e77f-e2c0-4cce-8575-c5aa587f78fb", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "\"Output" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "from matplotlib import pyplot as plt\n", + "from qiskit_addon_obp.utils.visualization import (\n", + " plot_accumulated_error,\n", + " plot_slice_errors,\n", + ")\n", + "\n", + "fig, axes = plt.subplots(1, 2, figsize=(14, 5))\n", + "axes[1].plot([6], [l1_error], \"x\", color=\"red\", label=\"actual error\")\n", + "plot_slice_errors(l1_metadata, axes[0])\n", + "plot_accumulated_error(l1_metadata, axes[1])" + ] + }, + { + "cell_type": "markdown", + "id": "10dd1139-c597-43c2-9f58-0a0988de768f", + "metadata": {}, + "source": [ + "## Use the L2 norm\n", + "\n", + "One can argue that the L2 norm is a better approximation of the incurred error than the L1 norm.\n", + "That is because we can assume the quantum state $|\\psi\\rangle$ to be drawn from a Haar random ensemble, in which case the incurred error follows a distribution with a vanishing mean and a variance that can be approximately bound by the L2 norm:\n", + "$$\n", + "|\\langle\\psi|\\Delta|\\psi\\rangle| \\lesssim \\left( \\sum_{P\\in\\mathcal{T}} |c_P|^2 \\right)^{1/2}\n", + "$$\n", + "While the bound is not rigorous, it will only be violated in pathological cases." + ] + }, + { + "cell_type": "markdown", + "id": "f302d808-b341-49cb-8bbd-b03f2bfc6dd6", + "metadata": {}, + "source": [ + "We again backpropagate six slices of the example circuit, using a maximum error per slice of `0.001` (this time, interpreted on the L2 norm)." + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "c7b7e21f-22e4-479d-954c-39400974f8c1", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "TruncationErrorBudget(per_slice_budget=[0.001], max_error_total=inf, p_norm=2)\n" + ] + } + ], + "source": [ + "l2_truncation_error_budget = setup_budget(max_error_per_slice=0.001, p_norm=2)\n", + "print(l2_truncation_error_budget)" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "e92680c5-497e-47e0-ae0f-69465028dd66", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Backpropagated 6 circuit slices.\n", + "New observable contains 84 terms and 6 commuting groups.\n" + ] + } + ], + "source": [ + "max_slices = 6\n", + "l2_bp_obs, l2_remaining_slices, l2_metadata = backpropagate(\n", + " obs,\n", + " slices[-max_slices:],\n", + " truncation_error_budget=l2_truncation_error_budget,\n", + ")\n", + "l2_reduced_circuit = combine_slices(\n", + " slices[:-max_slices] + l2_remaining_slices\n", + ")\n", + "print(\n", + " f\"Backpropagated {max_slices - len(l2_remaining_slices)} circuit slices.\"\n", + ")\n", + "print(\n", + " f\"New observable contains {len(l2_bp_obs)} terms and {len(l2_bp_obs.group_commuting(qubit_wise=True))} commuting groups.\"\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "a05f992a-3a38-4912-9e1b-bcd40463c35e", + "metadata": {}, + "source": [ + "Again, we compute the expectation value of the backpropagated observable and the error with respect to the exact reference:" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "id": "73fe737a-c3b0-4639-83dc-d614521dd77a", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "9.317829770853422 0.00036808900872387085\n" + ] + } + ], + "source": [ + "estimator = StatevectorEstimator()\n", + "job = estimator.run([(l2_reduced_circuit, l2_bp_obs)])\n", + "res = job.result()\n", + "l2_exp = res[0].data.evs\n", + "l2_error = exact_exp - l2_exp\n", + "print(l2_exp, l2_error)" + ] + }, + { + "cell_type": "markdown", + "id": "81fd099c-f144-4c59-9b76-72fd8b06d8ad", + "metadata": {}, + "source": [ + "Plotting the incurred errors per slice and the accumulated error yields a similar picture as before." + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "id": "fe7f454c-7d79-4c61-b1dd-6a98564fb5f1", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "\"Output" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "fig, axes = plt.subplots(1, 2, figsize=(14, 5))\n", + "axes[1].plot([6], [l2_error], \"x\", color=\"red\", label=\"actual error\")\n", + "plot_slice_errors(l2_metadata, axes[0])\n", + "plot_accumulated_error(l2_metadata, axes[1])" + ] + }, + { + "cell_type": "markdown", + "id": "9ef23a93-5c3b-48be-a02a-e666179c8c65", + "metadata": {}, + "source": [ + "Note that the accumulated error is again the sum of the single slice errors. This is another loose bound due to the Minkowski inequality, since we have to compute this bound recursively:\n", + "$$\n", + "|\\langle\\psi|\\Delta_{i}|\\psi\\rangle| \\leq |\\langle\\psi|\\tilde{\\Delta}_{i-1}|\\psi\\rangle| + \\left( \\sum_{P\\in\\mathcal{T_i}} |c_P|^2 \\right)^{1/2} = |\\langle\\psi|\\tilde{\\Delta}_{i}|\\psi\\rangle|\n", + "$$\n", + "where the new subscript $i$ indicates the current slice iteration, making $\\Delta_i$ the actual error at backpropagation iteration $i$, $\\tilde{\\Delta}_{i-1}$ the approximated truncation error from iteration $i-1$, and $\\mathcal{T}_i$ the set of Pauli terms truncated at iteration $i$." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/addons/qiskit-addon-obp/guides/index.mdx b/docs/addons/qiskit-addon-obp/guides/index.mdx new file mode 100644 index 00000000000..d10d7b702c1 --- /dev/null +++ b/docs/addons/qiskit-addon-obp/guides/index.mdx @@ -0,0 +1,13 @@ +--- +title: "OBP Guides" +description: "OBP Guides for the latest version of Operator backpropagation (OBP)" +--- + +# OBP Guides + +* [Overview](overview) +* [Quick start guide](quickstart) +* [Bound error in experiments](bound-error-using-p-norm) +* [Simulate circuits with OBP](simulating-circuits-with-obp) +* [Truncate operator terms during backpropagation](truncate-operator-terms) + diff --git a/docs/addons/qiskit-addon-obp/guides/overview.mdx b/docs/addons/qiskit-addon-obp/guides/overview.mdx new file mode 100644 index 00000000000..3d53964e88b --- /dev/null +++ b/docs/addons/qiskit-addon-obp/guides/overview.mdx @@ -0,0 +1,23 @@ +--- +title: "Overview" +description: "Overview for the latest version of Operator backpropagation (OBP)" +--- + +# Overview + +This page summarizes the guides that are available. All guides are written to focus on specific aspects of the package. Examples of end-to-end workflows can be found in the tutorials hosted on the IBM Quantum Platform. + +## Getting started + +These simple guides help you to get started quickly with the package. + +* [Quick start](quickstart) + +## Beyond the basics + +These guides provide a deeper explanation of specific concepts and components from this package. + +* [Bound error in experiments](bound-error-using-p-norm) +* [Truncate operator terms during backpropagation](truncate-operator-terms) +* [Simulate circuits with OBP](simulating-circuits-with-obp) + diff --git a/docs/addons/qiskit-addon-obp/guides/quickstart.ipynb b/docs/addons/qiskit-addon-obp/guides/quickstart.ipynb new file mode 100644 index 00000000000..aed1268c292 --- /dev/null +++ b/docs/addons/qiskit-addon-obp/guides/quickstart.ipynb @@ -0,0 +1,44 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "frontmatter", + "metadata": {}, + "source": [ + "---\n", + "title: \"Coming soon\"\n", + "description: \"Coming soon for the latest version of Operator backpropagation (OBP)\"\n", + "---" + ] + }, + { + "cell_type": "markdown", + "id": "930fb583-8eca-4613-b4df-8ecf982d4a07", + "metadata": {}, + "source": [ + "# Coming soon" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/addons/qiskit-addon-obp/guides/simulating-circuits-with-obp.ipynb b/docs/addons/qiskit-addon-obp/guides/simulating-circuits-with-obp.ipynb new file mode 100644 index 00000000000..1af27ad2729 --- /dev/null +++ b/docs/addons/qiskit-addon-obp/guides/simulating-circuits-with-obp.ipynb @@ -0,0 +1,585 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "frontmatter", + "metadata": {}, + "source": [ + "---\n", + "title: \"Classically simulating circuits with OBP\"\n", + "description: \"Classically simulating circuits with OBP for the latest version of Operator backpropagation (OBP)\"\n", + "---" + ] + }, + { + "cell_type": "markdown", + "id": "26d926db-2e2f-41ff-947e-9757a9f426d8", + "metadata": {}, + "source": [ + "# Classically simulating circuits with OBP" + ] + }, + { + "cell_type": "markdown", + "id": "7642d6db-fe6d-4506-8e49-6c840f166e2b", + "metadata": {}, + "source": [ + "In this guide, you will learn how to classically simulate `QuantumCircuit` instances to estimate expectation values entirely through the means of OBP.\n", + "\n", + "Since OBP will take an observable and backpropagate it through a given circuit, the \"simulation\" of a circuit amounts to computing the expectation value of the target observable with respect to this circuit.\n", + "As you will see later, the `qiskit-addon-obp` package is even capable of handling simple noise models, allowing you to compute noisy expectation values, too!" + ] + }, + { + "cell_type": "markdown", + "id": "2e996d79-36fd-4a71-bd6b-737fc8e44987", + "metadata": {}, + "source": [ + "## Constructing an example circuit\n", + "\n", + "For the purposes of this guide, we will use the same example circuit as in the [Pauli term truncation guide](https://qiskit.github.io/qiskit-addon-obp/how_tos/truncate_operator_terms.html):" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "b7946767-904b-422e-b076-7f956f3fdb70", + "metadata": {}, + "outputs": [], + "source": [ + "import rustworkx.generators\n", + "from qiskit.synthesis import LieTrotter\n", + "from qiskit_addon_utils.problem_generators import (\n", + " PauliOrderStrategy,\n", + " generate_time_evolution_circuit,\n", + " generate_xyz_hamiltonian,\n", + ")\n", + "from qiskit_addon_utils.slicing import combine_slices, slice_by_gate_types\n", + "\n", + "# we generate a linear chain of 10 qubits\n", + "num_qubits = 10\n", + "linear_chain = rustworkx.generators.path_graph(num_qubits)\n", + "\n", + "# we use an arbitrary XY model\n", + "hamiltonian = generate_xyz_hamiltonian(\n", + " linear_chain,\n", + " coupling_constants=(0.05, 0.02, 0.0),\n", + " ext_magnetic_field=(0.02, 0.08, 0.0),\n", + " pauli_order_strategy=PauliOrderStrategy.InteractionThenColor,\n", + ")\n", + "# we evolve for some time\n", + "circuit = generate_time_evolution_circuit(\n", + " hamiltonian, synthesis=LieTrotter(reps=3), time=2.0\n", + ")\n", + "# slice the circuit by gate type\n", + "slices = slice_by_gate_types(circuit)" + ] + }, + { + "cell_type": "markdown", + "id": "63bcf4d0-7abe-4467-bc2b-f95d8d66dee5", + "metadata": {}, + "source": [ + "However, the above is purely the circuit describing the time evolution under a chosen Hamiltonian.\n", + "We also need an initial state to start from, with respect to which we compute the expectation values of our observable.\n", + "\n", + "Of course, we could choose the all-zero (or vacuum) state as our initial state, but to show how one would insert their own initial state, we choose a different one below.\n", + "\n", + "One possibility, would be to prepend the initial state to our time-evolution circuit above: `circuit.compose(initial_state, front=True)`.\n", + "But since we have already sliced our `circuit`, it is easier to simply insert the initial state as the first slice, which we do below.\n", + "\n", + "In this way, we can simply replace the first slice with another initial state, if we want to exchange that in the future, without having to recompute our slices." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "ffaa07e2-af75-4424-9e7b-61c81b3bb9ff", + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit.circuit import QuantumCircuit\n", + "\n", + "initial_state = QuantumCircuit(num_qubits)\n", + "for i in range(0, num_qubits, 2):\n", + " initial_state.x(i)\n", + "\n", + "slices.insert(0, initial_state)" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "8758f393-8691-4116-94ca-1185c6188bb4", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "\"Output" + ] + }, + "execution_count": 3, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "# for visualization purposes only, we recombine the slices with barriers between them and draw the resulting circuit\n", + "combine_slices(slices, include_barriers=True).draw(\"mpl\", fold=50, scale=0.6)" + ] + }, + { + "cell_type": "markdown", + "id": "bc9d51da-0a4e-46e2-8a5a-3501456aeb81", + "metadata": {}, + "source": [ + "## Simulating a noiseless expectation value" + ] + }, + { + "cell_type": "markdown", + "id": "1125cb39-4eda-4928-86b2-24e1872ed87e", + "metadata": {}, + "source": [ + "As our target observable, we choose the `ZZ` observable on the central qubits:" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "ee438fc3-8196-43d9-bcdb-956fd9ec4cf4", + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit.quantum_info import SparsePauliOp\n", + "\n", + "obs = SparsePauliOp(\"IIIIZZIIII\")" + ] + }, + { + "cell_type": "markdown", + "id": "d06f10b0-683e-476e-9ac3-5c110364a0c8", + "metadata": {}, + "source": [ + "At this point, we are already set to classically simulate the expectation value using OBP.\n", + "To do so, we simply provide the _all_ the slices to the `backpropagate` method, like so:" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "6402f5f5-08e0-4d05-ab2b-0c8863e9f966", + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit_addon_obp import backpropagate\n", + "\n", + "vacuum_state_obs, _, metadata = backpropagate(obs, slices)" + ] + }, + { + "cell_type": "markdown", + "id": "7b2d555e-7fab-49f1-82d4-74a770f1be75", + "metadata": {}, + "source": [ + "We have now backpropagated our target observable `obs` through the _entire_ circuit (**including** the `initial_state` which we placed on `slices[0]`) resulting in a new `SparsePauliOp` whose expectation value we obtain by projecting it on the _vacuum state_ (`|00...00>`).\n", + "\n", + "This can be achieved in a straight forward manner by summing up the coefficients of all Pauli terms defined in the computational basis:" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "63ae0edc-e8f6-467b-896a-ddd451d40a9a", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "np.complex128(-0.8285688012239535+4.9487770271457865e-20j)" + ] + }, + "execution_count": 6, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "vacuum_state_obs.coeffs[~vacuum_state_obs.paulis.x.any(axis=1)].sum()" + ] + }, + { + "cell_type": "markdown", + "id": "107a0d89-323c-469b-8442-5e3f48169cd4", + "metadata": {}, + "source": [ + "As a sanity check (and to prove that this works) we can compare our result against Qiskit's `Statevector`:" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "f3cb999d-688a-4e82-bf12-d958ef0e2ec0", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "np.complex128(-0.8285687255430366+0j)" + ] + }, + "execution_count": 7, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from qiskit.quantum_info import Statevector\n", + "\n", + "Statevector(combine_slices(slices)).expectation_value(obs)" + ] + }, + { + "cell_type": "markdown", + "id": "02207cde-e89e-4cf6-8b3e-727a750d245c", + "metadata": {}, + "source": [ + "### Some notes on performance\n", + "\n", + "The computational efficiency of the `backpropagate` call above will heavily depend on many things, including:\n", + "- the structure of the `circuit`\n", + "- the method of slicing the circuit\n", + "- the target observable\n", + "- the truncation parameters\n", + "\n", + "Since the `backpropagate` method simplifies the observable after every _slice_ has been applied, the number of gates in a slice can dramatically influence the computational burden.\n", + "The most aggressive strategy in terms of operator simplification can be achieved by slicing your circuit into slices of individual gates.\n", + "\n", + "Additionally, you can leverage all of the truncation mechanism built into the `backpropagate` method.\n", + "We did not do so above, effectively resulting in an exact expectation value, but you can learn how to in the [Pauli term truncation guide](https://qiskit.github.io/qiskit-addon-obp/how_tos/truncate_operator_terms.html)." + ] + }, + { + "cell_type": "markdown", + "id": "1ba37abf-0f78-4053-8995-2ab8340237ab", + "metadata": {}, + "source": [ + "## Simulating a noisy expectation value" + ] + }, + { + "cell_type": "markdown", + "id": "3a5e753b-c479-42d9-84d0-5ce4860ec091", + "metadata": {}, + "source": [ + "The `qiskit-addon-obp` package also supports handling of noise models in the form of `PauliLindbladError`s.\n", + "This is especially useful when you have characterized the noise model of the 2-qubit layers in your circuit, for example using the [`NoiseLearner`](/api/qiskit-ibm-runtime/noise-learner-noise-learner).\n", + "\n", + "In this section, you will see how you can use the `LayerError` objects returned by the `NoiseLearner` to compute noisy expectation values using OBP." + ] + }, + { + "cell_type": "markdown", + "id": "2d50dbf1-3abd-4945-bed9-1ed49758e9cc", + "metadata": {}, + "source": [ + "### Obtaining a noise model\n", + "\n", + "Normally, you would execute the `NoiseLearner` to obtain a noise model of your specific circuit.\n", + "To avoid complexity (and randomness) in this tutorial, we will refrain from doing so, and instead hard-code some noise model for our circuit below.\n", + "\n", + "However, we make sure that the structure of our data matches that of the [`NoiseLearnerResult`](/api/qiskit-ibm-runtime/noise-learner-result)." + ] + }, + { + "cell_type": "markdown", + "id": "54a7aba1-a7ee-4d0f-b95b-095158511ce0", + "metadata": {}, + "source": [ + "In its current (non-transpiled) form, our circuit contains 4 unique layers of 2-qubit gates:\n", + "- `slices[1]`: which has `Rxx` gates acting on all odd pairs of qubits\n", + "- `slices[2]`: which has `Rxx` gates acting on all even pairs of qubits\n", + "- `slices[3]`: which has `Ryy` gates acting on all odd pairs of qubits\n", + "- `slices[4]`: which has `Ryy` gates acting on all even pairs of qubits\n", + "\n", + "In the cell below, we manually construct 4 `LayerError` instances for each one of these layers with some randomized error rates." + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "e7a3b1f9-b60c-4735-8d6b-5151a7c5b92b", + "metadata": {}, + "outputs": [], + "source": [ + "import numpy as np\n", + "from qiskit.quantum_info import PauliList\n", + "from qiskit_ibm_runtime.utils.noise_learner_result import (\n", + " LayerError,\n", + " PauliLindbladError,\n", + ")\n", + "\n", + "# fmt: off\n", + "pauli_errors_even = ['IIIIIIIIIX', 'IIIIIIIIIY', 'IIIIIIIIIZ', 'IIIIIIIIXI', 'IIIIIIIIXX', 'IIIIIIIIXY', 'IIIIIIIIXZ', 'IIIIIIIIYI', 'IIIIIIIIYX', 'IIIIIIIIYY', 'IIIIIIIIYZ', 'IIIIIIIIZI', 'IIIIIIIIZX', 'IIIIIIIIZY', 'IIIIIIIIZZ', 'IIIIIIIXII', 'IIIIIIIXXI', 'IIIIIIIXYI', 'IIIIIIIXZI', 'IIIIIIIYII', 'IIIIIIIYXI', 'IIIIIIIYYI', 'IIIIIIIYZI', 'IIIIIIIZII', 'IIIIIIIZXI', 'IIIIIIIZYI', 'IIIIIIIZZI', 'IIIIIIXIII', 'IIIIIIXXII', 'IIIIIIXYII', 'IIIIIIXZII', 'IIIIIIYIII', 'IIIIIIYXII', 'IIIIIIYYII', 'IIIIIIYZII', 'IIIIIIZIII', 'IIIIIIZXII', 'IIIIIIZYII', 'IIIIIIZZII', 'IIIIIXIIII', 'IIIIIXXIII', 'IIIIIXYIII', 'IIIIIXZIII', 'IIIIIYIIII', 'IIIIIYXIII', 'IIIIIYYIII', 'IIIIIYZIII', 'IIIIIZIIII', 'IIIIIZXIII', 'IIIIIZYIII', 'IIIIIZZIII', 'IIIIXIIIII', 'IIIIXXIIII', 'IIIIXYIIII', 'IIIIXZIIII', 'IIIIYIIIII', 'IIIIYXIIII', 'IIIIYYIIII', 'IIIIYZIIII', 'IIIIZIIIII', 'IIIIZXIIII', 'IIIIZYIIII', 'IIIIZZIIII', 'IIIXIIIIII', 'IIIXXIIIII', 'IIIXYIIIII', 'IIIXZIIIII', 'IIIYIIIIII', 'IIIYXIIIII', 'IIIYYIIIII', 'IIIYZIIIII', 'IIIZIIIIII', 'IIIZXIIIII', 'IIIZYIIIII', 'IIIZZIIIII', 'IIXIIIIIII', 'IIXXIIIIII', 'IIXYIIIIII', 'IIXZIIIIII', 'IIYIIIIIII', 'IIYXIIIIII', 'IIYYIIIIII', 'IIYZIIIIII', 'IIZIIIIIII', 'IIZXIIIIII', 'IIZYIIIIII', 'IIZZIIIIII', 'IXIIIIIIII', 'IXXIIIIIII', 'IXYIIIIIII', 'IXZIIIIIII', 'IYIIIIIIII', 'IYXIIIIIII', 'IYYIIIIIII', 'IYZIIIIIII', 'IZIIIIIIII', 'IZXIIIIIII', 'IZYIIIIIII', 'IZZIIIIIII', 'XIIIIIIIII', 'XXIIIIIIII', 'XYIIIIIIII', 'XZIIIIIIII', 'YIIIIIIIII', 'YXIIIIIIII', 'YYIIIIIIII', 'YZIIIIIIII', 'ZIIIIIIIII', 'ZXIIIIIIII', 'ZYIIIIIIII', 'ZZIIIIIIII']\n", + "pauli_errors_odd = ['IIIIIIIIXI', 'IIIIIIIIYI', 'IIIIIIIIZI', 'IIIIIIIXII', 'IIIIIIIXXI', 'IIIIIIIXYI', 'IIIIIIIXZI', 'IIIIIIIYII', 'IIIIIIIYXI', 'IIIIIIIYYI', 'IIIIIIIYZI', 'IIIIIIIZII', 'IIIIIIIZXI', 'IIIIIIIZYI', 'IIIIIIIZZI', 'IIIIIIXIII', 'IIIIIIXXII', 'IIIIIIXYII', 'IIIIIIXZII', 'IIIIIIYIII', 'IIIIIIYXII', 'IIIIIIYYII', 'IIIIIIYZII', 'IIIIIIZIII', 'IIIIIIZXII', 'IIIIIIZYII', 'IIIIIIZZII', 'IIIIIXIIII', 'IIIIIXXIII', 'IIIIIXYIII', 'IIIIIXZIII', 'IIIIIYIIII', 'IIIIIYXIII', 'IIIIIYYIII', 'IIIIIYZIII', 'IIIIIZIIII', 'IIIIIZXIII', 'IIIIIZYIII', 'IIIIIZZIII', 'IIIIXIIIII', 'IIIIXXIIII', 'IIIIXYIIII', 'IIIIXZIIII', 'IIIIYIIIII', 'IIIIYXIIII', 'IIIIYYIIII', 'IIIIYZIIII', 'IIIIZIIIII', 'IIIIZXIIII', 'IIIIZYIIII', 'IIIIZZIIII', 'IIIXIIIIII', 'IIIXXIIIII', 'IIIXYIIIII', 'IIIXZIIIII', 'IIIYIIIIII', 'IIIYXIIIII', 'IIIYYIIIII', 'IIIYZIIIII', 'IIIZIIIIII', 'IIIZXIIIII', 'IIIZYIIIII', 'IIIZZIIIII', 'IIXIIIIIII', 'IIXXIIIIII', 'IIXYIIIIII', 'IIXZIIIIII', 'IIYIIIIIII', 'IIYXIIIIII', 'IIYYIIIIII', 'IIYZIIIIII', 'IIZIIIIIII', 'IIZXIIIIII', 'IIZYIIIIII', 'IIZZIIIIII', 'IXIIIIIIII', 'IXXIIIIIII', 'IXYIIIIIII', 'IXZIIIIIII', 'IYIIIIIIII', 'IYXIIIIIII', 'IYYIIIIIII', 'IYZIIIIIII', 'IZIIIIIIII', 'IZXIIIIIII', 'IZYIIIIIII', 'IZZIIIIIII']\n", + "# fmt: on\n", + "\n", + "np.random.seed(42)\n", + "\n", + "layer_error_odd_xx = LayerError(\n", + " circuit=slices[1],\n", + " qubits=list(range(num_qubits)),\n", + " error=PauliLindbladError(\n", + " PauliList(pauli_errors_odd),\n", + " 0.0001 + 0.0004 * np.random.rand(len(pauli_errors_odd)),\n", + " ),\n", + ")\n", + "\n", + "layer_error_even_xx = LayerError(\n", + " circuit=slices[2],\n", + " qubits=list(range(num_qubits)),\n", + " error=PauliLindbladError(\n", + " PauliList(pauli_errors_even),\n", + " 0.0001 + 0.0004 * np.random.rand(len(pauli_errors_even)),\n", + " ),\n", + ")\n", + "\n", + "layer_error_odd_yy = LayerError(\n", + " circuit=slices[3],\n", + " qubits=list(range(num_qubits)),\n", + " error=PauliLindbladError(\n", + " PauliList(pauli_errors_odd),\n", + " 0.0001 + 0.0004 * np.random.rand(len(pauli_errors_odd)),\n", + " ),\n", + ")\n", + "\n", + "layer_error_even_yy = LayerError(\n", + " circuit=slices[4],\n", + " qubits=list(range(num_qubits)),\n", + " error=PauliLindbladError(\n", + " PauliList(pauli_errors_even),\n", + " 0.0001 + 0.0004 * np.random.rand(len(pauli_errors_even)),\n", + " ),\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "a9dff7ad-2c7a-4fc2-b7b5-5aa1a0e9b9db", + "metadata": {}, + "source": [ + "If you would have used the `NoiseLearner` to identify the unique 2-qubit gate layers of your circuit and characterize their noise, you would obtain a `NoiseLearnerResult` object.\n", + "This result would contain a list of `LayerError` objects, just like the ones we have manually constructed above.\n", + "\n", + "For each unique 2-qubit layer, the `LayerError` contains:\n", + "- the `QuantumCircuit` representing that 2-qubit gate layer\n", + "- the qubit indices which this circuit is acting upon\n", + "- the `PauliLindbladError` which represents the characterized noise model of this layer\n", + "\n", + "The `PauliLindbladError` will contain two objects:\n", + "- the list of Pauli errors that have been characterized\n", + "- the error rates corresponding to each one of those Pauli errors\n", + "\n", + "Normally, the list of Pauli errors will be sparse. More specifically, it will contain the single-qubit Pauli errors on all qubits that have gates acting upon them as well as the two-qubit Pauli errors on all those qubits that are connected." + ] + }, + { + "cell_type": "markdown", + "id": "9c3a1a9d-6fcb-4345-b9ba-e86e2e362a7e", + "metadata": {}, + "source": [ + "### Inserting the noisy layers into our circuit\n", + "\n", + "In the previous section, we have specifically constructed one `LayerError` for each of our known unique 2-qubit gate layers.\n", + "This means, we know which `LayerError` matches a specific one of our slices exactly.\n", + "\n", + "Normally, when using the `LayerError`, you will need to figure out what the unique 2-qubit gate layer is, and where it occurs inside of your circuit.\n", + "You will then need to adjust your `circuit` and/or `slices` to insert the `LayerError` accordingly.\n", + "How to do this in the general case, is beyond the scope of this how-to guide.\n", + "**TODO: link to external documentation, once it exists!**" + ] + }, + { + "cell_type": "markdown", + "id": "dcb5937e-83d8-41ab-a526-d6677201c8f4", + "metadata": {}, + "source": [ + "Here, our life is simpler because we know which slice a `LayerError` corresponds to.\n", + "Therefore, it is now just a matter of inserting new slices to represent the noise.\n", + "\n", + "Note, that we must wrap each `PauliLindbladError` from `LayerError.error` in a `PauliLindbladErrorInstruction` for it to be a valid `QuantumCircuit` instruction." + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "1f5c4655-f6af-439f-8475-0ecf0c673de5", + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit_addon_obp.utils.noise import PauliLindbladErrorInstruction\n", + "\n", + "noisy_slices = []\n", + "for slice_ in slices:\n", + " if slice_ == layer_error_even_xx.circuit:\n", + " noisy_slices.append(\n", + " QuantumCircuit.from_instructions(\n", + " [\n", + " (\n", + " PauliLindbladErrorInstruction(\n", + " layer_error_even_xx.error\n", + " ),\n", + " slice_.qubits,\n", + " )\n", + " ]\n", + " )\n", + " )\n", + " elif slice_ == layer_error_odd_xx.circuit:\n", + " noisy_slices.append(\n", + " QuantumCircuit.from_instructions(\n", + " [\n", + " (\n", + " PauliLindbladErrorInstruction(\n", + " layer_error_odd_xx.error\n", + " ),\n", + " slice_.qubits,\n", + " )\n", + " ]\n", + " )\n", + " )\n", + " elif slice_ == layer_error_even_yy.circuit:\n", + " noisy_slices.append(\n", + " QuantumCircuit.from_instructions(\n", + " [\n", + " (\n", + " PauliLindbladErrorInstruction(\n", + " layer_error_even_yy.error\n", + " ),\n", + " slice_.qubits,\n", + " )\n", + " ]\n", + " )\n", + " )\n", + " elif slice_ == layer_error_odd_yy.circuit:\n", + " noisy_slices.append(\n", + " QuantumCircuit.from_instructions(\n", + " [\n", + " (\n", + " PauliLindbladErrorInstruction(\n", + " layer_error_odd_yy.error\n", + " ),\n", + " slice_.qubits,\n", + " )\n", + " ]\n", + " )\n", + " )\n", + " noisy_slices.append(slice_)" + ] + }, + { + "cell_type": "markdown", + "id": "b3778d94-4d04-4094-990d-a354f2062932", + "metadata": {}, + "source": [ + "We can check our work and draw the circuit below:" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "id": "dadc314d-452f-465c-a382-d54685ce3f2a", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "\"Output" + ] + }, + "execution_count": 10, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "combine_slices(noisy_slices, include_barriers=True).draw(\n", + " \"mpl\", fold=100, scale=0.8\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "10b88555-0263-4cdb-a4c1-6895d7e55a5b", + "metadata": {}, + "source": [ + "### Simulating a noisy expectation value\n", + "\n", + "At this point, classically simulating the expectation value works exactly the same as before, just" + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "id": "0e3ecb85-08c4-4fda-85e2-1000983c8842", + "metadata": {}, + "outputs": [], + "source": [ + "vacuum_state_noisy_obs, _, metadata = backpropagate(obs, noisy_slices)" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "id": "a74e9e88-2f1c-4d40-873d-bf4524e2b7fe", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "np.complex128(-0.7230801696448901+7.082755280463563e-19j)" + ] + }, + "execution_count": 12, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "vacuum_state_noisy_obs.coeffs[\n", + " ~vacuum_state_noisy_obs.paulis.x.any(axis=1)\n", + "].sum()" + ] + }, + { + "cell_type": "markdown", + "id": "7a4d2ff5-7c49-463e-8515-6fc9daa951ad", + "metadata": {}, + "source": [ + "We point out again, that multiple performance concerns should be considered.\n", + "Please go back to the [corresponding section above](#some-notes-on-performance)." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/addons/qiskit-addon-obp/guides/truncate-operator-terms.ipynb b/docs/addons/qiskit-addon-obp/guides/truncate-operator-terms.ipynb new file mode 100644 index 00000000000..4ddb0ee7bbc --- /dev/null +++ b/docs/addons/qiskit-addon-obp/guides/truncate-operator-terms.ipynb @@ -0,0 +1,947 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "frontmatter", + "metadata": {}, + "source": [ + "---\n", + "title: \"Truncate Pauli terms during backpropagation\"\n", + "description: \"Truncate Pauli terms during backpropagation for the latest version of Operator backpropagation (OBP)\"\n", + "---" + ] + }, + { + "cell_type": "markdown", + "id": "11cf5076-2777-499c-be50-531e305bf011", + "metadata": {}, + "source": [ + "# Truncate Pauli terms during backpropagation" + ] + }, + { + "cell_type": "markdown", + "id": "c1453472-3506-4008-b432-f8ef9ccbf3ee", + "metadata": {}, + "source": [ + "This guide explains how to configure the Pauli term truncation mechanism provided by the [qiskit_addon_obp.utils.truncating](/docs/api/qiskit-addon-obp/utils-truncating#module-qiskit_addon_obp.utils.truncating) module.\n", + "\n", + "Operator backpropagation (OBP) can be used to reduce the depth of quantum circuits at the cost of a more complex observable. In order to get meaningful results from OBP, one usually needs to truncate terms from their observable to prevent it from growing too large. One way to allow for deeper backpropagation into the circuit, while preventing the operator from growing too large, is to truncate terms with small coefficients, rather than adding them to the operator. Truncating terms can result in fewer quantum circuits to execute, but doing so results in some error in the final expectation value calculation, proportional to the magnitude of the truncated terms' coefficients.\n", + "\n", + "The [backpropagate](/docs/api/qiskit-addon-obp/qiskit-addon-obp#backpropagate) method takes an optional [TruncationErrorBudget](/docs/api/qiskit-addon-obp/utils-truncating#truncationerrorbudget), which configures the truncation of low-weight Pauli terms for each observable after the successful backpropagation of every slice.\n", + "The amount of terms that are truncated depends on various configuration parameters specified by the user.\n", + "As of now, only a single truncation strategy is available - the [truncate_binary_search](/docs/api/qiskit-addon-obp/utils-truncating#truncate_binary_search) method.\n", + "Given an observable and some _budget_ it will perform a binary search over the Pauli terms and coefficients within that observable to find the optimal threshold,\n", + "such that the sum of the truncated coefficients is maximal but lower than the budget.\n", + "\n", + "**Note**: By default, the L1 norm is used to evaluate and bound the truncation error; however, the `p_norm` setting enables the specification of the Lp-norm to be used.\n", + "For more information on how to use that setting, refer to the [Use different Lp-norms for Pauli term truncation](https://qiskit.github.io/qiskit-addon-obp/how_tos/bound_error_using_p_norm.html) guide." + ] + }, + { + "cell_type": "markdown", + "id": "aaf5f046-6d5e-4b6f-add7-b60604edef30", + "metadata": {}, + "source": [ + "The following examples illustrate various ways of building an [TruncationErrorBudget](/docs/api/qiskit-addon-obp/utils-truncating#truncationerrorbudget) by using the accompanying [setup_budget](/docs/api/qiskit-addon-obp/utils-truncating#setup_budget) function." + ] + }, + { + "cell_type": "markdown", + "id": "c83c0741-4a9e-4f89-92a9-4756ef133130", + "metadata": {}, + "source": [ + "## Construct an example circuit\n", + "\n", + "This guide uses the following circuit slices:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "297fc3b0-d3b4-432d-96cd-7e175b7e6a52", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "\"Output" + ] + }, + "execution_count": 1, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "import rustworkx.generators\n", + "from qiskit.synthesis import LieTrotter\n", + "from qiskit_addon_utils.problem_generators import (\n", + " PauliOrderStrategy,\n", + " generate_time_evolution_circuit,\n", + " generate_xyz_hamiltonian,\n", + ")\n", + "from qiskit_addon_utils.slicing import combine_slices, slice_by_gate_types\n", + "\n", + "# Generate a linear chain of 10 qubits\n", + "linear_chain = rustworkx.generators.path_graph(10)\n", + "\n", + "# Use an arbitrary XY model\n", + "hamiltonian = generate_xyz_hamiltonian(\n", + " linear_chain,\n", + " coupling_constants=(0.05, 0.02, 0.0),\n", + " ext_magnetic_field=(0.02, 0.08, 0.0),\n", + " pauli_order_strategy=PauliOrderStrategy.InteractionThenColor,\n", + ")\n", + "# Evolve for some time\n", + "circuit = generate_time_evolution_circuit(\n", + " hamiltonian, synthesis=LieTrotter(reps=3), time=2.0\n", + ")\n", + "# slice the circuit by gate type\n", + "slices = slice_by_gate_types(circuit)\n", + "\n", + "# for visualization purposes, recombine the slices with barriers between them and draw the resulting circuit\n", + "combine_slices(slices, include_barriers=True).draw(\"mpl\", fold=50, scale=0.6)" + ] + }, + { + "cell_type": "markdown", + "id": "89ce4fa9-06ba-4009-8594-d1b85f5e719f", + "metadata": {}, + "source": [ + "We will look at a single simple observable:" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "b168d34c-f147-4524-9af9-264f56440a55", + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit.quantum_info import SparsePauliOp\n", + "\n", + "obs = SparsePauliOp(\"IIIIIZIIII\")" + ] + }, + { + "cell_type": "markdown", + "id": "723dcf4e-1dab-4c26-a8e4-cd30b1564189", + "metadata": {}, + "source": [ + "## The simplest case: a fixed truncation budget for each slice" + ] + }, + { + "cell_type": "markdown", + "id": "5e04e5c4-1e6b-4720-9563-becbb9edc4d7", + "metadata": {}, + "source": [ + "The available budget for truncation of Pauli terms can vary at each step of the backpropagation.\n", + "To understand how this works, we first look at the simplest case of a fixed truncation budget as specified by the user.\n", + "\n", + "The most straightforward way to specify the truncation budget is by using the `max_error_per_slice` argument.\n", + "In fact, this is what is being done in the [Reducing depth of circuits with operator backpropagation](https://qiskit.github.io/qiskit-addon-obp/tutorials/01_getting_started.ipynb) tutorial. Setting `max_error_per_slice` to a `float` results in each slice being allotted a budget equaling that value.\n", + "In the example below, we set this value to `0.001` which guarantees an implicit truncation error of at most `0.018`, if all 18 slices were backpropagated.\n", + "\n", + "
\n", + "Note that any error budget remaining after backpropagating a slice and truncating terms with small coefficients will always be added to the following slice's error budget.\n", + "
" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "5f20a9b9-c3c4-43c4-9f13-fdf451958081", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "TruncationErrorBudget(per_slice_budget=[0.001], max_error_total=inf, p_norm=1)\n" + ] + } + ], + "source": [ + "from qiskit_addon_obp.utils.truncating import setup_budget\n", + "\n", + "truncation_error_budget = setup_budget(max_error_per_slice=0.001)\n", + "print(truncation_error_budget)" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "c3b8b9ef-7d5c-43dd-8cb9-90756d4753b7", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Backpropagated 11 circuit slices.\n", + "New observable contains 29 terms and 10 commuting groups.\n" + ] + } + ], + "source": [ + "from qiskit_addon_obp import backpropagate\n", + "from qiskit_addon_obp.utils.simplify import OperatorBudget\n", + "\n", + "op_budget = OperatorBudget(max_qwc_groups=10)\n", + "bp_obs, remaining_slices, metadata = backpropagate(\n", + " obs,\n", + " slices,\n", + " operator_budget=op_budget,\n", + " truncation_error_budget=truncation_error_budget,\n", + ")\n", + "reduced_circuit = combine_slices(remaining_slices)\n", + "print(f\"Backpropagated {len(slices) - len(remaining_slices)} circuit slices.\")\n", + "print(\n", + " f\"New observable contains {len(bp_obs)} terms and {len(bp_obs.group_commuting(qubit_wise=True))} commuting groups.\"\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "4a772af6-edc6-4e53-81c7-53f3b72bf58a", + "metadata": {}, + "source": [ + "We next use the [OBPMetadata](/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata) instance and the tools provided by the [visualization](/docs/api/qiskit-addon-obp/utils-visualization#module-qiskit_addon_obp.utils.visualization) module to visualize the backpropagation process.\n", + "\n", + "- **The top left plot** shows that we have enough budget to begin truncating observable terms after backpropagating the third slice. Starting from the third slice, we know that we truncate at least one term from each slice we backpropagate because we are incurring some truncation error after each slice.\n", + "- **The top right plot** shows that the error budget grows to `.003` for the third slice. We see a sharp drop in remaining budget, which means terms were truncated from the observable. This is consistent with what we inferred from the top left plot.\n", + "- **The bottom left plot** shows that as we truncate terms from our observable, our overall accumulated error is growing monotonically. This graph also confirms that no terms were truncated until after the third slice had been backpropagated.\n", + "- **The bottom right plot** shows that the number of commuting Pauli groups in our observable has grown to the specified limit of `10`. This plot also shows how backpropagating one more layer would cause our observable to outgrow the specified bound as you can see from the crossover of the black and red lines." + ] + }, + { + "cell_type": "markdown", + "id": "8ff436fa-3b52-4387-a9f4-d8d9df13c480", + "metadata": {}, + "source": [ + "
\n", + "Note that in all of these plots, the x-axis enumerates the backpropagated slices, but since OBP works on the end of the circuit, `slice 1` is the very last slice, `slice 2` is the one before that, and so on.\n", + "
" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "68f118df-6718-49b2-ba80-c37ef461f71a", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "\"Output" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "from matplotlib import pyplot as plt\n", + "from qiskit_addon_obp.utils.visualization import (\n", + " plot_accumulated_error,\n", + " plot_left_over_error_budget,\n", + " plot_num_qwc_groups,\n", + " plot_slice_errors,\n", + ")\n", + "\n", + "fig, axes = plt.subplots(2, 2, figsize=(20, 10))\n", + "plot_slice_errors(metadata, axes[(0, 0)])\n", + "plot_left_over_error_budget(metadata, axes[(0, 1)])\n", + "plot_accumulated_error(metadata, axes[(1, 0)])\n", + "plot_num_qwc_groups(metadata, axes[(1, 1)])" + ] + }, + { + "cell_type": "markdown", + "id": "523f5a81-afbc-4eee-9d66-05cc3b4a781a", + "metadata": {}, + "source": [ + "## Specify slice budget explicitly" + ] + }, + { + "cell_type": "markdown", + "id": "80f9337d-ea37-454c-ae0b-b101259568c9", + "metadata": {}, + "source": [ + "If you know how to assign a budget to each slice, such that the backpropagation performance is optimized, you might want to explicitly assign a budget for each slice. For demonstration purposes, we will assign the first three slices zero budget and use a budget of `.001` per slice for the remaining slices." + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "17ce7232-7e3a-44e4-8081-1b1b27430bad", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "TruncationErrorBudget(per_slice_budget=[0.0, 0.0, 0.0, 0.001, 0.001, 0.001, 0.001, 0.001, 0.001, 0.001, 0.001, 0.001, 0.001, 0.001, 0.001, 0.001, 0.001, 0.001], max_error_total=inf, p_norm=1)\n" + ] + } + ], + "source": [ + "# Zero out the first 3 slices' budgets\n", + "max_error_per_slice = [0.0] * 3 + [0.001] * (len(slices) - 3)\n", + "\n", + "truncation_error_budget = setup_budget(\n", + " max_error_per_slice=max_error_per_slice\n", + ")\n", + "print(truncation_error_budget)" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "7cd711a7-1aea-4b45-a46a-63d771230969", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Backpropagated 11 circuit slices.\n", + "New observable contains 32 terms and 10 commuting groups.\n" + ] + } + ], + "source": [ + "bp_obs, remaining_slices, metadata = backpropagate(\n", + " obs,\n", + " slices,\n", + " operator_budget=op_budget,\n", + " truncation_error_budget=truncation_error_budget,\n", + ")\n", + "reduced_circuit = combine_slices(remaining_slices)\n", + "print(f\"Backpropagated {len(slices) - len(remaining_slices)} circuit slices.\")\n", + "print(\n", + " f\"New observable contains {len(bp_obs)} terms and {len(bp_obs.group_commuting(qubit_wise=True))} commuting groups.\"\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "3e853723-454b-4c69-b9c5-180eb1b2e6c2", + "metadata": {}, + "source": [ + "Removing the budget from the first three layers resulted in no terms being truncated until after the fourth layer, as can be confirmed in three of these plots. What might be somewhat surprising is that although the fourth slice had no leftover budget passed to it, a term was still truncated by using the allocated `.001` budget. This is obvious from the **top left** plot, but can also be observed in the **top right** plot, as the leftover budget curve flattens between slices three and four. Another notable detail is that at least one term was truncated from this point on, the same as in the previous example.\n", + "\n", + "The key takeaway is that although we incurred less truncation error in the second example due to zeroing out some slices' budgets, we were able to backpropagate the same number of slices, and our observable contains the same number of commuting Pauli groups. We can confirm that the bound on our error is smaller in the second example by inspecting the **bottom left** plot." + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "b7167f80-5d29-4c32-be97-cba733f18b1d", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "\"Output" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "fig, axes = plt.subplots(2, 2, figsize=(20, 10))\n", + "plot_slice_errors(metadata, axes[(0, 0)])\n", + "plot_left_over_error_budget(metadata, axes[(0, 1)])\n", + "plot_accumulated_error(metadata, axes[(1, 0)])\n", + "plot_num_qwc_groups(metadata, axes[(1, 1)])" + ] + }, + { + "cell_type": "markdown", + "id": "f03a92ee-e9a0-4707-b23a-ebdc3c9f35a3", + "metadata": {}, + "source": [ + "## Specify the budget cyclically" + ] + }, + { + "cell_type": "markdown", + "id": "62f0ea1f-eaec-408d-99df-25a8647c1eb9", + "metadata": {}, + "source": [ + "If you have a circuit with some repeatable pattern, such as a Trotter circuit, you might want to specify a budget for that repeated subset of slices and have that budget used for all of the following repetitions of those slices.\n", + "\n", + "More concretely, the example circuit we are using has six slices that are repeated three times, for a total of 18 slices. We will arbitrarily assign zero budget to the single-qubit and `RYY` layers, and `.003` budget to each of the `RXX` layers. We will observe how specifying the budget as a length-6 sequence causes the budget to be applied to all 18 slices cyclically.\n", + "\n", + "
\n", + "Again, note that the slices are backpropagated in reverse order (that is, starting at the end). Therefore, the first entry in our cyclic budget actually gets used for the last slice, the second entry for the slice before that, and so on.\n", + "
" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "4f37a576-5a61-4589-a896-8304056d0e19", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "TruncationErrorBudget(per_slice_budget=[0.0, 0.0, 0.0, 0.0, 0.003, 0.003], max_error_total=inf, p_norm=1)\n" + ] + } + ], + "source": [ + "# Specify a length-6 per-slice budget.\n", + "# This will be cycled over three times to be applied to the 18 slices\n", + "max_error_per_slice = [0.0] * 4 + [0.003] * 2\n", + "\n", + "truncation_error_budget = setup_budget(\n", + " max_error_per_slice=max_error_per_slice\n", + ")\n", + "print(truncation_error_budget)" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "id": "7f78cfe4-13e4-472c-b6cc-9d1e867cbd9c", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Backpropagated 13 circuit slices.\n", + "New observable contains 49 terms and 14 commuting groups.\n" + ] + } + ], + "source": [ + "op_budget = OperatorBudget(max_qwc_groups=20)\n", + "bp_obs, remaining_slices, metadata = backpropagate(\n", + " obs,\n", + " slices,\n", + " operator_budget=op_budget,\n", + " truncation_error_budget=truncation_error_budget,\n", + ")\n", + "reduced_circuit = combine_slices(remaining_slices)\n", + "print(f\"Backpropagated {len(slices) - len(remaining_slices)} circuit slices.\")\n", + "print(\n", + " f\"New observable contains {len(bp_obs)} terms and {len(bp_obs.group_commuting(qubit_wise=True))} commuting groups.\"\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "3511206b-2972-41ba-b981-6c20ccb7712b", + "metadata": {}, + "source": [ + "As seen in the **top left** and **bottom left** images, no truncation was performed over the first four slices since they were allocated no error budget. Slices five and six had some of their terms truncated as budget became available.\n", + "\n", + "As seen in the **top left** image, a relatively large amount of error was incurred after backpropagating slice seven, even though that slice was allocated no budget. This is because only about `.002` of the `.006` total budget allocated to slices five and six was used, so the remaining was forwarded to slice seven and mostly expended, as seen in the **top right** image.\n", + "\n", + "The **top left** and **top right** images show that the small amount of leftover budget is used up between slices 8-10, and new budget becomes available in slice 11, as expected. The **top left**, **top right**, and **bottom left** images all demonstrate the cyclical behavior of the `max_error_per_slice` argument when its length is less than the number of slices. This cyclical behavior would have continued through all the slices, but the `max_qwc_groups` stopping criteria was reached after backpropagating 13 slices, as seen in the **bottom right** image.\n", + "\n", + "Also interesting is that the number of Pauli groups actually drops after the second round of budget becomes available at slice 11. This is because there were groups with small coefficients that could not be truncated until there was more budget after backpropagating slice 11, so they accumulated in the observable for several iterations. This case also highlights that `max_qwc_groups` must be _exceeded_ for the algorithm to terminate." + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "id": "4c36768e-03e7-4e1b-81b3-59b6e9eab43e", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "\"Output" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "fig, axes = plt.subplots(2, 2, figsize=(20, 10))\n", + "plot_slice_errors(metadata, axes[(0, 0)])\n", + "plot_left_over_error_budget(metadata, axes[(0, 1)])\n", + "plot_accumulated_error(metadata, axes[(1, 0)])\n", + "plot_num_qwc_groups(metadata, axes[(1, 1)])" + ] + }, + { + "cell_type": "markdown", + "id": "269536c5-8ba4-48da-8e99-6b8ce3a52bd0", + "metadata": {}, + "source": [ + "## Cap the total error\n", + "\n", + "In addition to specifying the per-slice error budget, one can specify the maximum amount of error to incur from truncation. Once that limit is hit, no more truncation will be performed; however, backpropagation will continue until the observable becomes too large and one of the stopping criteria is met.\n", + "\n", + "We next re-run the above experiment, setting a cap on `max_error_total` such that the error budget is expended after backpropagating slice seven." + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "id": "8ef6a100-fb4b-4b66-be6e-a094db2c29d4", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "TruncationErrorBudget(per_slice_budget=[0.0, 0.0, 0.0, 0.0, 0.003, 0.003], max_error_total=0.006, p_norm=1)\n" + ] + } + ], + "source": [ + "# Specify a length-6 per-slice budget.\n", + "# This will be cycled over 3 times to be applied to the 18 slices\n", + "max_error_per_slice = [0.0] * 4 + [0.003] * 2\n", + "\n", + "truncation_error_budget = setup_budget(\n", + " max_error_per_slice=max_error_per_slice, max_error_total=0.006\n", + ")\n", + "print(truncation_error_budget)" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "id": "c58bccd5-aa40-482f-acaf-4ef50d420053", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Backpropagated 10 circuit slices.\n", + "New observable contains 67 terms and 20 commuting groups.\n" + ] + } + ], + "source": [ + "bp_obs, remaining_slices, metadata = backpropagate(\n", + " obs,\n", + " slices,\n", + " operator_budget=op_budget,\n", + " truncation_error_budget=truncation_error_budget,\n", + ")\n", + "reduced_circuit = combine_slices(remaining_slices)\n", + "print(f\"Backpropagated {len(slices) - len(remaining_slices)} circuit slices.\")\n", + "print(\n", + " f\"New observable contains {len(bp_obs)} terms and {len(bp_obs.group_commuting(qubit_wise=True))} commuting groups.\"\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "dadb77a5-00d7-427d-921b-4a005f5ab36f", + "metadata": {}, + "source": [ + "As expected, our truncation error caps out at `.006` (**bottom left** chart). It is notable that in this run we were not able to backpropagate slice 11. This is because we did not have enough budget to truncate terms and the number of commuting Pauli groups grew past the limit of `20`, as seen in the **bottom right** image." + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "id": "69c9069a-9038-4319-8dc6-37a1be973ebf", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "\"Output" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "fig, axes = plt.subplots(2, 2, figsize=(20, 10))\n", + "plot_slice_errors(metadata, axes[(0, 0)])\n", + "plot_left_over_error_budget(metadata, axes[(0, 1)])\n", + "plot_accumulated_error(metadata, axes[(1, 0)])\n", + "plot_num_qwc_groups(metadata, axes[(1, 1)])" + ] + }, + { + "cell_type": "markdown", + "id": "2049d223-1b91-4042-ba98-a86f7a59483c", + "metadata": {}, + "source": [ + "It may be desirable to simply cap the overall budget with `max_error_total` without specifying `max_error_per_slice`." + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "id": "fac59f4f-3528-49c1-9d4d-9be98d2c7d78", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "TruncationErrorBudget(per_slice_budget=[0.018], max_error_total=0.018, p_norm=1)\n" + ] + } + ], + "source": [ + "truncation_error_budget = setup_budget(max_error_total=0.018)\n", + "print(truncation_error_budget)" + ] + }, + { + "cell_type": "markdown", + "id": "20c55e75-f619-4ac9-aecd-29491867ab82", + "metadata": {}, + "source": [ + "The output of the cell above might be slightly surprising because the `per_slice_budget` is set to the `max_error_total`. This indicates that the entire available budget will be consumed **greedily**.\n", + "You can think of it this way: the entire budget is available to each slice (because we loop over the `per_slice_budget`). But any budget that has already been consumed will be deducted from the budget that is available at that given point in the algorithm." + ] + }, + { + "cell_type": "code", + "execution_count": 16, + "id": "5d65a057-eb5e-4308-b84d-82bfbea06989", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Backpropagated 9 circuit slices.\n", + "New observable contains 25 terms and 9 commuting groups.\n" + ] + } + ], + "source": [ + "op_budget = OperatorBudget(max_qwc_groups=10)\n", + "bp_obs, remaining_slices, metadata = backpropagate(\n", + " obs,\n", + " slices,\n", + " operator_budget=op_budget,\n", + " truncation_error_budget=truncation_error_budget,\n", + ")\n", + "reduced_circuit = combine_slices(remaining_slices)\n", + "print(f\"Backpropagated {len(slices) - len(remaining_slices)} circuit slices.\")\n", + "print(\n", + " f\"New observable contains {len(bp_obs)} terms and {len(bp_obs.group_commuting(qubit_wise=True))} commuting groups.\"\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "a77ceb1e-bc6d-462d-aebe-ec478d312233", + "metadata": {}, + "source": [ + "The **top right** image shows how the entire `.018` error budget is made available to the first slice. No truncation is performed until the third slice, so the leftover budget remains constant. The budget monotonically decreases, as the full budget is made available to each backpropagated slice until it is expended.\n", + "\n", + "It is notable that this experiment yielded two fewer backpropagated slices compared to the first experiment in this notebook, which is almost identical. This demonstrates that for some problems, distributing the budget evenly might be optimal. For other problems, allowing slices to greedily expend the full budget might yield better performance." + ] + }, + { + "cell_type": "code", + "execution_count": 17, + "id": "51d36d7e-0bd5-4388-bbb8-6831bf1f02e6", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "\"Output" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "fig, axes = plt.subplots(2, 2, figsize=(20, 10))\n", + "plot_slice_errors(metadata, axes[(0, 0)])\n", + "plot_left_over_error_budget(metadata, axes[(0, 1)])\n", + "plot_accumulated_error(metadata, axes[(1, 0)])\n", + "plot_num_qwc_groups(metadata, axes[(1, 1)])" + ] + }, + { + "cell_type": "markdown", + "id": "8859d36c-258f-441f-a7cf-3997b9f6e8ff", + "metadata": {}, + "source": [ + "## Cap the number of backpropagated slices and the total error together\n", + "\n", + "If you don't want to distribute their error budget all the way through the circuit but you don't want to greedily expend it either, you can specify the number of slices you intend to backpropagate (`num_slices`), along with a total error budget (`max_error_total`). This will distribute the error budget uniformly (accordingly to `p_norm`) across the input slices.\n", + "\n", + "Here, we will cap the number of slices we might backpropagate at `12`, and we will keep the same total error budget." + ] + }, + { + "cell_type": "code", + "execution_count": 18, + "id": "474cf708-5447-4984-873c-5f62f81a402d", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "TruncationErrorBudget(per_slice_budget=[0.0014999999999999998], max_error_total=0.018, p_norm=1)\n" + ] + } + ], + "source": [ + "num_slices = 12\n", + "\n", + "truncation_error_budget = setup_budget(\n", + " max_error_total=0.018, num_slices=num_slices, p_norm=1\n", + ")\n", + "print(truncation_error_budget)" + ] + }, + { + "cell_type": "markdown", + "id": "1ac2fb58-db97-4c9e-9a96-fce97b52e7e2", + "metadata": {}, + "source": [ + "Now we will attempt to backpropagate the 12 slices for which we allocated some budget in the previous step. We do this by just passing in the final 12 slices in our circuit. With `p_norm=1`, each of the 12 slices has an available budget of `0.018 / num_slices = 0.0015`." + ] + }, + { + "cell_type": "code", + "execution_count": 19, + "id": "6efc92bc-3433-4ea6-a683-684205201f4f", + "metadata": {}, + "outputs": [], + "source": [ + "bp_obs, remaining_slices, metadata = backpropagate(\n", + " obs,\n", + " slices[-num_slices:],\n", + " operator_budget=op_budget,\n", + " truncation_error_budget=truncation_error_budget,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "b15c2a20-19c3-417c-b32d-173c10f13852", + "metadata": {}, + "source": [ + "Since we passed a subset of our slices (in the code ``slices[-num_slices:]``) to ``backpropagate``, we must combine the slices remaining after backpropagation with the slices that were never sent for backpropagation (in the code ``slices[:-num_slices]``).\n", + "\n", + "Once we have combined all of the remaining slices, we can use [combine_slices](/docs/api/qiskit-addon-utils/slicing#combine_slices) to generate the reduced-depth [QuantumCircuit](/docs/api/qiskit/qiskit.circuit.QuantumCircuit#html). Next, we inspect how many slices were backpropagated versus how large our observable became." + ] + }, + { + "cell_type": "code", + "execution_count": 20, + "id": "7c42256f-e7f2-40ed-999e-6a51fd9351c4", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Backpropagated 12 circuit slices.\n", + "New observable contains 29 terms and 9 commuting groups.\n" + ] + } + ], + "source": [ + "# Recombine the slices remaining after backprop with the rest of the original circuit\n", + "reduced_circuit = combine_slices(slices[:-num_slices] + remaining_slices)\n", + "\n", + "print(f\"Backpropagated {num_slices - len(remaining_slices)} circuit slices.\")\n", + "print(\n", + " f\"New observable contains {len(bp_obs)} terms and {len(bp_obs.group_commuting(qubit_wise=True))} commuting groups.\"\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "ae2d383c-c11c-457e-856f-85602f2df306", + "metadata": {}, + "source": [ + "The plots show that we did successfully backpropagate all 12 slices while keeping our observable under 10 commuting Pauli groups. We can also see that using `num_slices` along with `max_error_total` results in a distribution of budgets across the slices and unused budget is again forwarded to the next slice. This is most apparent in the **top right** plot, as the budget is both expended and replenished throughout backpropagation.\n", + "\n", + "It is notable that this method of distributing error produced the best results (more backpropagated slices), compared with the first experiment in this notebook and the example just previous this one. All of these examples allotted `.018` error budget, but backpropagation performed differently depending on how that budget was distributed." + ] + }, + { + "cell_type": "code", + "execution_count": 21, + "id": "b0bf5050-2928-41a1-9c3d-c9d79e918f6f", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "\"Output" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "fig, axes = plt.subplots(2, 2, figsize=(20, 10))\n", + "plot_slice_errors(metadata, axes[(0, 0)])\n", + "plot_left_over_error_budget(metadata, axes[(0, 1)])\n", + "plot_accumulated_error(metadata, axes[(1, 0)])\n", + "plot_num_qwc_groups(metadata, axes[(1, 1)])" + ] + }, + { + "cell_type": "markdown", + "id": "5c554774-2986-43a0-bdcd-45eaeb81ef5a", + "metadata": {}, + "source": [ + "## Work with multiple observables\n", + "\n", + "The `qiskit_addon_obp.backpropagate` method allows one to pass in a sequence of observables. This simplifies the workflow when dealing with multiple target observables.\n", + "\n", + "We explicitly mention this here to teach you how the truncation strategy handles such a case. For the sake of this example, we add an extra observable to the one which we have been using so far:" + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "id": "0857ea4c-82c1-4641-a268-1a9ba44a312b", + "metadata": {}, + "outputs": [], + "source": [ + "obs = [SparsePauliOp(\"IIIIIZIIII\"), SparsePauliOp(\"IIIIIXIIII\")]" + ] + }, + { + "cell_type": "markdown", + "id": "ba3ac81c-7395-4287-907a-742a1751cbd0", + "metadata": {}, + "source": [ + "Finally, we repeat the first experiment from this tutorial., but with two observables to backpropagate the circuit into.\n", + "\n", + "For this example, this does not affect the number of slices that could be backpropagated. However, we can see that the two observables resulted in different numbers of Pauli terms and commuting groups." + ] + }, + { + "cell_type": "code", + "execution_count": 23, + "id": "10c50f14-5bbd-427d-ae77-24389498a1e4", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "TruncationErrorBudget(per_slice_budget=[0.001], max_error_total=inf, p_norm=1)\n" + ] + } + ], + "source": [ + "truncation_error_budget = setup_budget(max_error_per_slice=0.001)\n", + "print(truncation_error_budget)" + ] + }, + { + "cell_type": "code", + "execution_count": 24, + "id": "862edaec-fc2c-488b-875d-23841ecc80b3", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Backpropagated 11 circuit slices.\n", + "The new first observable contains 29 terms and 10 commuting groups.\n", + "The new second observable contains 23 terms and 8 commuting groups.\n" + ] + } + ], + "source": [ + "bp_obs, remaining_slices, metadata = backpropagate(\n", + " obs,\n", + " slices,\n", + " operator_budget=op_budget,\n", + " truncation_error_budget=truncation_error_budget,\n", + ")\n", + "reduced_circuit = combine_slices(remaining_slices)\n", + "print(f\"Backpropagated {len(slices) - len(remaining_slices)} circuit slices.\")\n", + "print(\n", + " f\"The new first observable contains {len(bp_obs[0])} terms and {len(bp_obs[0].group_commuting(qubit_wise=True))} commuting groups.\"\n", + ")\n", + "print(\n", + " f\"The new second observable contains {len(bp_obs[1])} terms and {len(bp_obs[1].group_commuting(qubit_wise=True))} commuting groups.\"\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "467c614d-6bac-4826-a42b-39937b9d0c72", + "metadata": {}, + "source": [ + "The plots below help illustrate how the backpropagation algorithm handles multiple observables.\n", + "\n", + "First, the plots in the **top left**, **top right**, and **bottom left** show that the budget for truncating terms is set individually for each observable. In other words, both observables have the ability to truncate terms assuming an error of `0.001` per backpropagated slice.\n", + "Due to the different nature of the observables, this results in different consumption of the budget. In this example, they exhibit a lot of overlap, which does not always happen.\n", + "\n", + "The **bottom right** plot illustrates that `max_qwc_groups` takes _all_ observables into account. That means that the terms of all observables are grouped together to arrive at one final number of qubit-wise commuting groups, which is compared against `max_qwc_paulis`. The same is done for the `max_paulis` threshold (not discussed in this notebook), which allows you to set a limit on the number of Pauli terms across all observables." + ] + }, + { + "cell_type": "code", + "execution_count": 25, + "id": "82271b0d-ddaf-4ad2-b5c6-e9e4c2a4cff7", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "\"Output" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "fig, axes = plt.subplots(2, 2, figsize=(20, 10))\n", + "plot_slice_errors(metadata, axes[(0, 0)])\n", + "plot_left_over_error_budget(metadata, axes[(0, 1)])\n", + "plot_accumulated_error(metadata, axes[(1, 0)])\n", + "plot_num_qwc_groups(metadata, axes[(1, 1)])" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/addons/qiskit-addon-obp/index.mdx b/docs/addons/qiskit-addon-obp/index.mdx new file mode 100644 index 00000000000..a00590b0ec6 --- /dev/null +++ b/docs/addons/qiskit-addon-obp/index.mdx @@ -0,0 +1,31 @@ +--- +title: "Operator backpropagation (OBP)" +description: "Documentation for the latest version of Operator backpropagation (OBP)" +--- + +# Operator backpropagation (OBP) + +This package contains the Qiskit addon for operator backpropagation (OBP). Experimental errors limit the depth of quantum circuits that can be executed on near-term devices. OBP is a technique to reduce circuit depth by trimming operations from its end, at the cost of more operator measurements. + +As one backpropagates an operator further through a circuit, the size of the observable will grow exponentially, which results in both a classical and quantum resource overhead. However, for some circuits, the resulting distribution of Pauli observables is more concentrated than the worst-case exponential scaling, meaning that some terms in the Hamiltonian with small coefficients can be truncated to reduce the quantum overhead. The error incurred by doing this can be controlled to find a suitable tradeoff between precision and efficiency. + +There are several ways to perform operator backpropagation. This package uses a method based on Clifford perturbation theory, which has the benefit that the overhead incurred by backpropagating gates is determined by the non-Cliffordness of that gate. This leads to an increased efficiency for some families of circuits relative to tensor-network based methods for OBP, which currently have high classical overheads even in cases where the quantum overhead remains low. + +## Deprecation policy + +This package follows [semantic versioning](https://semver.org/) and is guided by the principles in [Qiskit’s deprecation policy](https://github.com/Qiskit/qiskit/blob/main/DEPRECATION.md). We may occasionally make breaking changes in order to improve the user experience. When possible, we will keep old interfaces and mark them as deprecated, as long as they can co-exist with the new ones. Each substantial improvement, breaking change, or deprecation will be documented in the [release notes](/docs/api/qiskit-addon-obp/release-notes). + +## Contributing + +The developer guide is located at [CONTRIBUTING.md](https://github.com/Qiskit/qiskit-addon-obp/blob/main/CONTRIBUTING.md) in the root of this project’s repository. By participating, you are expected to uphold Qiskit’s [code of conduct](https://github.com/Qiskit/qiskit/blob/main/CODE_OF_CONDUCT.md). + +We use [GitHub issues](https://github.com/Qiskit/qiskit-addon-obp/issues/new/choose) for tracking requests and bugs. + +## References + +1. 2. Fuller *et al.*, “[Improved quantum computation using operator backpropagation](https://www.nature.com/articles/s41534-026-01196-0),” *npj Quantum Inf.* **12**, 51 (2026). \[[arXiv](https://arxiv.org/abs/2502.01897)] + +## License + +[Apache License 2.0](https://github.com/Qiskit/qiskit-addon-obp/blob/main/LICENSE.txt) + diff --git a/docs/addons/qiskit-addon-obp/install.mdx b/docs/addons/qiskit-addon-obp/install.mdx new file mode 100644 index 00000000000..3c543b968e1 --- /dev/null +++ b/docs/addons/qiskit-addon-obp/install.mdx @@ -0,0 +1,77 @@ +--- +title: "Installation instructions" +description: "Installation instructions for the latest version of Operator backpropagation (OBP)" +--- + +# Installation instructions + +Before installing the package, choose how you’re going to run and install the packages. There are two primary ways to do this: + +* [Option 1: Install from PyPI](#option-1) +* [Option 2: Install from source](#option-2) + +## Preinstallation + +First, create a minimal environment with only Python installed in it. We recommend using [Python virtual environments](https://docs.python.org/3.10/tutorial/venv.html). + +```sh +python3 -m venv /path/to/virtual/environment +``` + +Activate your new environment. + +```sh +source /path/to/virtual/environment/bin/activate +``` + +Note: If you are using Windows, use the following commands in PowerShell: + +```pwsh +python3 -m venv c:\path\to\virtual\environment +c:\path\to\virtual\environment\Scripts\Activate.ps1 +``` + + + +## Option 1: Install from PyPI + +The most straightforward way to install the `qiskit-addon-obp` package is by using `PyPI`. + +```sh +pip install 'qiskit-addon-obp' +``` + + + +## Option 2: Install from source + +Users who want to develop in the repository or run the notebooks locally might want to install from source. + +If so, the first step is to clone the `qiskit-addon-obp` repository. + +```sh +git clone git@github.com:Qiskit/qiskit-addon-obp.git +``` + +Next, upgrade pip and enter the repository. + +```sh +pip install --upgrade pip +cd qiskit-addon-obp +``` + +The next step is to install `qiskit-addon-obp` to the virtual environment. If you plan on running the notebooks, install the notebook dependencies so you can run visualizations. If you plan on developing in the repository, you might want to install the `dev` dependencies. + +Adjust the options below to suit your needs. + +```sh +pip install tox notebook -e '.[notebook-dependencies,dev]' +``` + +If you installed the notebook dependencies, you can get started by running the notebooks in the docs directory. + +```python +cd docs/ +jupyter lab +``` + diff --git a/docs/api/qiskit-addon-obp/_toc.json b/docs/api/qiskit-addon-obp/_toc.json index e2bd0263c41..3336d5e5e49 100644 --- a/docs/api/qiskit-addon-obp/_toc.json +++ b/docs/api/qiskit-addon-obp/_toc.json @@ -72,5 +72,7 @@ } ], "collapsed": true, - "untranslatable": true + "untranslatable": true, + "parentUrl": "/docs/addons/qiskit-addon-obp", + "parentLabel": "Operator backpropagation (OBP)" } diff --git a/docs/api/qiskit-addon-obp/qiskit-addon-obp.mdx b/docs/api/qiskit-addon-obp/qiskit-addon-obp.mdx index 0dc24a61be8..1d45bc3986e 100644 --- a/docs/api/qiskit-addon-obp/qiskit-addon-obp.mdx +++ b/docs/api/qiskit-addon-obp/qiskit-addon-obp.mdx @@ -18,7 +18,7 @@ Main operator backpropagation functionality. ### backpropagate - + Backpropagate slices of quantum circuit operations onto the provided observables. This function takes a (list of) observable(s) and backpropagates the provided quantum circuit slices **in reverse order** onto the observable(s) until one of the stopping criteria is reached. @@ -34,7 +34,7 @@ Main operator backpropagation functionality. **Parameters** * **observables** ([*SparsePauliOp*](/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp) *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list)*\[*[*SparsePauliOp*](/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp)*]*) – The observable(s) onto which the circuit is backpropagated. - * **slices** ([*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)*\[*[*QuantumCircuit*](/docs/api/qiskit/qiskit.circuit.QuantumCircuit)*]*) – A sequence of `QuantumCircuit` objects representing a single circuit which has been separated into partitions spanning all qubits. **These “slices” will be backpropagated in reverse order.** Each slice must span all qubits. One may use the tools provided in [`qiskit_addon_utils.slicing`](https://qiskit.github.io/qiskit-addon-utils/apidocs/qiskit_addon_utils.slicing.html#module-qiskit_addon_utils.slicing "(in Qiskit addon utilities)") to slice a single [`QuantumCircuit`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit). + * **slices** ([*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)*\[*[*QuantumCircuit*](/docs/api/qiskit/qiskit.circuit.QuantumCircuit)*]*) – A sequence of `QuantumCircuit` objects representing a single circuit which has been separated into partitions spanning all qubits. **These “slices” will be backpropagated in reverse order.** Each slice must span all qubits. One may use the tools provided in [`qiskit_addon_utils.slicing`](/docs/api/qiskit-addon-utils/slicing#module-qiskit_addon_utils.slicing#module-qiskit_addon_utils.slicing "(in Qiskit addon utilities)") to slice a single [`QuantumCircuit`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit). * **truncation\_error\_budget** ([*TruncationErrorBudget*](utils-truncating#truncationerrorbudget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget") *| None*) – The error budget used for truncating Pauli terms. Refer to the [how-to guide](https://qiskit.github.io/qiskit-addon-obp/how_tos/truncate_operator_terms.html) for a detailed discussion on truncating terms from the output operator and bounding the incurred error. * **operator\_budget** ([*OperatorBudget*](utils-simplify#operatorbudget "qiskit_addon_obp.utils.simplify.OperatorBudget") *| None*) – Constraints on how large the operator may grow during backpropagation. If `None`, a default instance of [`OperatorBudget`](utils-simplify#operatorbudget "qiskit_addon_obp.utils.simplify.OperatorBudget") will be used, and no constraints will be placed on the output operator size. * **max\_seconds** ([*int*](https://docs.python.org/3/library/functions.html#int) *| None*) – The maximum number of seconds to run the backpropagation. If this timeout is triggered before the function returns, the metadata of that moment will be returned. Note, that this metadata may contain only partial information for the last slice being backpropagated. @@ -54,6 +54,6 @@ Main operator backpropagation functionality. **Return type** - [tuple](https://docs.python.org/3/library/stdtypes.html#tuple)\[[list](https://docs.python.org/3/library/stdtypes.html#list)\[[*SparsePauliOp*](/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp)], [*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)\[[*QuantumCircuit*](/docs/api/qiskit/qiskit.circuit.QuantumCircuit)], [*OBPMetadata*](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")] + [tuple](https://docs.python.org/3/library/stdtypes.html#tuple)\[[list](https://docs.python.org/3/library/stdtypes.html#list)\[[*SparsePauliOp*](/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp)], [*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)\[[*QuantumCircuit*](/docs/api/qiskit/qiskit.circuit.QuantumCircuit)], [*OBPMetadata*](/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")] diff --git a/docs/api/qiskit-addon-obp/release-notes.mdx b/docs/api/qiskit-addon-obp/release-notes.mdx index 2ef507a6319..6af107d322b 100644 --- a/docs/api/qiskit-addon-obp/release-notes.mdx +++ b/docs/api/qiskit-addon-obp/release-notes.mdx @@ -10,6 +10,18 @@ in_page_toc_max_heading_level: 2 # Operator backpropagation (OBP) release notes + + + + +## Upcoming release (`136/merge`) + + + +### Upgrade Notes + +* Support for Python 3.9 has been removed. The minimum supported Python version is now 3.10. + @@ -20,13 +32,13 @@ in_page_toc_max_heading_level: 2 ### New Features -* [`PauliLindbladError`](/docs/api/qiskit-ibm-runtime/utils-noise-learner-result-pauli-lindblad-error "(in Qiskit Runtime IBM Client)") objects can now be embedded in slices of `QuantumCircuit` using the [`PauliLindbladErrorInstruction`](utils-noise-pauli-lindblad-error-instruction "qiskit_addon_obp.utils.noise.PauliLindbladErrorInstruction") and will be handled properly by [`backpropagate()`](qiskit-addon-obp#backpropagate "qiskit_addon_obp.backpropagate"). +* [`PauliLindbladError`](/docs/api/qiskit-ibm-runtime/utils-noise-learner-result-pauli-lindblad-error "(in Qiskit Runtime IBM Client)") objects can now be embedded in slices of `QuantumCircuit` using the [`PauliLindbladErrorInstruction`](/docs/api/qiskit-addon-obp/utils-noise-pauli-lindblad-error-instruction "qiskit_addon_obp.utils.noise.PauliLindbladErrorInstruction") and will be handled properly by [`backpropagate()`](/docs/api/qiskit-addon-obp/qiskit-addon-obp#backpropagate "qiskit_addon_obp.backpropagate"). ### Bug Fixes -* Fixed a bug in [`qiskit_addon_obp.backpropagate()`](qiskit-addon-obp#backpropagate "qiskit_addon_obp.backpropagate") which often caused resets to be applied to the wrong qubit. +* Fixed a bug in [`qiskit_addon_obp.backpropagate()`](/docs/api/qiskit-addon-obp/qiskit-addon-obp#backpropagate "qiskit_addon_obp.backpropagate") which often caused resets to be applied to the wrong qubit. @@ -40,16 +52,18 @@ in_page_toc_max_heading_level: 2 ### New Features -* A new parameter `show_legend` has been added to each function in the [`qiskit_addon_obp.utils.visualization`](utils-visualization#module-qiskit_addon_obp.utils.visualization "qiskit_addon_obp.utils.visualization") module that can show or hide the legend on a plot. The legend is shown by default. This can be useful when the legend becomes long and obstructs the plot. +* A new parameter `show_legend` has been added to each function in the [`qiskit_addon_obp.utils.visualization`](/docs/api/qiskit-addon-obp/utils-visualization#module-qiskit_addon_obp.utils.visualization "qiskit_addon_obp.utils.visualization") module that can show or hide the legend on a plot. The legend is shown by default. This can be useful when the legend becomes long and obstructs the plot. -* [`qiskit_addon_obp.utils.simplify.OperatorBudget`](utils-simplify#operatorbudget "qiskit_addon_obp.utils.simplify.OperatorBudget") now holds `atol` and `rtol` fields which are absolute and relative tolerances used to determine whether coefficients are zero while simplifying an operator. +* [`qiskit_addon_obp.utils.simplify.OperatorBudget`](/docs/api/qiskit-addon-obp/utils-simplify#operatorbudget "qiskit_addon_obp.utils.simplify.OperatorBudget") now holds `atol` and `rtol` fields which are absolute and relative tolerances used to determine whether coefficients are zero while simplifying an operator. -* [`truncate_binary_search()`](utils-truncating#truncate_binary_search "qiskit_addon_obp.utils.truncating.truncate_binary_search") now accepts a `tol` kwarg. Once an optimal truncation threshold, up to this value, has been found, the search for an optimal threshold will stop. The default tolerance is `1e-8`; whereas, the tolerance used prior to this release was `1e-10`. +* [`truncate_binary_search()`](/docs/api/qiskit-addon-obp/utils-truncating#truncate_binary_search "qiskit_addon_obp.utils.truncating.truncate_binary_search") now accepts a `tol` kwarg. Once an optimal truncation threshold, up to this value, has been found, the search for an optimal threshold will stop. The default tolerance is `1e-8`; whereas, the tolerance used prior to this release was `1e-10`. - [`TruncationErrorBudget`](utils-truncating#truncationerrorbudget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget") now holds a `tol` field. This field is used by [`backpropagate()`](qiskit-addon-obp#backpropagate "qiskit_addon_obp.backpropagate") as the `tol` argument to [`truncate_binary_search()`](utils-truncating#truncate_binary_search "qiskit_addon_obp.utils.truncating.truncate_binary_search"). + [`TruncationErrorBudget`](/docs/api/qiskit-addon-obp/utils-truncating#truncationerrorbudget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget") now holds a `tol` field. This field is used by [`backpropagate()`](/docs/api/qiskit-addon-obp/qiskit-addon-obp#backpropagate "qiskit_addon_obp.backpropagate") as the `tol` argument to [`truncate_binary_search()`](/docs/api/qiskit-addon-obp/utils-truncating#truncate_binary_search "qiskit_addon_obp.utils.truncating.truncate_binary_search"). + + ### Upgrade Notes * This release adds support for Python 3.13. No code changes were necessary, so older releases are expected to work on Python 3.13 too. @@ -58,43 +72,43 @@ in_page_toc_max_heading_level: 2 - + ### Bug Fixes -* The [`num_duplicate_paulis`](utils-simplify#num_duplicate_paulis "qiskit_addon_obp.utils.simplify.SimplifyMetadata.num_duplicate_paulis") was previously unable to differentiate from Pauli terms that were trimmed due to their coefficient being close to zero. This is now tracked correctly with these trimmed terms only counting towards [`num_trimmed_paulis`](utils-simplify#num_trimmed_paulis "qiskit_addon_obp.utils.simplify.SimplifyMetadata.num_trimmed_paulis"). +* The [`num_duplicate_paulis`](/docs/api/qiskit-addon-obp/utils-simplify#num_duplicate_paulis "qiskit_addon_obp.utils.simplify.SimplifyMetadata.num_duplicate_paulis") was previously unable to differentiate from Pauli terms that were trimmed due to their coefficient being close to zero. This is now tracked correctly with these trimmed terms only counting towards [`num_trimmed_paulis`](/docs/api/qiskit-addon-obp/utils-simplify#num_trimmed_paulis "qiskit_addon_obp.utils.simplify.SimplifyMetadata.num_trimmed_paulis"). -* The reported number of unique Paulis in [`num_unique_paulis`](utils-simplify#num_unique_paulis "qiskit_addon_obp.utils.simplify.SimplifyMetadata.num_unique_paulis") is now correct in cases where all gates in a slice commute with an observable. +* The reported number of unique Paulis in [`num_unique_paulis`](/docs/api/qiskit-addon-obp/utils-simplify#num_unique_paulis "qiskit_addon_obp.utils.simplify.SimplifyMetadata.num_unique_paulis") is now correct in cases where all gates in a slice commute with an observable. -* Fixed a bug in [`qiskit_addon_obp.backpropagate()`](qiskit-addon-obp#backpropagate "qiskit_addon_obp.backpropagate") which caused slices with depth > 1 to be incorrectly forward-propagated. Gates from a given slice will now be correctly propagated into the observable in reverse order (i.e., from the back of the slice). +* Fixed a bug in [`qiskit_addon_obp.backpropagate()`](/docs/api/qiskit-addon-obp/qiskit-addon-obp#backpropagate "qiskit_addon_obp.backpropagate") which caused slices with depth > 1 to be incorrectly forward-propagated. Gates from a given slice will now be correctly propagated into the observable in reverse order (i.e., from the back of the slice). - + ## 0.1.0 - + ### New Features -* Added a [`OperatorBudget`](utils-simplify#operatorbudget "qiskit_addon_obp.utils.simplify.OperatorBudget") class for specifying how large an operator may grow during back-propagation. +* Added a [`OperatorBudget`](/docs/api/qiskit-addon-obp/utils-simplify#operatorbudget "qiskit_addon_obp.utils.simplify.OperatorBudget") class for specifying how large an operator may grow during back-propagation. -* Adds the `max_seconds` keyword-argument to the [`backpropagate()`](qiskit-addon-obp#backpropagate "qiskit_addon_obp.backpropagate") function, allowing the end-user to specify a maximum wall clock time for the algorithm. This can (for example) be useful for exploring different truncation error budget strategies while limiting the CPU time. +* Adds the `max_seconds` keyword-argument to the [`backpropagate()`](/docs/api/qiskit-addon-obp/qiskit-addon-obp#backpropagate "qiskit_addon_obp.backpropagate") function, allowing the end-user to specify a maximum wall clock time for the algorithm. This can (for example) be useful for exploring different truncation error budget strategies while limiting the CPU time. -* Introduced a new `dataclass`, [`TruncationErrorBudget`](utils-truncating#truncationerrorbudget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget"), for holding information about the observable truncation strategy. +* Introduced a new `dataclass`, [`TruncationErrorBudget`](/docs/api/qiskit-addon-obp/utils-truncating#truncationerrorbudget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget"), for holding information about the observable truncation strategy. -* Introduced a new function, [`setup_budget()`](utils-truncating#setup_budget "qiskit_addon_obp.utils.truncating.setup_budget"), which generates a [`TruncationErrorBudget`](utils-truncating#truncationerrorbudget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget") class, given an observable truncation strategy (e.g. `max_error_total`, `max_error_per_slice`, `p_norm`). +* Introduced a new function, [`setup_budget()`](/docs/api/qiskit-addon-obp/utils-truncating#setup_budget "qiskit_addon_obp.utils.truncating.setup_budget"), which generates a [`TruncationErrorBudget`](/docs/api/qiskit-addon-obp/utils-truncating#truncationerrorbudget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget") class, given an observable truncation strategy (e.g. `max_error_total`, `max_error_per_slice`, `p_norm`). - + ### Upgrade Notes -* The [`backpropagate()`](qiskit-addon-obp#backpropagate "qiskit_addon_obp.backpropagate") function no longer accepts `max_paulis` and `max_qwc_groups` kwargs for constraining the size of the operator during back-propagation. Users should instead use the new `operator_budget` kwarg, which takes an [`OperatorBudget`](utils-simplify#operatorbudget "qiskit_addon_obp.utils.simplify.OperatorBudget") instance. +* The [`backpropagate()`](/docs/api/qiskit-addon-obp/qiskit-addon-obp#backpropagate "qiskit_addon_obp.backpropagate") function no longer accepts `max_paulis` and `max_qwc_groups` kwargs for constraining the size of the operator during back-propagation. Users should instead use the new `operator_budget` kwarg, which takes an [`OperatorBudget`](/docs/api/qiskit-addon-obp/utils-simplify#operatorbudget "qiskit_addon_obp.utils.simplify.OperatorBudget") instance. To migrate, change this code @@ -120,7 +134,7 @@ in_page_toc_max_heading_level: 2 bp_obs, remaining_slices, metadata = backpropagate(obs, slices, operator_budget=op_budget) ``` -* The `max_slices` kwarg has been removed from [`backpropagate()`](qiskit-addon-obp#backpropagate "qiskit_addon_obp.backpropagate"). Users should now only pass in slices which they intend to back-propagate. If a user wants to attempt to only back-propagate the last `20` slices of an `N`-slice circuit, they would simply pass in the last `20` slices to [`backpropagate()`](qiskit-addon-obp#backpropagate "qiskit_addon_obp.backpropagate") and, recombine any slices remaining after back-propagation with the original `N-20` slices. +* The `max_slices` kwarg has been removed from [`backpropagate()`](/docs/api/qiskit-addon-obp/qiskit-addon-obp#backpropagate "qiskit_addon_obp.backpropagate"). Users should now only pass in slices which they intend to back-propagate. If a user wants to attempt to only back-propagate the last `20` slices of an `N`-slice circuit, they would simply pass in the last `20` slices to [`backpropagate()`](/docs/api/qiskit-addon-obp/qiskit-addon-obp#backpropagate "qiskit_addon_obp.backpropagate") and, recombine any slices remaining after back-propagation with the original `N-20` slices. For example @@ -137,9 +151,9 @@ in_page_toc_max_heading_level: 2 reduced_circuit = combine_slices(slices[:-num_slices] + remaining_slices) ``` -* The `max_slices` kwarg in [`setup_budget()`](utils-truncating#setup_budget "qiskit_addon_obp.utils.truncating.setup_budget") has been renamed to `num_slices`. +* The `max_slices` kwarg in [`setup_budget()`](/docs/api/qiskit-addon-obp/utils-truncating#setup_budget "qiskit_addon_obp.utils.truncating.setup_budget") has been renamed to `num_slices`. -* The `max_slices` attribute in [`OBPMetadata`](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata") has been renamed to `num_slices`. +* The `max_slices` attribute in [`OBPMetadata`](/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata") has been renamed to `num_slices`. * The project’s root Python namespace has been changed from `obp` to `qiskit_addon_obp`. All package imports must be updated. @@ -155,19 +169,19 @@ in_page_toc_max_heading_level: 2 from qiskit_addon_obp import backpropagate ``` -* Removed the `max_error_total`, `max_error_per_slice`, and `p_norm` kwargs from the [`backpropagate()`](qiskit-addon-obp#backpropagate "qiskit_addon_obp.backpropagate") signature. Instead, users must specify their observable truncation strategy with the new `truncation_error_budget` kwarg which accepts a [`TruncationErrorBudget`](utils-truncating#truncationerrorbudget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget") instance. +* Removed the `max_error_total`, `max_error_per_slice`, and `p_norm` kwargs from the [`backpropagate()`](/docs/api/qiskit-addon-obp/qiskit-addon-obp#backpropagate "qiskit_addon_obp.backpropagate") signature. Instead, users must specify their observable truncation strategy with the new `truncation_error_budget` kwarg which accepts a [`TruncationErrorBudget`](/docs/api/qiskit-addon-obp/utils-truncating#truncationerrorbudget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget") instance. -* Removed the `per_slice_budget`, `max_error_total`, and `p_norm` fields from the [`OBPMetadata`](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata") class. These fields will now be accessed through the new `truncation_error_budget` field, which holds a [`TruncationErrorBudget`](utils-truncating#truncationerrorbudget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget") instance. +* Removed the `per_slice_budget`, `max_error_total`, and `p_norm` fields from the [`OBPMetadata`](/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata") class. These fields will now be accessed through the new `truncation_error_budget` field, which holds a [`TruncationErrorBudget`](/docs/api/qiskit-addon-obp/utils-truncating#truncationerrorbudget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget") instance. - + ### Bug Fixes -* The [`setup_budget()`](utils-truncating#setup_budget "qiskit_addon_obp.utils.truncating.setup_budget") erroneously distributed the `max_error_total` when `num_slices` was also set. This has been fixed now, such that the budget always gets distributed evenly, regardless of the value of `p_norm`. +* The [`setup_budget()`](/docs/api/qiskit-addon-obp/utils-truncating#setup_budget "qiskit_addon_obp.utils.truncating.setup_budget") erroneously distributed the `max_error_total` when `num_slices` was also set. This has been fixed now, such that the budget always gets distributed evenly, regardless of the value of `p_norm`. -* When the `max_seconds` argument to the [`backpropagate()`](qiskit-addon-obp#backpropagate "qiskit_addon_obp.backpropagate") method is used, but the timeout is not reached during the actual OBP execution, the signal will now be reset properly, thereby avoiding cancellations at a (seemingly) random later point in time (of course, it is not random but actually after the specified amount of time has passed, but the rest of the code being executed after OBP could be doing anything at this point). +* When the `max_seconds` argument to the [`backpropagate()`](/docs/api/qiskit-addon-obp/qiskit-addon-obp#backpropagate "qiskit_addon_obp.backpropagate") method is used, but the timeout is not reached during the actual OBP execution, the signal will now be reset properly, thereby avoiding cancellations at a (seemingly) random later point in time (of course, it is not random but actually after the specified amount of time has passed, but the rest of the code being executed after OBP could be doing anything at this point). -* The computation of the [`accumulated_error()`](utils-metadata-obp-metadata#accumulated_error "qiskit_addon_obp.utils.metadata.OBPMetadata.accumulated_error") and [`left_over_error_budget()`](utils-metadata-obp-metadata#left_over_error_budget "qiskit_addon_obp.utils.metadata.OBPMetadata.left_over_error_budget") were fixed to respect the [Minkowski inequality](https://en.wikipedia.org/wiki/Minkowski_inequality). This is necessary, because a general Lp-norm (other than `p=2`) does not satisfy the [parallelogram law](https://en.wikipedia.org/wiki/Parallelogram_law) which resulted in a non-rigorous upper bound of the actual accumulated errors (and left-over error budgets by extension). +* The computation of the [`accumulated_error()`](/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata#accumulated_error "qiskit_addon_obp.utils.metadata.OBPMetadata.accumulated_error") and [`left_over_error_budget()`](/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata#left_over_error_budget "qiskit_addon_obp.utils.metadata.OBPMetadata.left_over_error_budget") were fixed to respect the [Minkowski inequality](https://en.wikipedia.org/wiki/Minkowski_inequality). This is necessary, because a general Lp-norm (other than `p=2`) does not satisfy the [parallelogram law](https://en.wikipedia.org/wiki/Parallelogram_law) which resulted in a non-rigorous upper bound of the actual accumulated errors (and left-over error budgets by extension). diff --git a/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata.mdx b/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata.mdx index 59e391628c9..b90bc50222a 100644 --- a/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata.mdx +++ b/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata.mdx @@ -8,7 +8,7 @@ python_api_name: qiskit_addon_obp.utils.metadata.OBPMetadata # OBPMetadata - + Bases: [`object`](https://docs.python.org/3/library/functions.html#object) A container for metadata generated during the `backpropagate()` method. @@ -17,9 +17,9 @@ python_api_name: qiskit_addon_obp.utils.metadata.OBPMetadata **Parameters** - * **truncation\_error\_budget** ([*TruncationErrorBudget*](utils-truncating#truncationerrorbudget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget")) + * **truncation\_error\_budget** ([*TruncationErrorBudget*](/docs/api/qiskit-addon-obp/utils-truncating#truncationerrorbudget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget")) * **num\_slices** ([*int*](https://docs.python.org/3/library/functions.html#int) *| None*) - * **operator\_budget** ([*OperatorBudget*](utils-simplify#operatorbudget "qiskit_addon_obp.utils.simplify.OperatorBudget")) + * **operator\_budget** ([*OperatorBudget*](/docs/api/qiskit-addon-obp/utils-simplify#operatorbudget "qiskit_addon_obp.utils.simplify.OperatorBudget")) * **backpropagation\_history** ([*list*](https://docs.python.org/3/library/stdtypes.html#list)*\[*[*SliceMetadata*](utils-metadata-slice-metadata "qiskit_addon_obp.utils.metadata.SliceMetadata")*]*) * **num\_backpropagated\_slices** ([*int*](https://docs.python.org/3/library/functions.html#int)) @@ -61,12 +61,12 @@ python_api_name: qiskit_addon_obp.utils.metadata.OBPMetadata ### accumulated\_error - + Compute the accumulated error for a given observable at a given “time”. This method computes the accumulated error for a given observable index at a given “time” during the course of the backpropagation. In this context, “time” is to be understood as the discrete steps of already backpropagated slices. - The accumulated error is computed as the sum of the individual [`SliceMetadata.slice_errors`](utils-metadata-slice-metadata#slice_errors "qiskit_addon_obp.utils.metadata.SliceMetadata.slice_errors"). These in turn may be computed within a specified [`TruncationErrorBudget.p_norm`](utils-truncating#p_norm "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.p_norm"). Thus, the computed accumulated error is an upper bound to the real accumulated error as given by the [Minkowski inequality](https://en.wikipedia.org/wiki/Minkowski_inequality) (the generalization of the triangle inequality for Lp-norms other than `p=2`). + The accumulated error is computed as the sum of the individual [`SliceMetadata.slice_errors`](utils-metadata-slice-metadata#slice_errors "qiskit_addon_obp.utils.metadata.SliceMetadata.slice_errors"). These in turn may be computed within a specified [`TruncationErrorBudget.p_norm`](/docs/api/qiskit-addon-obp/utils-truncating#p_norm "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.p_norm"). Thus, the computed accumulated error is an upper bound to the real accumulated error as given by the [Minkowski inequality](https://en.wikipedia.org/wiki/Minkowski_inequality) (the generalization of the triangle inequality for Lp-norms other than `p=2`). Since a general Lp-norm (other than `p=2`) is *not* an inner product norm, it does *not* satisfy the [parallelogram law](https://en.wikipedia.org/wiki/Parallelogram_law). Hence, we must use the Minkowski inequality as the upper bound of the accumulated error. @@ -88,7 +88,7 @@ python_api_name: qiskit_addon_obp.utils.metadata.OBPMetadata ### from\_json - + Load a metadata from a json file. **Parameters** @@ -106,12 +106,12 @@ python_api_name: qiskit_addon_obp.utils.metadata.OBPMetadata ### left\_over\_error\_budget - + Compute the left-over error budget for a given observable at a given “time”. This method computes the left-over error budget for a given observable index at a given “time” during the course of the backpropagation. In this context, “time” is to be understood as the discrete steps of already backpropagated slices. - The left-over error budget is computed as the remainder of the total budget minus the sum of the individual [`SliceMetadata.slice_errors`](utils-metadata-slice-metadata#slice_errors "qiskit_addon_obp.utils.metadata.SliceMetadata.slice_errors"). These in turn may be computed within a specified [`TruncationErrorBudget.p_norm`](utils-truncating#p_norm "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.p_norm"). + The left-over error budget is computed as the remainder of the total budget minus the sum of the individual [`SliceMetadata.slice_errors`](utils-metadata-slice-metadata#slice_errors "qiskit_addon_obp.utils.metadata.SliceMetadata.slice_errors"). These in turn may be computed within a specified [`TruncationErrorBudget.p_norm`](/docs/api/qiskit-addon-obp/utils-truncating#p_norm "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.p_norm"). See also the explanations in [`accumulated_error()`](#qiskit_addon_obp.utils.metadata.OBPMetadata.accumulated_error "qiskit_addon_obp.utils.metadata.OBPMetadata.accumulated_error") for more details on how the individual slice errors are summed up to form an upper bound to the real error via the Minkowski inequality. @@ -137,7 +137,7 @@ python_api_name: qiskit_addon_obp.utils.metadata.OBPMetadata ### to\_json - + Dump this metadata to a json file. **Parameters** diff --git a/docs/api/qiskit-addon-obp/utils-metadata-slice-metadata.mdx b/docs/api/qiskit-addon-obp/utils-metadata-slice-metadata.mdx index 2c3517d4932..4d7cc2dd7e4 100644 --- a/docs/api/qiskit-addon-obp/utils-metadata-slice-metadata.mdx +++ b/docs/api/qiskit-addon-obp/utils-metadata-slice-metadata.mdx @@ -8,7 +8,7 @@ python_api_name: qiskit_addon_obp.utils.metadata.SliceMetadata # SliceMetadata - + Bases: [`object`](https://docs.python.org/3/library/functions.html#object) A container for metadata generated during the backpropagation of a single slice. @@ -76,7 +76,7 @@ python_api_name: qiskit_addon_obp.utils.metadata.SliceMetadata The sum of the coefficients for each observable that were trimmed during operator simplification because each individual coefficient was below the trimming threshold. - This sum is *not* affected by the value of [`p_norm`](utils-truncating#p_norm "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.p_norm")! + This sum is *not* affected by the value of [`p_norm`](/docs/api/qiskit-addon-obp/utils-truncating#p_norm "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.p_norm")! diff --git a/docs/api/qiskit-addon-obp/utils-metadata.mdx b/docs/api/qiskit-addon-obp/utils-metadata.mdx index 4375fd5ef91..20e6828efd2 100644 --- a/docs/api/qiskit-addon-obp/utils-metadata.mdx +++ b/docs/api/qiskit-addon-obp/utils-metadata.mdx @@ -16,8 +16,8 @@ python_api_name: qiskit_addon_obp.utils.metadata Container classes for holding backpropagation metadata. -| | | -| ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | -| [`OBPMetadata`](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata") | A container for metadata generated during the `backpropagate()` method. | -| [`SliceMetadata`](utils-metadata-slice-metadata "qiskit_addon_obp.utils.metadata.SliceMetadata") | A container for metadata generated during the backpropagation of a single slice. | +| | | +| --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | +| [`OBPMetadata`](/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata") | A container for metadata generated during the `backpropagate()` method. | +| [`SliceMetadata`](/docs/api/qiskit-addon-obp/utils-metadata-slice-metadata "qiskit_addon_obp.utils.metadata.SliceMetadata") | A container for metadata generated during the backpropagation of a single slice. | diff --git a/docs/api/qiskit-addon-obp/utils-noise-pauli-lindblad-error-instruction.mdx b/docs/api/qiskit-addon-obp/utils-noise-pauli-lindblad-error-instruction.mdx index f92f265d8ba..2484d2ebefd 100644 --- a/docs/api/qiskit-addon-obp/utils-noise-pauli-lindblad-error-instruction.mdx +++ b/docs/api/qiskit-addon-obp/utils-noise-pauli-lindblad-error-instruction.mdx @@ -8,7 +8,7 @@ python_api_name: qiskit_addon_obp.utils.noise.PauliLindbladErrorInstruction # PauliLindbladErrorInstruction - + Bases: [`Instruction`](/docs/api/qiskit/qiskit.circuit.Instruction) A lightweight wrapper around a `PauliLindbladError`. @@ -177,7 +177,7 @@ python_api_name: qiskit_addon_obp.utils.noise.PauliLindbladErrorInstruction ### repeat - Creates an instruction with `self` repeated :math\`n\` times. + Creates an instruction with `self` repeated $n$ times. **Parameters** @@ -243,7 +243,7 @@ python_api_name: qiskit_addon_obp.utils.noise.PauliLindbladErrorInstruction ### validate\_parameter - Instruction parameters has no validation or normalization. + Instruction parameter has no validation or normalization. diff --git a/docs/api/qiskit-addon-obp/utils-noise.mdx b/docs/api/qiskit-addon-obp/utils-noise.mdx index c09109eb726..d37043bbe3d 100644 --- a/docs/api/qiskit-addon-obp/utils-noise.mdx +++ b/docs/api/qiskit-addon-obp/utils-noise.mdx @@ -16,7 +16,7 @@ python_api_name: qiskit_addon_obp.utils.noise Utilities for noise operators. -| | | -| -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | -| [`PauliLindbladErrorInstruction`](utils-noise-pauli-lindblad-error-instruction "qiskit_addon_obp.utils.noise.PauliLindbladErrorInstruction") | A lightweight wrapper around a `PauliLindbladError`. | +| | | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | +| [`PauliLindbladErrorInstruction`](/docs/api/qiskit-addon-obp/utils-noise-pauli-lindblad-error-instruction "qiskit_addon_obp.utils.noise.PauliLindbladErrorInstruction") | A lightweight wrapper around a `PauliLindbladError`. | diff --git a/docs/api/qiskit-addon-obp/utils-operations.mdx b/docs/api/qiskit-addon-obp/utils-operations.mdx index 3c4945b8f86..9acd121d958 100644 --- a/docs/api/qiskit-addon-obp/utils-operations.mdx +++ b/docs/api/qiskit-addon-obp/utils-operations.mdx @@ -18,7 +18,7 @@ Utility functions for operator backpropagation. ### apply\_op\_to - + Apply the operator `op2` to the operator `op1`. These operators do not necessarily need to act on the same number of qubits, as they are assumed to act on a larger system. The position in the system of each operator is defined by the corresponding `qargs`. The output operator will be defined on `union(op1_qargs, op2_qargs)`. @@ -56,7 +56,7 @@ Utility functions for operator backpropagation. ### apply\_reset\_to - + Apply a reset operation to a Pauli operator. This function applies a reset operation to `op` in the following way: @@ -82,7 +82,7 @@ Utility functions for operator backpropagation. ### to\_global\_op - + Convert a local operator to a global operator by inserting identities on qubits which aren’t used. **Parameters** @@ -106,7 +106,7 @@ Utility functions for operator backpropagation. ### reduce\_op - + Create a lean representation of a global Pauli operator. This function returns a lean representation of the input operator such that all of the qubits associated solely with Pauli-I terms have been removed. A list of indices is also returned indicating on which qubits the lean operator acts. diff --git a/docs/api/qiskit-addon-obp/utils-simplify.mdx b/docs/api/qiskit-addon-obp/utils-simplify.mdx index 467b9568aff..7f385078694 100644 --- a/docs/api/qiskit-addon-obp/utils-simplify.mdx +++ b/docs/api/qiskit-addon-obp/utils-simplify.mdx @@ -18,7 +18,7 @@ Functions for simplifying Pauli operators. ### OperatorBudget - + Bases: [`object`](https://docs.python.org/3/library/functions.html#object) A class for storing the constants that determine how large an operator may grow. @@ -44,7 +44,7 @@ Functions for simplifying Pauli operators. #### is\_active - + Return whether `self` places any bounds on operator size. **Return type** @@ -79,7 +79,7 @@ Functions for simplifying Pauli operators. ### SimplifyMetadata - + Bases: [`object`](https://docs.python.org/3/library/functions.html#object) A simple dataclass for returning the tracked attributes during operator simplification. @@ -118,7 +118,7 @@ Functions for simplifying Pauli operators. ### simplify - + Simplifies the provided Pauli operator. This is an adaption of `SparsePauliOp.simplify()` which tracks metadata of the simplified terms. diff --git a/docs/api/qiskit-addon-obp/utils-truncating.mdx b/docs/api/qiskit-addon-obp/utils-truncating.mdx index 2e6b97735e1..53815adf710 100644 --- a/docs/api/qiskit-addon-obp/utils-truncating.mdx +++ b/docs/api/qiskit-addon-obp/utils-truncating.mdx @@ -18,7 +18,7 @@ Functions for truncating Pauli operators within given error budgets. ### TruncationErrorBudget - + Bases: [`object`](https://docs.python.org/3/library/functions.html#object) A class for storing the constants that determine the truncation error budget. @@ -34,7 +34,7 @@ Functions for truncating Pauli operators within given error budgets. #### is\_active - + Return whether the truncation is active, i.e. whether the budget is non-zero. **Return type** @@ -71,7 +71,7 @@ Functions for truncating Pauli operators within given error budgets. ### setup\_budget - + Calculate the budget available to each slice for observable term truncation. This method makes the construction of a [`TruncationErrorBudget`](#qiskit_addon_obp.utils.truncating.TruncationErrorBudget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget") easier for an end-user. This error budget can be provided to the [`backpropagate()`](qiskit-addon-obp#backpropagate "qiskit_addon_obp.backpropagate") method to enable the truncation of low-weight Pauli terms. Refer to the [how-to guide](https://qiskit.github.io/qiskit-addon-obp/how_tos/truncate_operator_terms.html) for a detailed discussion on truncating terms from the output operator and bounding the incurred error. @@ -111,7 +111,7 @@ Functions for truncating Pauli operators within given error budgets. ### truncate\_binary\_search - + Perform binary search to find an optimal observable truncation threshold. Removes the Pauli terms from a `SparsePauliOp` whose sum of their absolute coefficients values does not exceed the provided error `budget`. @@ -119,7 +119,7 @@ Functions for truncating Pauli operators within given error budgets. **Parameters** * **observable** ([*SparsePauliOp*](/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp)) – the `SparsePauliOp` to truncate terms from. - * **budget** ([*float*](https://docs.python.org/3/library/functions.html#float)) – the maximum permissable truncation error. + * **budget** ([*float*](https://docs.python.org/3/library/functions.html#float)) – the maximum permissible truncation error. * **p\_norm** ([*int*](https://docs.python.org/3/library/functions.html#int)) – an integer specifying what p-norm to use. * **tol** ([*float*](https://docs.python.org/3/library/functions.html#float)) – when the binary search thresholds differ by an amount smaller than `tol`, the threshold search will stop. diff --git a/docs/api/qiskit-addon-obp/utils-visualization.mdx b/docs/api/qiskit-addon-obp/utils-visualization.mdx index f21a5e38145..af549522ea3 100644 --- a/docs/api/qiskit-addon-obp/utils-visualization.mdx +++ b/docs/api/qiskit-addon-obp/utils-visualization.mdx @@ -18,10 +18,10 @@ Various visualization utilities. ### plot\_accumulated\_error - + Plot the accumulated error. - This method populates the provided figure axes with a line-plot of the [`OBPMetadata.accumulated_error()`](utils-metadata-obp-metadata#accumulated_error "qiskit_addon_obp.utils.metadata.OBPMetadata.accumulated_error"). Below is an example where we plot some `metadata` which exists within our context. + This method populates the provided figure axes with a line-plot of the [`OBPMetadata.accumulated_error()`](/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata#accumulated_error "qiskit_addon_obp.utils.metadata.OBPMetadata.accumulated_error"). Below is an example where we plot some `metadata` which exists within our context. ```python >>> from matplotlib import pyplot as plt @@ -38,7 +38,7 @@ Various visualization utilities. **Parameters** - * **metadata** ([*OBPMetadata*](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. + * **metadata** ([*OBPMetadata*](/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. * **axes** (*Axes*) – the matplotlib axes in which to plot. * **show\_legend** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – enable/disable showing the legend in the plot. @@ -49,10 +49,10 @@ Various visualization utilities. ### plot\_left\_over\_error\_budget - + Plot the left-over error budget. - This method populates the provided figure axes with a line-plot of the [`OBPMetadata.left_over_error_budget()`](utils-metadata-obp-metadata#left_over_error_budget "qiskit_addon_obp.utils.metadata.OBPMetadata.left_over_error_budget"). Below is an example where we plot some `metadata` which exists within our context. + This method populates the provided figure axes with a line-plot of the [`OBPMetadata.left_over_error_budget()`](/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata#left_over_error_budget "qiskit_addon_obp.utils.metadata.OBPMetadata.left_over_error_budget"). Below is an example where we plot some `metadata` which exists within our context. ```python >>> from matplotlib import pyplot as plt @@ -67,7 +67,7 @@ Various visualization utilities. **Parameters** - * **metadata** ([*OBPMetadata*](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. + * **metadata** ([*OBPMetadata*](/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. * **axes** (*Axes*) – the matplotlib axes in which to plot. * **show\_legend** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – enable/disable showing the legend in the plot. @@ -78,7 +78,7 @@ Various visualization utilities. ### plot\_slice\_errors - + Plot the slice errors. This method populates the provided figure axes with a bar-plot of the truncation error incurred at each backpropagated slice. Below is an example where we plot some `metadata` which exists within our context. @@ -98,7 +98,7 @@ Various visualization utilities. **Parameters** - * **metadata** ([*OBPMetadata*](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. + * **metadata** ([*OBPMetadata*](/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. * **axes** (*Axes*) – the matplotlib axes in which to plot. * **show\_legend** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – enable/disable showing the legend in the plot. @@ -109,7 +109,7 @@ Various visualization utilities. ### plot\_num\_paulis - + Plot the number of Pauli terms. This method populates the provided figure axes with a line-plot of the number of Pauli terms at each backpropagated slice. Below is an example where we plot some `metadata` which exists within our context. @@ -129,7 +129,7 @@ Various visualization utilities. **Parameters** - * **metadata** ([*OBPMetadata*](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. + * **metadata** ([*OBPMetadata*](/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. * **axes** (*Axes*) – the matplotlib axes in which to plot. * **show\_legend** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – enable/disable showing the legend in the plot. @@ -140,7 +140,7 @@ Various visualization utilities. ### plot\_num\_truncated\_paulis - + Plot the number of truncated Pauli terms. This method populates the provided figure axes with a bar-plot of the number of the truncated Pauli terms at each backpropagated slice. Below is an example where we plot some `metadata` which exists within our context. @@ -160,7 +160,7 @@ Various visualization utilities. **Parameters** - * **metadata** ([*OBPMetadata*](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. + * **metadata** ([*OBPMetadata*](/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. * **axes** (*Axes*) – the matplotlib axes in which to plot. * **show\_legend** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – enable/disable showing the legend in the plot. @@ -171,7 +171,7 @@ Various visualization utilities. ### plot\_sum\_paulis - + Plot the total number of all Pauli terms. This method populates the provided figure axes with a line-plot of the total number of all Pauli terms at each backpropagated slice. Below is an example where we plot some `metadata` which exists within our context. @@ -191,7 +191,7 @@ Various visualization utilities. **Parameters** - * **metadata** ([*OBPMetadata*](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. + * **metadata** ([*OBPMetadata*](/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. * **axes** (*Axes*) – the matplotlib axes in which to plot. * **show\_legend** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – enable/disable showing the legend in the plot. @@ -202,7 +202,7 @@ Various visualization utilities. ### plot\_num\_qwc\_groups - + Plot the number of qubit-wise commuting Pauli groups. This method populates the provided figure axes with a line-plot of the number of qubit-wise commuting Pauli groups at each backpropagated slice. Below is an example where we plot some `metadata` which exists within our context. @@ -220,7 +220,7 @@ Various visualization utilities. **Parameters** - * **metadata** ([*OBPMetadata*](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. + * **metadata** ([*OBPMetadata*](/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. * **axes** (*Axes*) – the matplotlib axes in which to plot. * **show\_legend** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – enable/disable showing the legend in the plot. diff --git a/public/docs/api/qiskit-addon-obp/objects.inv b/public/docs/api/qiskit-addon-obp/objects.inv index c5791a33f253255c0a99f4893f0f3100b32be23c..d601ca6ddb41fbe8bdfd0ee38a487bc15e11214e 100644 GIT binary patch delta 2528 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 delta 3612 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 literal 0 HcmV?d00001 diff --git a/public/docs/images/addons/qiskit-addon-obp/guides/bound-error-using-p-norm/extracted-outputs/ff72e77f-e2c0-4cce-8575-c5aa587f78fb-0.avif b/public/docs/images/addons/qiskit-addon-obp/guides/bound-error-using-p-norm/extracted-outputs/ff72e77f-e2c0-4cce-8575-c5aa587f78fb-0.avif new file mode 100644 index 0000000000000000000000000000000000000000..722ad405b967a312564ed8de7f6058aaba68877b GIT binary patch literal 7140 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%0D5#Lxu^0166=&WDL=KOihvi0SGbP$mHAZ?E6G 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 z
VecX(eY>I#ZMcVb?~1QmZXH4kq@Cqhz4 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 CkHSm< literal 0 HcmV?d00001 diff --git a/public/docs/images/addons/qiskit-addon-obp/guides/truncate-operator-terms/extracted-outputs/297fc3b0-d3b4-432d-96cd-7e175b7e6a52-0.avif b/public/docs/images/addons/qiskit-addon-obp/guides/truncate-operator-terms/extracted-outputs/297fc3b0-d3b4-432d-96cd-7e175b7e6a52-0.avif new file mode 100644 index 0000000000000000000000000000000000000000..1f66445a312f2984275a03082527ca11adc8b1a5 GIT binary patch literal 11411 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®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
cUK*p-$QGAdM#V&9 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 U_X-(rPtf#pQk%;v>d%4y4=Mp`g8%>k literal 0 HcmV?d00001 diff --git a/public/docs/images/addons/qiskit-addon-obp/guides/truncate-operator-terms/extracted-outputs/69c9069a-9038-4319-8dc6-37a1be973ebf-0.avif b/public/docs/images/addons/qiskit-addon-obp/guides/truncate-operator-terms/extracted-outputs/69c9069a-9038-4319-8dc6-37a1be973ebf-0.avif new file mode 100644 index 0000000000000000000000000000000000000000..acab16b05d8b29f335bfd5bb1f7bb7754cbbbc5a GIT binary patch literal 12758 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 LSf5u=ef0f5(!gIC literal 0 HcmV?d00001 diff --git a/public/docs/images/addons/qiskit-addon-obp/guides/truncate-operator-terms/extracted-outputs/82271b0d-ddaf-4ad2-b5c6-e9e4c2a4cff7-0.avif b/public/docs/images/addons/qiskit-addon-obp/guides/truncate-operator-terms/extracted-outputs/82271b0d-ddaf-4ad2-b5c6-e9e4c2a4cff7-0.avif new file mode 100644 index 0000000000000000000000000000000000000000..04a0c5eda7bc5980d037564afb7b7db6249bcac5 GIT binary patch literal 16712 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

0$Z|3^wT#Y^ z_2TgD_S-dX)$RO5%_!{v@tqKj;FR(f#4UGqMNgBf`BFf+MfVz1^D-Z>8F%%u(3a7X z#31&=^ZYI>Iz8Yom#m&5-XRLJs{aJBHT1w!CKoRxZ8_TCQuG1%i0+|HVbo^q-Zc!f zdk%Ab-Usf4$--}+p=7gMkJ+NQ?(oqt^6>tH)AuAphFi3LoWWYwU1LiBX@Tl(Tx-n` z$dCQg_5se_r)JLIWXRJI%MGte9$MjN;7c{jnyc8c(aP8i!wd`_Z2r<|8^9xU0mx6o8i1{~0|35TPR`>1n*B}KKq zmo3KY96q+*Tg3j>K0)3rK}UNoWxZUb*hGH$Mo^C=HqBLx%?7GjCm;ABWlL8t{y_n@ zKGe#~49UuJNHR%^T_{gvmMmVSpXzzjnVaiR*5UdjP$KgKi)EXDjN!48&HpFA zRyCQ}_IYdEX$1nV8RavUmJ%Lhb>(tD*dobNWe=z3TQqkh+ykwdRtAozby<#Q^>-a3 zLt6q7%qL}X1heK&mOK8^rBfOJMB*zd7WTEdP7`Lfv`+HFl@yygD^MIR`Q@*Svy(p* z{@)w>(~Yp@1`3}659BB;$6&F`-(sK!6-vw5z|Xxw_}1l|%-Yy86Jh1pB@X z)(51GrZ3KQx#%F&Dd`cYpy+r|Qxny&f{j$JtjB6wfXw!h{)fXol(v3wTq-+v%K(h0 z^lmumN}(>fEygD0q?t{Q*pFN!>?NulWW@l2BKg%ogH`dghTAy@&d~u+R_LxIQ8T9W z_QCM{4=~BwGfj6rNV^^5LFMpojZ#*{Q>I0ylqHe8F@B9KN=%5vX_}OMMXe?4;zKcJ zgAq`8YbX3iKm#16(49v^06w1)%M_W`xMvaZ=r{tL1v zcsp{q-wQbARZX^3Wx;m3Rdh0Lh|{@<%gG&bEL|PG;tK>Juyo}wehCoV_c*+eT6M7m zgqH7U$2IH(F%(2heChoGAIxt>pclCpgOc5w$_f+{W${Ix!k=t;EM2_tcr_EDjV|X) zDEG%UHr8Z5VukzHX<;O4cEA)@JW{4G`zbkXwaR6oU2@(+H5H!Tl~QNs@;1Qd?-N$7 zKTcay>cz>k1WCVe#Go28XFII#C-Z{Owz%=$FY7tN{QhM&anM5f3GX`JQ?zJ<8p|5( zEcz%f>js^_#)QWCV%XY=LyZ*eO3W8bss$StJFzlN%w8+QSQYT<@%o5cOmktNrGFXrb3^ZyxFy; z`|ok8Q4G;D(i@a1DZ;tZbEOo8*r*|WJ`}#9wYz^Sie8Rr$&9h4JyY5Lm?@FM;K%mR z;uXt0LHq6W{LBCUoaRU$Hhkycn8_o`y%#uX^k z#;u5?e4;HXr_uMoET&@i+Ei@SRhu|@l|Myy6y!(&?68wakS)&|*FR~(JW5V^r)?`O zKY;xW@m!v|Rc8D}|97{%5Sx}!+}wAy_x`qwWi>Nqwb_m6=@>0VdrCs_kNWb<>ETWAqnZogezP$|ww zKG3mq*uAOb&yJxFgdcoVUXI(HuNn>;DVSXG!wBW|m z5_h_o-pF23yxgC2k9-t8J}0~w%$RdFO+-Y+&bD{vKbt_-sA8DrWKbkq;A6wsP;PiBo=#sqjYL>=x3*r<-X-E9svKgY}M6 zX+u!;1HCQg?sgmhJlepHl~Q^YvY>3uCi#GNvY7BzqFDl;H`3#JX2)Z();S$I;24k8 zcGzz07|h^_y$fSKgId0v@2H&=BQS`RVzZ2 zU&x>DUC$4+g85raHOb)wlefh<#$0SEHvZyF$o`JM*qqwD?WxvooQd+;6<|i6k4_3K z+gPcf2Mv2BqHC_7Y-D2QJffpDgV(_5ErjvTE6{Qk<=$K`?^a+t;B26YK9)?qO>% zzDsIh3aX3`6uzG@due3qs0T^HnI`oH{|(2;AVCWFg%j$ocxtM|-hoTWTb`N^)^(u& zZGRAE#S!)AEDAzXGtcN|R8N-nKo~?bzQ`&c@|ahUZY1hwIS}sDLd^&<;m+aGj#}mb z>9+M`8*d&oc_eZOVIx+Cn-rOkGF`8{*b-Ljhzt0%+S>6q1>wN80cOx9DYWFw8`o$X zEk^fOCp;u2XzE_U zwhSDrq#p`9guQ-GA8JZ_>^00;kAEeUU*LS&^L~5LQFTp`I*>|86bm2&Kg{na?Zjs@ zTJo4rBYfhr0er{+Dkxu!qy}MlOpq(!4itPkcpG+m0kd`ML|6zXaPTC$&n3jfb zY`4tNIbLy;RTzqze>S2&ghFZvjI8L0`F0>w?nFd`@a)V_t&EXtl_ z?;HyOT937y65({nm`^{Tw?i+>IFcsZ&xD~K+2V|+4w5hQ30Z~(HUSAd8*q#B>x1w-%AEdB&OL6*U~$eN<#O_B z@J@KPbyC0QZhV{uYd_@VY5Hj z_pi3dg#I!@Z+M!LuFrJF^+8Z$GI}``g+uRw^rcMcPtz|nz*ygxPn|!pY?rH2Ca7G7?|q zTXWA_?wk?gw2PSU^U8Go%CDJtz8S;g-aZlI7_c7~6yvd(Dcm&gbKzjGa>r;H1=+V` z!R+a?Ucb}Wyv#Ppen~=QG5T80ezsb2t;~?cGQf@~IbyqCQwIu|c|0}L=N%T&acGF` z(GZ+J1Wcu}Ec%r33zE~ae3TT@|Kg)UdvF$A8e|v4V=TGp0}0+W{o~Ouwl-!%PzlNU ziTb2;z1)|?xf>e+w0A`n5N(M47huO+v3B2$p3F8)AVgzid?;5Mof%m;Z! zIOTnZ8i)hg8#bk53u%bEz>xDjy*~h7mUR&_p$@f9vyvT|lOea^*($3+_M=)h(fHWUQso zKO;;BY9Ek)$d$M`oW@cZwhLxrH=4+YypJsfPq;!zkF2K1pc( zo8}mI`kd1H-nE+cINtSPeQF_?q$|Qb9fKyYkvap@RwKj&>L!NfaaL`g9efc4xB^PnI1P4($ zjVAXG&hWD?@{I@Kk0Ed5(M}iDMBVtF+ki6C)=)##xzsN0kcWHC@1x)uoIU&icgR4c z;K&X@eTH1CX-}3z{)_(;5NEufrBKpd-?;o!C9Nv&fI=e`&v`D6vh<7bC(AX#4F(i+ zgQTL%$(P-NQ&hp0^Y>*xb)Rya0@Af1+pX}h`NR1w_!r!44#9Q&O3lil5F8IsJAszH zT|}@Oc`ErX%0vfZ5SyVp#8$e)OiwEfUChY$<7%1T%yxF^$~TDKokdbB7+yyIWV)^D zvuR~xWgTF~S{~5>WP?>3WSHYUw*`Z$9-%-}-!?5=>mnNug{ZtxW_6YI9?x^5S@F#N zvPWT`OK9@b5}HI{UHfIFiNpN(e!S~>_4uj)L>Au@XcMrwZ~@=toV}RPq|in zw+5|%frN-^f`C`Ik$CwfLVj0Bd{B*XdqD6b*`m1z$@rm zL|D0gKyUq*FY1&D%%jT+BX70l~A=KN^#C|wa1i-~=yc52>~Wl}C) z1O9s0-G+6H?CZ^~xW(*tHyI_g4N{c;0&5So&!h#qs6CiW0@oV(lg$PIt`P!x zLk0@vvV#&~bq+M6AK1x@l#T760<^sgE-sOyfeZ#P5oD_` zX79cT^LmcPb}LK;LY!=`;#Qx6=C7$zCNghzyW3ViS*p0tIj(1eB0g)hzXD8(;TBYb zdkIby6LOTTshRIxE2GynF#AF^@p7SfHAHoQKvI|4UcBW4^hG;zh{)K0p2;d$kS5#^ zDTLP|I*h4*-BkuG+gn~s$I0=|ha+l66Xmv)uh2BoYx!TWH0aDA_}Yy*fdR4h7I?DlFk7GKW-3 z)+rdnE6~XFeb6HaDGO&aR$RQ`zFj> zq9Ofw*dT*HOUWlW1W&)xyLpvtQwNctY@;BC%agRKKt3wgfZ zD4=E;m?#jTJ4BNmU0o+)6=0mt->lydxevngA@;Y3wMuCmr#8|baF=`CWa59$hvQU^ zuLU=zW^cjD8O}70E;mbqQ69F{bmb45XS&1j?e>|LB@1O;20H9!K}4MYt{@y+I+gBd zG{JJE15XmHrgOnl@XNLts$#FKj z_zac{j^V+vT7g;24jdBG71Nm~FCjf1B;6=#HFCR`=sGtz2c3M!8`bL5Pp}0G9w>35 zlx&hIOrqcUQZhxAIrcU>f{KaM*76kGIxeHt6UM)qEUnjTF7F%e7G}KzTDt{X=UG9I zhPx}aC?!-xW!IXO1KdMnX|I~AIpCtH>`$oAvL!6P+z4z6D+kh$T?bTgN`)Oc^%kMz zI5?$L=N?wVoO9T5xyWpB43xJYGb(~+__-f7;htXVb;Jc`_W$JbDhIdS3?fJk#H zlxycCP+C*aG0K(q{61*h|AQAJ%t!1rcvoKf0uuNIfqQGygbGLK(U@dRp@Mgv2EM7ZQFLP*vZDWZQHiF(Z+T*wm01T_w&7=06Mui{WGJ1PG*k(GQ5cgi&zje{C^GTKvyS= z{{R30`OgCr`3I1lfL_4=6fkIL=zr<|SC9Xn^lys)^FaP{xJ}%>#Qu}rT^xAroh+>W zw}|qZ0nMCvU4OW`S=hVs{;L7n0Zm+f@S4~;S)2S&PG0$nWrZ_Iz6``2vuzYY2~Bu})xxrrMp02UUP*3~0u2m}E#l(oP`J`nT`UWyMz z(F%{VB#}bP>$gKz#N(Q5$;M9LcyzyBD$iY`a_oLrb-S*aY!gKzW5bd25X)zWvhHN(=f{f;f+6s4(Q=F&3`A@~t|-KP z&7)ud2vG_vm~lG?w)4z@^G~BFWAvt_02wCm$`;rU1?5>EjGi1ilY|GWP;jhVq8ax& zlMFXdE(LZKyNdqXRlv43?j|8H^99;!r45 zRK{ieWYrljbbs*Ryr{dg#|M2>qoxOs|Iv(F{^b17iuyb?<7BA%b}{Z9FFE`jxmNeZ zt8QUlbD#oSGOZd&{fl3ir{H_^pgydhnr}7iq5np$R2l!;2R}D(e|lsuON~3%2ThK& zU0b?@cdX)qVvLj+8EyI6&)jNf7!ekcUn3s1UJMNulhr1>r437}a#y4kA*pbC(-GgM zZ}`@X%U>sYjG|a$##MhaRg=XzrZ@fELgDe~$=gCDs=m*?uwJf(5D!hTb*VColZ(Gh zKU6ZZxgpS?P`fd#oWY1mX#!X2HAhqGM$Uw;ZA#%f_bTa;6G&kTH?(dw)mWH<;8KSrk=%>hANX^-d z+gO5CK1T`u^>D7%xLz`&p!FlEc0MtVQ*ddm>wwZ(uPwjsxN|Eof}ESyp&-872gj~5 z=pfyG?;f-;NS`Og-0Zmi#u4p})7}La3MQ({C~bnjz`l?}Xs5>TSw;U4DUr&MZ%nB- zD=mt?;G)#`=EcAXvURf;EgysPMN;2EFC)+3EcmZ4%T0z6f~2i7T9Y23N0+rN<%{M_ zHlxY1B!mo!y(o7ra3`u;$2nO%+OR=C)cP}fOtfAU6S>Sbg$61ytL_QLF?{$( zzvEnDV-lRc zsr^kee=-F`9tc`CS1EUbu}Axhc8JhnmjTb1?Ene>(9pTE&zn#(h4fG?gZeHg2iAwQ@x$uxBvyv*D$QsU;lM)5IV{+4Hwvv?ecQukpKLjQ zRkfL^cr4r`qZgVbrJE=GU@4~g(B(zvd!ec&ZTzJrRP+bX>WbU=6E!~c?!^L@5ta>r z#RKyEppy~s^Z=0nRLWr`^+&QBG3VxhBUIHav*J``z;rhw?##C^gy*<-PIaouKxD}M$0x}6Qau7(;`8CJ60ygr_M;9!S>|D|+`9qw6lgM{w}v-F zVsK#tpWBS}Dcjon2;BZOYc}7LMgJY;C|0G`K%JNFH?naf^R#X1b9E}z+&H1QrV2#- zlO1wF7-K7Ynv|E|nW3zow{@sE$&ed@B&G7>>Tn@m_GY4ha^(_OwKeI`3Jc+8B*`*eWs>v=gP8GuVlZ~b>v;Hat z_r(C)gsD$DbFbm)A+3`DwS7tQ&bObQBkez&C|n})N8@VH%lwL6<~qb}Q5W1cIUZ() z@Tz2Odz@_G7Qv=ik@pLu98UacP{SY#A8qcqM%BcKT2MGk8g5;H;eL2)&bK%*vrHKy zr;J9ts2^6*FI9ITQMNMm^+#q(OQ_A=L60u2hzp?OQ04<@Y&yuhvy5SjD|%#rMOJu! zmFh3S=`mNCWyCnSD!zvh+Lsu*F(Dvo-$ATSh9^0?nozQ~^1#{%9{^>ugEHXcjI}1g zGd0&Zd1p<}#aWe1Ja8uod$}^Slf~)K0rDP=tm#~fD*7O96Hg*rYmvZ+dK7zAz~EV8kOS?9>0=y-d_9%Q5h3G_9(sn)op@BF?q3uVGG~TO@hxm zOwy`#OnXA~CxekzfNt+wtXn$?)#`qVa$l_Jm~W<4I$i0)h{t3&M9hjnKhyl?-1LT? z_4YH?R+tJash?YX^5UjDg9OTv)4*+NkcVtS{>I{B1F0U^5-5*JAa7P}Va8^Z&d);y zr868lBY7Utt$uLKE}akpd+t2TqL$w#F{e|C1#V=x=CWq*EqFT9_>F0(AXl^@aa2DV zdyM-0y2}wJDx6Nc^F9f+9dAhGDKD-w2 zeKzYgYDgV+(iCm^yS9D$wMLuLmH#{dZp4BR6M+xb9U|VbGnn=n})TE`m{o{5^2qY=#4Ct{IZxoP3hCAGnk)}H%>qv6z* zIZM~t5#HISyVu(MopAEJJ4=%y?D=O!Pvq%anj}*4A)-?_f7JjmxNn@ys3fQ=C0sGd z?{2ake0{_>-#7)?wn+hoOdA)lh8xs~gQMVySmuYN4ku_ksChf&X&5*9+ePlH?c-B` z87ca6jJSME))BPULD_HhDaJVOGk*3Xa<*vMprGq%m$KQF23!J)mSD0!G>Ol3{vQ+po#tu7$B_xukQPx6LUYK^}SMSI~qkhEc^lu7u6qX~SCI|^^%Zq#R-sJq+xMxvlhIO6a zloMtw4D4%6J&h#d4bfbk20>VpS$QH?gvZ)%JpA>%HnO4Mr$z{t&Y2bpNECfhY;vkr z^TufqoRb-k{n>m&9E@MJHp^2diXl`eGPbI_^YYrK^WZ7^cer~@hdfo13SzqjiL`OJ z(h}}mj*Tjp*Fi+${)^jY_HK@4U7rWsTs-Ws=`-C)lfhFtTX>V=8jt9j@eqO@zp5k5+F`>U=lSf` z66cpp{)g7X~6g=t+yy%2>#s_F72wM%49^)3bLOz^bz0;n_}c z@X}*QhEpzXzf6tzpFG!m5nR0M6tilx7ZA;C7Y#gY@TsX<4{HVh1bEst&Ed@242@~A zg}#6PP&bq-w!s6U)Iv?ES36oRfE#-U4Lf3cR}PHhCddwhFY~~_`y-c& zeED=_+mvu&U3E8RC~D67r7D#274<3_MGwipbZEX0)4XQC6ekL7D4O zD0n^aG){ZVLs(QpE%F;i$lf+Z(ow0^JO7~LW(Iv!stB>+ArcS`w-Co1wnLj?YGi#aN5_c*?mZ}=b>P>*$RuJ5+U9E;(P`i>Aj`c@ZC3oZ8hMi^xN0)V#0kgaU zQN}#6{Zb&fn?km3$ggvh5`x9|ICB8H3>!q*pBEQp625e^pc+yrcWfx|Ye$R2s6fba zXaX-Tp!!s$glg@(xk7NICs<}<_IT~XumilyT zV%taixAYZkcS^ckkuZBK!Jj}F&HL7tZ?88Ig>K?uq&hXw(jOAW#0GKrvgYd73iENx z4`xRwYuiR6J%Y{lJ-LZFdqRjF9uI~--HT#+(o9pq$q?9YaZ5A z&-g`XH94pt#k_X-<>$(%6ZUL@N*`$oYqbS2D>XKO9DjzR zMMHg|Q#C7=lc3x;en!gLHCC#|GBse^vJn9RL@+aix>_0g(48p6J?pfnmEgu~?D_kA zJ*OXV2>Xav8o}MV02ANUls#pY6_4Bz-hvbc>c7NI>S;o1#U$c|@@8+%VzIG!`7=o6 zzUXq^{h-0RF5kHtTib3E1)ZU!LKPGQh!X}&^(Z3ZU|sBaCsw-YfIQA>Vs*SJD*qI$50d+ zo8MV`68X1?7Yg37ndX9^cQ@5Dhv*Iw~0Y67ZG3U=RwZrzIEw^D)(s9#x{6~FmJry2fO&3#3}6YgB7=y2Hfynj%q ztK)xuH1E_1=vvALs|>^DDaOU@vWDytQ8vi>1znD)q0n|9TT5WC4}crd^v*DH;qzP1 zFdj#n$pUZWjicjM!hB2o22&Ry6X-GxDqo7Xx8jMDeV*a>RZ5H%Eok6z(jIG;-I_Gt zK^2^!&2prs4j%@G7^`2OnzDuiXM75~qwB@L_iR(B$qaC+p^=u?1UFspnGmRK!DpU9 z>MdbzJ;KNwf^3KfOLjR^_r8?A19qH1s;2UF&tN5_gAn}U2|y(`M&JSpY=7}&oXr~l zwLZ!=gj*C)%4e5sbA*1|M(*Jq;!5rQ-1)r#-Qe$}lFuYbB2E-4ys*mXJAyUK@>9t5 z;R=C-)jguJp9_Y%tB#XrLu1a@5$JfQhycWTecAA6OY>ECYF&*fp4FYZC zmg`u|%--JzA{oaZYw9hVKGP0)y(6@kw^GiFL{+5{z^_Yun*2{FWo$E5359~mrl zgkMG>Yj_eYgMm{x|YPDJk@1g>k)rz;=kgJ_HUwU%-MN0g`xAt#? zdhl^e@-+`@<}9nFf57)14(Ctwxs%9aSO#p^SHEITdACacFgeY%&^x$#f-JXLQA`pE zFUm$g%iKMyT7MocXEo2ZBXDXME#k-HC37d7Hv1FBS0!)b3FnPK@#q;t#ZFoQY00D! zEF#z|{sQL0)0lO8?9K_zM}%J6xc1Nyf!Bb0S+t#Cyqg~}ZYqw;L0Sk|_D&H<54Ab07vyYk<@jpA zJ@Ep-xpxrCuE~!|)ag$P?X9-rZ-!80R9A1RD&pI?m2>`!pCWU`v@1xqR;nnVs(*TKFaQ0(#n%azreb%2TkX>R`Bk*AI?4pOeM!@M|O- z+-R#NywPp+9Mz$++(fECd-X0sR0v0}F+8C{?G<4J10qnL>4Hg{D>`{F8|HI+R-8>& zlFe+_hxX0*O&M`>ijg1anTLB!>yLAFUb0SCAnVtnnac z0E^Vq#>uQXW6KR&#qk`SxKn%7c4;{EABl|(0&cj!<@R4c3^6-0{T#!dGVJlm^B3U zrE87oXB2Jo-w*A9ym|uS*gtv30&=zbQdXW83z9;!EXwMa*PPidBA_f`787B~T`lW7 zJ}Ht9Ekk@s2LaatJbzU~OiwDct(lkNWY zFYoEXDIwffRaCH|C7&Ra2)D9sOon-%rD%ship)&Dox0_f;K|^87h$nRf*SCcpOKci zk5EkOq|A?!JmIbz0ftp@ak&(qXo*7Lpo=FMNM8tJz6B%tBI>gc7lk=BpjY+~T0VsV zd)Bv`z@v_NMT_~*?PYn^c99!w^+vNbOz{V0zHO zP){!<`q%+N%E*BDiNZSDDRR(MQKSv-Th&Bq>OBk_z0=t*{EZOYC2*8FNt8su55Ii6 z!cg8O&nbiUy4yg11KXSIBkJz=pUHFB6+^?_P}USlkhiQ@fuJ#OAU04*JUo1>5Ygfd zUHTc!$ZksN%YwVhAhk-=Ram&WT-)o|33aGzT#K`9eVRnbwbUUrGz4z-BeyWCWu(go$N@MAIK4l1E+7$cyEyNv|$n*6?Vq1O_ojF~;!j2w#Y2I4>4D?SmT4ziiKy z@SL7xIYsDL>r=tCq}LJ7+GS9DbIu-*K1oH9^xP3yNK3((@9WXS%Pf5tPUEiyS5er% zEwp`P1Y&-p)m|suebK}V5ft1XkSO3nmvuuBP9J6@!?NZB;GlhCMR!2>-Tjf&rQ0OE zD?{R@q`cWb9^G0IO5`z7greBca2k*uIS>V7Q4#~{kLeALng{zb5iPvM&O?3PI(l5k zH95N!PvcA(S6L1o=Zt9(&%#qC09%nF&v0lAx0mmEeY3N=fH>r)u5DD4D z<_3SHU8{+F^Q{jCkb=181=BT?tw)bT#yMr?Af6id`x#Qt*e1XW^H^A9X7}&UqbnMf zPG_W*RGs%~!~D*zc`S~h^8lvZ1kK5=cXeuqL4@oCTkkF;zqdKji)~AMN2-)T3p}`k zH;B+z1NefEFHhcJtna=m*M2kfOGu$Z4YKHGzbisWaPUzqwJR?@D969Uq{D~TbHB0j z_CakIm>j~#)SR`_l}F*tazQRd#ckEPGFaxT4=bzal;HjpWym@uYxvvt9xmA)wSajx zTU~G95ZgVv+RG$$7Cj>`^6m^IBq3x!eK5n-E*=?=^nbv~>lR5yWsWu8lXPW0_!{!+ zkZCend201XYM}!6id-K-dcgDya0T1O2dW^@`fA(E3e1m1G7>O}-{ z1-f1eJ$2;5^5+Np*<`LfQPo9M=`a}buW~Y`-Vq16t)#^3+i8PUD}brq_y|AuFI0Y<`c@hQmC|L z#V{Gpg?9ty59)TgMoe%29%pk4hV0NTy~F9~5|bLmP}L3wlHNB28I%1u>XFw^FGa%|1$ln5oX(oXdXL{`x(Mk)VLZD2A%DP;%G{*<{a)({H7p;PCoFHM(#M zD&Th`d{+h#3FHoYsjDW9yfhDelOJ4Ifp$GV|HfIs=i2rcXQZl>isR)(zH!1{ZzQa) z%kB5wX#TrpszBi#HuAP|-&Mj~iLCSp9Fgr`o5f6@30xK9JFcas(6uvD1Gd)3W8kji z@U+6<*EMk~#xCfl;A~VfEFp3pE7~T3D_X#)1fCI`&0#80bjkKzlQbAORTB(`O)Zs< z$Fve*48b$C-+u48|4m7|PDn}F#%hA5OAYT;eqQ(}28SnFnq&3@^;%sRf<3tM=*s8) zDS|?DauT%$(a3pJ8@50^PUbzpmA+wf>q06hyKOd(vF@|xcP%@QsqWTn*&x7$lCgL) z`Fj0Z2>xunM5`nsUED_1>a<|cD*wS)I$yZ7doM$`p1}4|_W~J-;K@4>{-h&ET(IqQ z){1Y`sf*Bfqt^ftcJgOMEsH4Ls2G)_$+-~fUWvjf4$XM*9|3?^g^2TjqWxhHt!QrX zdwnRJ&QycTAY!h^owO71n3Glku2uMAhs{al+3oZ)e znn%8ozyNbrUmLdt&!sh-5Y~uGgrrN8Arvw^VZ6}z#1B|6iMvQOE`KRTZktj#W??_{NxtiFoI&rtH;){alh^S>Iu9>zfd`ev~Tf*mn zxOL&*1)uj!b0pq~lgLl(ENJOlfZ=WHrivAL5Wlc8Q7R6N1h&7sMCnVHv(9 z+z!4aVd+4+*cs9LnvMA;jGv+{lsRW(bD1f9ljyF07msoh>zIk&6n|uvf|{hP+Cy20 zTW5%l3Ko*)y3Z_VKU9mV#Cq5ZJNON_k!;o^$FeS(?dviLU5CbvIxw6tp#lo%t#VWA zko-OSVT(nieOec>X@%p4>Is-|FkUD-4v!EZAUP7hivyIk4~C=?@>OC~4-)CH@`By} zKpqM4@3H!E)*`^g{8E(v%&!sNx$ZwOI1gSkLKe*2RNcZt)c++EY0KQbj;RkMr!;E< zuWLQ=#qr2#_dVlU0E(o2F3@e7!ib@)Wtc*5FZ`eIjS}M1vXx6n*=l!7PpOI~a z{dNfl)jzPO#O4j+7m|wH5Juv6zdXdvXFBni63?=$F>oTW?MUTx(usU}4es^EGdvI-pGJYgR@g0oD_s2@Aj#o!o#z zXP9|e)h~96nCTm^ZF%88BF8{oP{(L$3tjm4lrFnjxATF(opX@CShfh2B_ZdeHrTk> z`M;rc;X##IN!hR=IX)=9OgroTG%PU#PU2$_bpnD}j!3Lm8m4To;&q7)^ft%gDDv+9 zkQ)b}8t%&5b9b&)%k->4Lg2@wfsM8-L#FaTGsz%*IQ?zqayL0@yxH#Lr?1W0`PuC# zKU8sH+j`(Wmq|E^zoFM*r#bHam&SpNhKdXp6%d>`J@7L*m991SPj$+nqHi4bnTS}z zSiM&2^u-+XFSFQ`{E}b($yL?Z{D4or6&4@kt57;2U|ltW66LaxVnLvaz@%Q98#MNM z@EC+Ex~kd$Ljv8}&eiKzl6FU}@c@Zn_|sfY`P-0|ZfxK%BNYMi1g3w<(TVHnuxe-B0;a9^QC zThZBiPBos@*+-M0#jvT^NcR1OmIC++9s73l}!r1>P$a!>(Dqi-@9 zz&&X2`_GnYJ&VDa_3S4U=i$QQxp4*PbsL-C5~Ww*V1N9OE^Y)EL6UfAUwCtR^dNi2 z+3MG_FA~DbhuP${atS+bX6|aOX42!&Ti)%PA3;#DaahXHTmHSC!Q$ zh0XR>(r?&~BWz9&8@aoP5BxQ<3+F6#J8KvTN=ZC!sk?K8N^M!QgTh-l2B9E|tJ}7h z#ey@qE%NjVDsAHxb77G(^V{$M2F#?DEk5zb3I=zc*7XaXKV+h42)uD_$z*k^@M#EQ zYZy93-0ob^eBH1#y8#U_AkR=$+5{D(4>*<7%Pg9%fLpW4YA)fTa4N3bCuZDY+Fst( zoE4YyF9#GS^1Um`?NHma-oE_4A?3UN_AwEwb!iq`rtRbk*P9nel4E9oSg3X{@#e(F z2J3sh0GDk{bYjk}QDpE)@gw_^6oAM~>b+a3u~om0#2f2J1F{!kwPPSYqf7gSh}ff? z2{hSR_q3tZ>~JZrse681PGh&^@Oi+M%xtnu1jTyz9(~RmSVY8^wAe2yYA^7b9L8Mh z?{v{sku4w5ft`q5Z!sw)@|vR}l>T*3m-Jbupc4qA<*E?;Yo$}%25lD3&(m3<`ZQ8| zYL3pYb{>n^X9Dyc@FK#N zl(keRyC1WJ5AyYr$DfH?kL$+dg_;l*o%68Rq=GC$4M_{^DMK$a5rQ+;H%A#~r-Nh| zIxbWX=JMCYSq{?FA2~@pjayvR*5c`!EEuUJ4KB9>F?-!+g;uL5tFN~} zer(3H((yN=3eis5Ql2Vz8Xuf8CT8ArlAKqG_MIq=#8Af_Q;=sfihHL%;`3D>c%?L4 zgbYL~b^@29&xk-*ggbYCUhbpk+q`WtKY~R_vZvWpR4TmSrxTaVX!^?H4Cj)sX1Khj zDr(N3IeC*YVL~D%po8%=TuVLFQCIL`dv^3$)txYQWjvynf;B>aGe8J1VbHE@bczcn z!ppC+6D^*$J#xvmJEmnpAv+T^ul2tVFSJBz;gg_lR*kU4I&Ta34l|ZEm8xD$eT`e0 ztZ$5E#zg0nWwyaI+L$e)f+CNNw4kc((jm4GJRg~A&H01I2WvZ9w~jIuXuPyV@sUHQ z`NbEUsQYH*^8tQfWoNKlIlt|$__ag{bekLlYh?xtp?LOLmE~h~DL!~YNNC1&Fl6yZ zH@K(dX-~f{NF__@6COf^_nI8`2a`18v*tvTWKvbZK}9&Ft-ToxviLH$p^cpu9`diV zlJCmGUA!o%PdbXais{|_F6w`emo+^X<7waz=+j8jU%pM}l!o-=#6kizl?q@(Dno0f zN%9bDt{Ij2FtsWf)NaeM1@Ykd-=C~1dDm(jI0b*Z9VV>$bqhE1o;B8>6+SG8t zm>Q5Q0(LWcEoXPy82XA_D`DRF=xM~H#^*i@K+!~0%x3O!QDJzcBx39VS4@|B68jnA z4igCj8(8m9jgwM}u54#eH!<)+fb6cc3(_r_Yt8ks-h6~gVC+7REU|ZNVk_*{5js%Zf<(OI5Cu}Ytm^ukvm=a>l!dXet@VU9&dq_3 zhPvUc%fh_>aW=RRT77lEp_KY;J8A868)@-_A>1k|YnyNTd{tX)M>V!MMNkDYw8b+$ zPV@Yx7Nj9UUaq30fRVaYkp6iYdmcOM-Fvw-}jk^ZayL-vZT+@nfls`(U-&^pfA4cFy99QnL ze(N+>+M@4aIu9mpact!VdFRTP>NoS&o-X26mx>L|Z|f)>jwT8L`D{AOgXanYfT1!#(Jj0gp9@ zd`*z=j&C!};oh{z+9yCg66?9RH)3`izd84&H|kCMW1Ezetdh_eVF=pi`SL1Kk<8QE z!t9_-^2wiuE-j3;nPLQGdq4&p-6GBgqpi3*vJ*+sDCzF6;X+K6fc13)N$lt5%-1^o z)GSz+XRbgo!6}$Q_fwh8ITii}!qLc-#NPI*E>$*M_4!W${oXCHAL{Z)wsg}SH+h5V zuD>B#RfHPC*C0LI#T%wqO_#rJnx7;)cLm`hS`_GjB~l5l*qE8Zt*sJu9F&~C_2TvU zBQ=dlC?i2@wE}!BeszOmrct?$EysW0Rr^LWMp<*48CM(TD`k5sL`1J#JN7}pH6k~2 zyf*Ls!pH});ww15y(T~0!V?4CmeR|h=GLwe4|LMCRp2b=JYfuq`J40m3)dI1VLnGrciYs~6LL{(;lAyY=zDvGSp6{GdPuH~EM zrV?2%a=Lm$^a}o5R=htmPa1eZY$9#elre%nBcm9Et77?i96lpGIyP+tjC~f!DxQTeR2&>OoHy0ypQ#fL?BA&vL z>hpmwB*1c8ZC8WzDfL$K4X17Z&OD8LPz_S(7ZM}xtK%?Iy0zw;}R7+88R|x z+qOu}{nt6g14&$U3tOEGnKDP5lr5(;<{-`5GI`R0$l!@=%@Tp=W0isc9B#kYLnWUA zC%Bg~{U^!nj_8mX`vj-%b*Xq^E|(VrHU1KV+Q;1-u?0?>H6)e|95Z{MyY+QW2}GLO zZ__R7=$5R{@AR6W^Mkqe0`<2;m*KBZX?Ie{$a#siocnO`NrWj>yO814A(Cz%_h7}D z_)VpI3_Cl`iZQq0r$}W_$ojRnX*pB3v^zH?L!}~NTxSy`P2}6HKK_IF9gUviruiS- zXFd^s1eKw411}mtb)OEy{vawD>=YWghYOm25hm?moN6h{4R+qga=IQea)rr2JYrs4 z7n``wE;J*`TQ_DK?#qV|yE}dLsWG%3X}{3NKt%2ElIC}MqS7Hea#E=?kGh_F+bP^m zfYrl=m;P*O$_>m;(R|%nhl)CBM_wojCp|oP#(9ss&*0+1@o(~T{P>j_X_SjlZDk43 zg>aYMsU3_5`-=~DGHy%o^?4lRrEV^~eiofczs#~y!cM`1S2-ejZZs=&-)lz#jIA0e zAi4U9jN<(!U6x*9m+3kg+4Fs7H`26LzJ4<1TC|i@$xEYCwq&JO>8TcRjG0tK121Pp zGjc(2FTL8^diT9)|9EysfT^}sw@^FmFtv8`ke2xanC~dueoWmhep*g32875(HFmpgLK?OVCW{n42Ckm?AcKKr)Fg z89JY%BC$H;758fHeDZU-WUz4GHGE3Gb1$Qy3i2*G`Pz7NBeGe!D%7|fgIB2=5P-NQ zB%J8lUjJ9#TXpah#&1HT5c&qu_MIHui=LbR$)D)`F_ z5C@t_Aq`Xzh)dk5cIJ_FdrwbU=p{Qoc!d#R6~r^w(&Ps2X%o2 zF?w$5`lL6>CaU9FniUI-)${Q_w$o<$ooVB&>>21}gJ)+=rPB$$tUB=enQ%1LCCBb! z%1O)Ej1OM)t)3=N^f9&XGu}TMe;7ZQ#dlv2v5>5hg@P>4_p0vZzr=dUr?Ws++GVx5 z1)Y8%@}Q~J;9mSV1wqL_{I#P(Q+w);Eg~hR`5KVy;njf8%ww6nElLAU2yU*Q>uSX^ zpQ9&nv|6df~efZ zU`MJJ1w*W3NYT2R|A+F}t=|WdWFw$8s@2=FnpC(GqXi278=i?|D`vC2^ zRs)qMII3quZ&fDX-#FecFw+U1Vl#Lj;cVdjE~L1Ep!N(2@HBf_?kYxZfM-!N39F-? zTV~cr!r-bkcGFBluR|gAChWS^g{nRDnIIKa9~eY3$a7q#K{x>r$%DX*g%xXgg$I>R zo!(f2+HaO41BytmLduN>-8{foPF@PI+N#i+@*1veSPz<~ zdz4sB4Gt7tq*Svy=^^i#LjxD=#WBjHhS=ZI&#`L`iyzabbN)P<70IWP=7dqI`;2%& z?@p@MCxsR>wZU}hF5R9gdu#`LpTzcVgd2MrOjCAR-)B3M-5u`tHg`b z5W&DVijq=QQrug0V(D1 zs}GTLVQq5e?9>+?=f4sQ#T`96dIA_=Aa%3QU|7iY4f?vY*W0DzNB8WpDV+&eM_Nx= zInB6}Z*0~forH%+@X5}y>;8SD6_{$fVqs7`J1MTG$t|gibh9ALW}K*nq$7%?3yspy zm4?BLVNHGtyPo6g5Ce=ByKk-zFg`{r&4*s!p6#678&A`L5MLF~@OFU?)%SN|ovp03 zk62PS6?NV%OFwhnOCj*6@_Eq>M1O(Bq{T@wopuX(L-prETy@;xPMQDaZ-@%($#!gc z+KQ)D4O2k;vSz{FImAO)cE-KaJw~Ht)MlKPQl8SZKU2pE!f7Qo3*Yz29P&MKVi*g$ zz=u=iAjUgPcdJEs(8Eco%{D{>-{5Z!3TN2cCi?LljgrZ}P|I%H+%U0|bsccgoUZ4W zzcfZl>new%BKLRPx&3Csfm8QUOY{Ja%_m>T*$Tz`Yx8T-@GATQ*tla@+@@&E!F3g0 zK&if|&y>0GGajnS#6(fra`0T0lcxldn?M?b84I-ywA9>W=ZOM;FIZKfRDHukeDCQB z8n@~TI<8D2>g=eX_uBQ?d-7Z%&9y~gURp?ObI>Z;0}Sk%B>?{}&D)GNl6K?c2MQLa zTarZ)%(+-DP3PYryaB9yyOLRLAupur$X<2s^}EJAY@uDYqC8c5b|Ax_!-|%T6&LbL zKeEp`BBjol8f#1l!F$=Um!_J-eSXJF|J#FfDiya-k2q;l$j0nBN!J-10z%qwyU$L( z#;X`pjPaT2k4N~MafKTEvhp|j0@ibVqP=0tdpDE8-$G+I5#0%XCC4r|rj>J7u>b`n z;y7m9AFMMTwPtI(Qt1P5H;u-AfB2Y0kNhI<9}Bz1yQ=z5CVEbYVA=M6g1@!mJ@3lba8qAD7fFBgk`(#A za!EmxkeEKv4RWGx4?N-M$;5H~#qM-!Rhe72rtihyN?k|NEx1wh~I05P?8E3 z7fqSsOB`1dR^DiOS4s|9o_+C^Q(s2K)PmqJ%j=yJugXvJafp@GG+|A$n)5D-I&Qr)*SWcDE5h1!k zh^ZPrHc>`&vT|pbjMjc^iD$1$LI^jdIFxwWf@PE4@>e6DXnd2{I(7}lD$gy=xA0cgKz4Wf>XYz4X5T-@bAi3P{<2wsW9Tk+OZSIU{VmSelPfIOao~Z&f zD&J}}ugp*d_$NhD6Rq$;yO;!twalsI3b4s>cA z6WF5xGmYn^u?Dmez}gn{!VJ{qS@tr}Qc7m(tmnWo)syzs+vCH60ch8;qa z2)ocjdT73-I2_fI5ZU|&l}Dyu==o4TMrg26YC=>s$V6`Lb2Ef1tbl*~L}-z>O}cF| z2zphp!lNv86K2nxP-#Q;!EbrcUyYE~j}Qe)9f)0Y@}>^yo1p87%qm%&H~$2?=o6_5 z{w|ndEe;XxiEB8cwBUYk!QWTIqzxG-2|U|R6+ut#Ry>*LOM`L(1LdrDbVy#2V|GCO z6$g7a?lP8`;Ex|KX1hcw$i^xSmR{nNJP=vF^o_YP%uY)amIj0l>J=b88Zd1cJx=Y{ zdoCKAE}N#2*1BaUJ~4#BD%0S_3gLU!fZ)*IYu6TLNl0rcba1_nVVkzws7A^UjXPiumyvPZbhIaP{M$hq3Il}& z^>#AlH<|r2jDc1J%jw^HNvQw5mmDr+mH0=fg`e(_cN(c2@|5d;t_$A6-p@Q`Ddd`f vC4DfcEXNf@U}l#qQ{?z7!wAq_J0KY-~7$e#vb$^6Bh=90Q*k?15f_H2nNR5`cL~e*k%5o0;c?r za$8#3{qHvZ=VJXMrvFR(S8e3R!unsu|6ly){6DeQ(!t5$pBZK80J8rV5slnf#R6dw z|0}?>bapWP4}gII{&|oh{{X6krHAEz3M4En?7#5;%P0I#`q#z(dEoy!+(xb*V*kmm zPIkPu4yNY+n?!j*mLLaSXHRDrQ(I@=e>s*mmPSsVyhb(-7DoT26InXg{tx`a|GI|^ zgn$HtfC_fI8u%dnrt~#&umDG==%T|*g5ZX%qQ$ zymAM)+Rl<#ik!!h#qFOnE9F%7cC=>cywV{GlL(3Ix$?d8hKuGKc%W{L*Zz$7)9d%j z9IkdtNqJl|zU=>EJ;3ZHH-L9UVVHGqa#}4vB6*a{xIBx&22$A&0QL_t@47T~;!q+y zZ6`aVY!7%}YN_TtyRW5&R&Bne{y=lI9}l98VWa2N)taY&WsQHatED%;dHE+bsP z(%!_1T~~`eUbE78Azg#^lG8q{y%2mac?ta3A2~ySsVmBz z$_c56{7MVC(rU7(i8o;<$cJgXv`gundQ4&&pu;8^NV;be8Sh)-bXmD__;_H z|FrpAWsPxCuoFpp>Gf#&(A( zrIV11W8knb{q-nBI=>dlo%fg_$elS893c9Kw_=-yqn^KT@>yOi)ByB>wTsQ|Db*cX z%ic6FLgbGTiCs>yy)^{|C30LeT^wCo&&+sepDOT^ZX1h&qf%1y3jo1-lx|NqK)P82 zpFyytLiD74X$GJGDv7S$OkC?9_}UQ}-{7Yg5!}ZXQEwR%q@ugK{+xee$P5mNW$+^G zT=9S(u;BvfzCcS=RWqrQ*?&BKMLtTMC_lY!3OnuP7i?Po3ExbJFzcct$Z$?X+L#m} z<;M{6${c-rzmwGAjTlzXJPcWtb#L$5I$wpdXHsl>-`Re5;OE=0mJh}YdS1wuzQF7d z(ogpG|Crp5GMdvXwv6Cfu*$$Y?{_*Q8usYfgf6c9VaqkE_?I@=gb({>Y)hqsKKskV zlJM}9{13WiK!hm=$UGRU)<07SI9?GlC4o58^WsxMCvID5$pTv;mLeRHF#x4sj;&p@ zW$4qJ7^}k^rH>|v-ZW%@pj80^JwcM9p_^?|H6Cdtri+cvO(?tzW9% zt(qAl5+*VC;sErc)1X{_s`pDnjXs&D5c>p7D7oXW>zR3~573s6I?Pv0PpXU62Bmk} zhyGyt!u>swt=SqWd}J7gJ{HqAa!|Us1pp@@HpP9MU9=NC2jV$C7FB-s@5j)@IEiMg zFXw(cxdjq>#CiIG6+rmZctoW8$R2}v51|kk=dwlf-+J3j^%uS3mTRR=)(ValE2`|Z~+B7}- z`|fJ^>)(=_E3gbxKYX72my#`7(JSV@ma2dl#xX3&SmoUYm9O`GOD)DSi3o9DRE!xL ziO_^6CX$AM9fwgTENH<_67kyDpkaGf{M5cwnDqllJC)}_d*9zhJ&@tB!X(_|U{Q49 zvSVqszWfQtIzXf%GQ%hx8X6>^bI3HU)+RU?1^;_`*-N!Hqt)ZD!}nPqQOZYDg!@?5 zA+p_D#EZH(Fm zKRHC4w1jn=G~yM=)AMp27M~G!oIGnrsksDT`*ZiM)t-FFLx?u$dp_)RO_?TQB(j1H zdiF$SSB%RBu?tKgFry{vxO0jfy+Jj&mIFJH=kIL?_;%*48K?_q3xuZU9 zUx||E*U%u+HRQ4=H%Kne(riu96bG#l9G=Yt~Pc!^}+S5k28bZk8@dDp~11(XSSYveT0 z%+|=(WdzAQ7n5U-UWdj%D5KwhH4q?SCX-1iwMF038r>gQky6rnwY?C%#sC5Ual+92 z^%%K{h%ll+s`JYL-HS!WAs%{Z^qO7QIBe@{Vn|&ctF9L|V?aE_XS=bH^&ny7#%pSo z7yX)p5e(65@oESR2Zss|j_P)qV}D&@)0X-dGe~RH89`Sg*!)7*^JYHckCstLo+P=E zMvDz7cI1sr#Zc$?%6NV2w<-|2fy~$>h$re`PetePhT$&-qsJ6}PmBsrZ}j`)F=3AsW+T=dFoczxG(hNJvMfJ@eit~%;Iq;E z*lF#>hI*QN4eg*EZjnQFs}&<9YhLeg?i?|Ci?T3+mvUqGG3~({45@F5Cty(hyD_vH zE-l13#&yxfTD%ndhoQ4I7wevotzM_9;;mIHPrkc}o2CzW$pvp5pKG$2$LdG<^{c!e z$KrP)2p;i_$l?ogC9NZt&dC14Usj|eeN(Ilx}BnH+!9_2(-mA|Oco26-!t!Bx%gNt@6b06N(Zo43?d3L^Z#o<$j#;PdKE< zzjTHP)CK8(MlWQH16GDLPQKbXeyHb=A`yhOx5ageD8kP%m)ivOy=aOj!txNx;7LphnQ7zXX#M+9i@c z4-*IU@>j4uPKd>KF5B)QGCPG5fIrfIIzpTc@<`GL4b4@P;S2T+)l;eS<|-jyIfz}L zZzy{#H5gVj)D+T^!6H`1fkA&dd@(b@OP3BWz@lO$*emapc`I1(n;S?4OHsO`bOD;<;ZPk~jg$TB`OCtRTlJ z%fP`Jjc$nJ%I}9dV)QX-#ak_KG8e_2u*9=~(DUd${7Ly(;B2%`Zo1xvnGqF~r5p+i zoh$PK=?%U$8(in^66(fhTGr60v3UlQi!;X7^M>&mG3fdai@3+n2D@)`^Z)iRULkcbSz{p-ae9c2*g-tcPrx^iUuYI?r=05Q7 z8S2}8RTe{a8ShU%3z(*<{EQkMN=a6-;4?7c@tw+Jq*FQH6O2n3t3mcB@STZr;YSMP z0xxB&yDq*igR&~m)QY00*2F2L{$iNOoRKGJE~|UQ(cj0PpyZ%Msw=DtiNF+IwJkNK zS4oUCqir4lNK}Wrz=o_qA;D)g@!KjKELOHYl+<~Y_36%VL&^(2>j_p->70*0J*RS6 z|8EoJoa=a!W6#{X8+68RK`$P~w~Ls679iKH60RGUw3o3@Ni<@0=zSG&5VB9}tS(A_ zJ*MA0_zN@&YE!mWf~lr&_2;gm7#P&>ryKW&=*nwuwG~MFBvJ>i^y@P~E5_whd)!qI zMtC*i-kL$J5kvpFMiCRgX**#v^?e*%zetZ$c!q~U92Bcs6T%ekzMDe01i8=EN4SY# zODZIM-5WTzV&Yl?JRdpO2gq6TB!fIoYWrJqT*) zo4Pq22r`5w2If_giDL>5f5-RWujeI}+!w_R+CK9#O=4NxPKN1}6FPyF$ZO&i21F6r zvJIso`S>!V8sFj=wEcMa^8IVwh14ESbi^rLZ@JnXY=(7qrxCNi==nGqPRKeDguqy$6r%vYm4J{DLVto#!VU zgR+qeOh{GX-g*+SY8ao6g3L`nioqz$nLy?Gt~JJj66*B|W`SM;H#q!f_v*W}YPbd- zQR+k@GTFWExc!lnbz~*?7opYg$tTb#4 zF0-MTBjA@nRQAWKb*9eTYRD4FN6eag+(?qlOJ7GY)F?HNroBYw>-$@gy?14he_?Lg z-sGzSZtsf&R@Y542vT4SWmYKtcrnYXO&in3v7q9jlUAulY2C%CaCEd>ntAX;Sd5oD zaupkHa5%j}52#)-X6B+aD9EgbedS7qPFQ;sW2wYM{yG%-;JL6eAqAAQO@uC228Klx z2HS2Rjt7mbXKaj;{tZZ$9-P8$z<`e<){Aayx*5CbUb*?#LS0hE~z9%2vr}WgT=f)qtz;Z^L5a>)cDPqk0 zg4i^kF7xP=ME>k|+eaV097P+|(Uc8}LDfGr3^w*Ru}f*eW!BL`FNLm2YP2S%5*dmW z3A?-Bg+kDrk+tQW&16qC#QWjVTYwx=SPx79TPk_9<4fuQsMy8J*}HX-3(t_;i9aA$ zCX$dcspi&-$4#fXeqb5{5Z_p~<5Kd#m4dQ7%=IPUgj&--uDcc6oZ88D1WSpr1_=zU z8*vTB1&^2E4=obwD4X*7xU|T+YH#YQi9}&!++PhOVHxw(?-m&zOMG~x7us>BS!-#d zRwac!pFu|{>Pp-xppSU%yTagZWTHNcpn63puQXNeC1*H2iXS`{)?XMRL~!pI*}*FW zSc%oQy98#dgu6e(k=vBd6Q!|U1GNB<@Lj`~{WS%@x!q;&QtTakCE$MfU8uU6^I*9& zkPDR3d^c@&jPBA@5Nzl@Aw#MQfhOy4?_*)#_)Tc)ojlp1cHQk8Y@*6=!kYd_UA`ep zRV>Nof318il~f<7j7Xjq#8`-EhpnLElc+j16S$`fV*0$b6#ilwf!AQ^JzdVfz8s{^ zt&9FOrVCO|e6v+%E5-$1&3UHBp5lWTo-~Lvu|sqXb?1&5E;G4k#=9)zR@$r`cWMG$ zkCtTcFy%{9@L|^f#u^J<85tOVLKY^W+0nc4uEp1(5)?Q0uOcYydT7Q3V5+9=QRK-^ zo`z6afYYQMJ}H$f9KrPv{g_NKBK!Gp4c#9gTvf)Z)mg!aH;IkH4C_u)oL8lM7{%cn1Gx}=>VrejbK_#) zx@mna25_;mPq0pI?8Z*6daNLwyqLYJnqNIDrfw0P_Ol*P^7suT>YYMva6RM6VJA+r z|6WZC!Pq5Cn@M(2K&5%kf;#!)8EHtK?-#cfX%NAar130D*~0^ujG;pBUX5d`JcVkd zwe~%XCFe8foy46nEN$Hj2X``~tluvk6AkJ+T+Gbh0L@d((*|WRpL>JB4YwVLCGU=9 zlmB*Gau%Y#MunwtMOY;TW(~wWvOy`o3#aRHeqIo(x;jdvSmbWz2NI8YHbES{Q-nqo zHDcnX{iI%?CZPNsJR?`wuj><%q3jI}PBOt>CkrLtx++8&m8+XR^vQ}}^<4J%ws%fM z(>PYJy~Pa5R}nP=!H_fbiX-0}^^6bS+sJGO%Xn!T@yQ7~M2drQsFn&(jZ{`%Mr}&I z?~+l9hmrL|_qUfYL>T+5INIs1mU2)G)FbNA`z}o@tulYgn0soF(KH%km`n;MVWE$) zYgID(Qu{EzL`)nsckDIoH!&Ru1}0q;Qyg@cMo!^hbJr&OfM_WMwb{0#ZTf?1X8&^^ z!=$5omVb}4g@+g0qJfzebB@653+*b&-(70KMJQb(cvu@{1w*Le4cgm)D&kQJ4P0*7 zreR_%BBnxbgKhA`23YcjK8%M{*;QNYGDzoxSzj-1;~$bxF)p%96ql*SGtE3w*j8auYtwxCH z&4Q%9SzdYs0{tppN)&gANa%5TrADGlEuX7MF8#gYIUp*MajY7+s=~sz10t_qFM1-L z*h&`24$HeNRBK*hn}vfNNpkB=nMtN-Lg z+DJ@(FlFgi0-&i4;9r~ZQ2^Xt5v6W=WeY__11rv-b=Dy0lPrO63L6bq8Ds~4uT1d2Grezk3#x3)VaDzW<@Kc$Yy)&OQO^+{_yPs zIc6wH)JiF>D@QE*m5Nx#dkM_%u?#nBrgWRce+-j5Wz6Dh`X*aTsYk1s`0fLGID1qMy z-3VK=`eCA{3z4VqlFVy?oqRnKZTkj8aP5q?F&MGD*E-NK254%rJee9cbDH1vUbHv> zrrRRrL@+a2CgHp(e1jZ+y^&O2=!bO#ftuB(YRl~I@tIWUdaQrVps zfp=l0l<+(#@esI%z*z7GzU-nYk!ZV0o{9Hh0f->1A>ZX*t#XBZ89B6}AhPbbOpSea z3V>T@T*G6>y7tU2T@E=kW)8R@J#3ViBKYv+o_U1$JyQ1dsjbiX``!wP#L#@b%SN-7 zbKYpz=4@B3Nez_Oh_V}wPN>e_=q9vT?i_4Sp`ut5RS}(B> zMTOY9AJ&9Jc%^o>eiT0Xb%9(-1*Sp%V!g&ABfCVTX(4|N+G8*Dl$GXcw)YmMFv&tCLnj4PH?=r62k&1;cIq(j8g47D=(ZlPHpQVAlF zB0HYfzwbuPYNJ7~o@}mxAr&|3pe!)>k5qEmMJPA5Kqh;RLB}EtH&vvgZpLRJp@i4% zEn-|zc{57#Sa*3JsP#blMmpsf|9|fcCBjSC5~ZM}lkC??ha2Bifa6<8GfQ2|*Iws= zn}!4qt`d0gcbyzOhe_Cex36Wf447k=cAR((E~ZKD;wQaQ{eT+r6Mmu&1-63tw6B^< zq)#-evr{Y5{;AQgcXvX2rDJZNv?8y(F)R2bVE$^ltod$+|B}aF-Qf~1(xLrR$Mjb% zhqfhew4i5l8Z*}?zKz4p-p~iej-n%s>{uDrS8PBoCIe6e?D-&|-}ONlU;dCP{A3VC zrQ5LxvRkHXO3eVUiNNjPTEJ7Al<5<9R9P^fI3IT}58F+u=FrF)M2^a)p886Z`c0}B z)*^{fr_>xh(6UWHj*7v5AoP89?7|k#FQk=uC49l7yBNRHB-n1Y$ii z@cQg@V-AJ6*!PTzTZ6PfwE9bIExE>7~%c$Uj?nJ>f|# z=iJJ<#XP8SfL6zbGBr+&%y>LL_CEF-%Kf3W;bTRaq{T`V5A%MY>3AF2dv$Uq zXiHuNQbM7$tYTHevDZC6_1yTYB3k!-wFucY;ks~B>^CstO1aX9=E_DO6h`CvcmF^yy&o2G9aH!&UqbeqFyIO+TN?z|i!ny@;D|Wtq}9ls?d^Wd zeMj?cIV%REur!I38xwlo^Z4gT#}!(`1LDsijTYpvIkhx#@1RLmAOGCBF!pmrbS#uC z*0%x;u_X-l?b}6uiYOal-tv!`{OZlW0KKIM0X1Dy0D<>6D{mFOVufdgF`nSZOZc2o~M4j z!MaGZg@*9cr3d%&YFtDFkG^oet2BP~E2Y&_pq?n2(`!IURBAbGW8zew#R-&faVq(_ zz6pe7ZZv0<(Gh0&0wwuc z|3J%UoHRQ;;g-QXc?f1!h|AuVZnJDCMn@JoCWn$HyaX4(jMmha{7MEu4*WJ_cX^%{Q zdq{%y4Gmjx9VB4qE2#zj+;W%~%bD$X-3ZB*?>;bu@I?-}`TnYs`k+YNi{UrHDSb9R zA#T}mHTXD8yM^s;85g@e!&fUsQfe=&C3AFEXaiK-AjPBk4edjS9I_f~m5BI7`92Cx zBf|fM*yU=e>l7{94@@oPb)%5_x%YB5tp^=_3|MM!cxme6HNW<1I_^;YAOU5oFRvoY zvE9BTQJSNkEw|gxX)Keq=VPj~%Ee?`79Dha4qs&V)huNg5>138QIXx}4gx0p7*l=W ze!S_jYoT7aYI(S-aJB%UCezc{kcf=Ti0aoA?f4k!iscMcDo0YQ5o>>Pn8o~bjj*Kl zw*WY1oWRCAue@OOx|H&1m+d)Fm)LMK zIUK8ccr$j@gPQ(_4)(Ru-(#DPl`o_D6%r@&eCuywvrIg{!B2z*;pT&pbc*1{IdB$EAUx5)ZYU7}e4L?-!Daa+_3sI^lh`u#vPKv)&G5ANoXOvnpj#D~tC>ht zr8_W0mK4M6nxajIv~3(KX|(_DP?+%LWIMLK((GeKmW`WQ!p~Bztu;(=jJZr2@4*ZN zGJv0~D+~8GASS=&b~cKJfFG;3ttM0bGHTlVt+HI(rhUPvp{l4L+|n(qUzPH!dTrjV zG@>r^(R;o@^G^%L`jz1?OXZ6MKrVGS%Mh2I##y`2M?B#L_BTl$;|4$l z;`?_M6@ys{VG$}?F8{nO?3^^zFvwuO$tFNv1@KXE*g#KR{?6zlV!tuY6k|CZ0ollM zjnU@ogW>KtM?84Gu;6M|M!AGF;q%^qyT{&j(?iS@H((s}wXJcRWyW42{k4r&vx#)9 z)mA|d_Z82#RqX%uL_L_`)N!^2#>6Sk5XO}vo=~b@SsxB)&e|CI&$x6H9cNtd7Y~i;1t@e6IgBJ%F9(q=x^|Ms zi0UR0#-wxH$PWee`+XAGpZ3qG8e{8;X5}tWZk1*|>bIoj7F36~pk4mZ%16%ZnjJz# z>aNM>3u-MmleNEKcOoz+UC~5vfB(0gMXRJ$*wq*bIphE(5`T%=j(YVH~Y zi^zRU0_Dn1h^NAF($+*)0OtYR(58@=4ig}%5sWY!QYoxYRG5Sse-bh12mY~YTi2=* zPZh84=0R_PU%42x$BIv6lt7F|P9?{E66P9A*BCa!Tzoni4Zk zr#K*Q6TMc+^dKgg?~bjWdZT6CY$bmG^^8J2z}I@g|G2@d1?j}Ll}+! zn%r-Yz@Xc^S34yx-oxz$i&re+R)TNsDbFT=q*~zCF@U=jMuMF4cxjI$Ur+^EHVbBa zxF!@aBLRhw5DYX`sUyC(59PrZdl>v$ThI$vYM1_9pq?%D?d;0FqKrf0`YvZUm;Y|w zaYwRy?3UK4b;w0-9vy#C!D$}TZpr^=85q#60UA~v4S=^uKPS1&77hM)`C>-Yb5|*L zFvG^Tm*3!inM_Zf)9s2I-&SC(a@w5g^ku*o(}-WiI9tv|bSWorhv-i`<|~5b2G1yc z$LO+E#(Krhi5^SzrG>X%q0%WEQSIik9K#%{mX9j4u<#_6dE%d8?Q2I8VJ%Lp5=T63 zqojkn@AeM3ae!4!8lSCL5Z{s=kdeLXn}8}QUAG7PbYp%$RnBwreoEuRa*}%s@L8<*2IDzhaVgW>Qc5aJDX@<#|mZUx-FTjsl zObne@b9W635^#3{)$JzqQ~Ty1)H^uyK!wm=_zQz!S_ zfO3ubP?aqA=&jCUmOmp0E)2Lp{d|)){zY7F^XP6=P?BuZVM{#{bgiU+MTb@5g3MgC zl|YZ}qFp5_{YV<)7PHZVbTc$p!O4k(sXh3YGI)kKej#PD@!`1a9%o3qp)elaOY-rg z12BC&5ZDtKsIXAGl+fZX!ZXSL{^JDsL9_;s?!q7SIYz-4?AWmV;BkUWNT#hX@|G%B zgk@VW5JhrID$LQ-oYuGdc$fj z!@^deH%E*l5pRj?;+#H=nC2>uEXC{U?_D7_o>!i zT=1~Xwkn~#k6X&%_$Cg6Y1Fksq9^{;usxwa&@Ni z4y}K^*jzjE;5I5uSgyc42C6YBQvVmQFllgFE3UCL4g#`ecjvaR+#B|23T-U z_6|ynqP)m8y}6aN?jZW?A6qRT%RJGk@>G|g(60D zgg)E4Z}9tW{`huWjhDa<&u%jg(y!U5lpn3N$UZ=Okw&W+#Mc70;mghdRE>deW^<0i zCO)>|O1+sXjSg{^w@ZhKne()|!k(XMBJq3MO0Q6iaY&K~h#MJHj>G%1$jm>Ahxo+L zaGo&eJvlfRhO22AY@Y&0%JjhDAT-C<$kLXNejlMplTwQWSBN_;Kdy&JerZGou)*0f z?)A6aMX^y9m%JE`=>e|{J1x{aQJK+b^}5}s)E8~t#+%GKmFq7LBNQKY6n*2ASR)Gg z;Qsxy>Z|iI+g&Aw5)CkYOnp=RlU^1}#Q`@gx)>uN`^})Jy1mf(?Z}K?V>?7u3%z%V z<=+3>_(#=d65DIspj1K1&SeAVpTrmIIDKlh^~hK-86$N?MIB>q%``0o0y{gtmcZ_% z!i8~X=g>_`h;!Y5I_GT3$5bDi-Cp?fXcIJQswu0XqM5F>ye4z-(XKs%_97&JxxOWA zR0C0P={II`TRT&P>PxVl3Hmb&Qwd^&G)2HlA79*}US26ZUjx+*JcaM+88kt*;tyV8 z|ERAoRL!4i@0Yfqh54Rs&jd2!V6IhE_Dz1n&hb0^y}y0~mD3r@9m8Ni-@B);#~RUP zO6Dg&p!b0Gj;rM_nokMU6xUE#75$Gm<$5tnx-$ede;Yr1O(IU;tYe5j2_1Dmho!-q zK7~uGuIT#Nar}BO)RylNtkB z!}h8T+V3nxwLn<-WMhC_bnmz)-ii+pKbg_q>k^SZ;-unw^mED@%_2IF3<6&^3!`=Y zIBNB+Pgf5Qv*ul}M3VA7N1l0~gmrpVP{N@k8@B9pD}KgMpt9PCP;2pz`s0h_9wLAtp5o zh`8*gnMPjt+<<VV&i1Oeyd8lrCSJQkN2>dB}8eqKryM{oQl|^$@z$I;(%Se7aqV_ z&ayUaYrqH+FbINAm`#HlpAC1Oz_fX zgi+B-FIZX=ay2rWXdfp@HMf-U@*vF&V_mUNXwNAepIwWcFtckx2uAc2eZths%~hBc z9+qxIwr-Mq(QZdKM7qfh5!=VOic2w5{??!mVFqJ_YC=FO5|_dX2foq3hvh|tH0W`? zvl@cz_5)cz;I^K);qy5EeY2>E@JqCRXvU~^K0bnK7(}|`?D+3Z^>3HjlMfzd&L>7z z=0uX_(gV&TCx}-^orR0^g!es*aluM|@5puc!sM^7)#Xgh&o;AT=kcL->^>LAj3xjh zbsD$sf0ngOWZgW(Kyc9wa_uA0K^CS(cEYk%goyNj5RJdA1lr%D9D0cLgj z0mdquVCLx(N>Q=AEZ664pd^x=Z#N)T3-lXk!EwCH5wcb zI_Mt2UOF)iK1|Yyqm(lSne{SaBFX1l5(8nJ6jvFOpL3t%wCu29zhGv6!NW$Mf+g7* zp(B=6v2XYGp0#c_IN;@4(%lEO%r}z@mT6B2oTqu3H%*DU4tXzGp0=Ah-F0;2Bc=^- zRI98S3a!Gfh#l~lyq-a?Jr_lJzUpiIn@3<0+;U=;yP;Bwq>YtNEA`j?Ex*0%kwQKV z`+#L?shT20P_o4m>C;w!I6anX-W3X9RTuM^x$l)0vx9-lp*6VcPa&(5rcD}&e}thd zr0YCFHkLvp+{_T(YOc9V8XyF7t+c*r9K=KW3Hm&t(p0^%K^}?mV;=~ExQ!lHaIokM zCEe{F87yCRE7wSR8esqR{n8bQOh^xes->{1pniVY2sSe|U{~#b0dQ0YK&McfkYLl# z;%Y52qkX2=5n2DDwq7QfsWs8|QGB#%*A)twuYwQKYM2ykW}wG~W@S}6`t;v*NjWHE z+=yl1TeJOyY7z_cGXt(y)hyhA9qo&1nRpm3MK(W`uifl^$q8%ZgVq}U*3NWit2iS4 zFf69|%!VyFTGEPtS{hwi3=la)^V?ZUIAB=vaRFk1$_h%Kh|*Uv^Mc`jZ9nb3wU;N4 z*9mK1yJFQGZU6kO_}X0%R`dlJl+rL3%ZslKnVnL+L&ANC}mjY!*LL;xiCd2laY zqkEPC&_cebpe^=TM<~_7r5&)nN1OoLzr#F3v0on~QujH3sD`8e&(8+Mx2oNu49Xn{ zIi(uXe!y=H3JXh+mInyS9_u`*)~7=zo}2-AlMC=)LD7jYD%pjILz0|7cN8@o2?ehz z@qTspr~^~SMXX%gOgMh=&1dV5wMb`Hpln7m5QSWfs1G^1j(vxqp;Q>{&f_pzG#3Xr ztX33g03}0zXf}BWy>|2|JQRcgaX0gaU(11Ly|Ap?)AtSayM8R=@RJ4+#d4WEoVhk8C|l~`UPa5C3`GyS+0 zA@oaDaxZ7dYumyM*>xh6WqQ1WD@+LdNK3fqB4^{=BZ+|DbQ4XT@bML-{g|gF3>Y+C zaLEnkmyCorkRzZ`D!FS)f15U7zbZw?wUAH{JUcKr9=(oSI_Uu5*pBm&`K%6PX2+#; zv7k_YwXkz5>7HM^c1ljzx}0&!aySvQ*9KJ0o!Ie4%~OwIVe{|Yz6N4ZgPUpBZjJH8 z@f@qP_7VK7Ag;C!V^c)$0ch>>OBkJ)&%2^j-h3$9D}G3`>?*mM(e4Hk%vYW#^@-Kj zer8Y-Wu+(!17xrBbAkyRRm#=mG`b_ib8cFHO82Tk0I<#gCuzD9WH)e`)(DRw21GMu zGHbk%WA}3G$0L<{uv>=GK1h=hU1I+lbBDEzgYos9O%dF5l{*U;#!F^CaSUO#GaH+u zvJ>T>zSWsme!V+U9+@i$Q^5cnbLL>MJ`jl)4<$bZ+_rsBVAN)mqfZ{<#1S~X{sQ=a zLTsaJFy_(-pm^gP{0>ZviAU;NZ}q7xnEC0T_#J_N*i%^!m{mb(yQ5+|NAD@eUd|NHeCQy%sa`A>ZUbGwIE+gc~#^ zRw7NGo|^u|R)z>9pYjxp^SrJjd8pWbZ!lR@RUEW9%AEYG6ZY^5ohP2U$o3Pzw2q+z zzc9MCxB9j*S<%&(A;pme_6i)|4^o|Ey;vduyd}Ian$_xxr|cFUf=a)Cc zlq_0Q6|g4h;bc$3!S8qV@^}M7EU4Qbjsa5sg8 zR+f7bnq*y}U=2xl@k4^HuncT%9e>@HK>|oVgPdZhAZHf!0>UWpM9eMdJDLEN8T{9@m!V=MGpa RojaP$Q1iZW#@v%B3@n!9_uK#g delta 2604 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 OvMQL>bceu`EDS89*ZHde diff --git a/public/docs/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-14.avif b/public/docs/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-14.avif index 73e9ef64255b7b87406d3b96f987f7cd7a6f792b..d126a4d7f927a56ff5fdd84d7e1200cec5270cf0 100644 GIT binary patch delta 2156 zcmV-y2$T2J8j~9s0000SW^{RQVRmU|00000ZE0pPVRmU|kr-eJ(*Obh0000DXR(0| z0Tv7gZDe6|5&#Mc7-B#7_6P`QG$1mqFSCS4h2@k!Bdg0g_IFQ{IsF6h zOMkdLm-yZgeer#f=(L>>tj&d~-`zs*jcdTbieO8g?bch&ZE4POfB-sc6=_Eat0ots zSZkPT_6BPx$P+^jW#Hilhf$_}{OlXAA5G&Qzb<{I$(wsEV^03GeJgrVF773XO6)Ln zxKKXmJRKp?;saALMGdm<)>P1aBxhm^zwmIhI~HZsOuu10V6c1!mpUReKx z8$q^pe_WOvQ(n|LNyh$1c`+twW zNIfX?PQrrj$^&KXb|&Z=D(#)8@+z&ol6v45tZHtR7|Z((sc(Z ze85hTT^Z`QXM0~&c(Im zqBJg#VzdK@SOq52T~jdw3l?SAd{aGe+~^TV28LyNB!9-)#KTuO ze2b@D!-v-fIx+^SK|CpCdSqAO{P+6uu^w+Dr*%<-E39R~!XuQhuP%PWzt*zZD*dmTQ#DCpv)dRY(exL!b6 zx~O9q9CTtc;S?)`Gvt(vsoY|Q$nfm7EP!!ogcn^iZEFr3HOV8++JBcF<%N3w=&;5) zbWEeV3LntUUkxx6T)hK45H!HZ1R;5EC&tWTMHA9>NKJnii@qzJm!=xxx4oP=Fb~9UwXkfQw=Qe9D zhqieNUp3@F54ZM~%l&Ql$!KZ@Y{5FN-n{nGY67{T1Q2e(KU^I*#r!RaOT2Y08_}wU zcFms=J<( z%x}!|m->Z}3Aj^pagbgM4ZLU+jl*p72OEYaNO<6Jt6;T%^{O=06=MHqirI5;nOq!j zydgxq^?%9Vo6^}LBeY%_2f&<93;;75OXY+G_y-vkK8n{@sckY90{$7EKJXfM)en!e z?Y?c^D&@49)lsu+X0b8&|Aow8z%wRPFb0$HAzHF_;&B|@u{MQudR}bJ%i8}N%g3m` z5F$M_m9~_@*x-$6UwDCt6$uc(r<#S-A6On(&jIWqtve=esQSGxN8s`XuhL5)05 zM7YqeoCRUP{r+*LUx~jNzJ|U_ zod#QQ3aspZ(ftV}6dl+x i%GXS9Xr|H4t5Vur9%v^>N5lo_cVAV5FamFrC=D#gStir~ delta 2092 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 WEqj-y+q+?d9(r4#^i@%lfe$Q#(WjCC delta 3433 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 diff --git a/public/docs/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-4.avif b/public/docs/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-4.avif index 0c4991e782e850fdc6959853b00c78aa4c998fc8..6085b852f823573253fc6902d24495020317fb29 100644 GIT binary patch delta 3280 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 V<>oYDLn;WMks-FDVZf7n3@jfrLXZFe diff --git a/public/docs/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-8.avif b/public/docs/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-8.avif index ce2d163fbb59651b96b764c6672812bb8218a94d..15c5864f9a30e7d84e2b1eb61ae5b3b5f3f9071e 100644 GIT binary patch delta 2825 zcmV+k3-%NM=A4ZAPI{o0zHxHGM(6JguVEE=ca$JQ;Q=r2TFp5ovpIO ze;c>QV@A7wqO18vJ9CQV!)rG&X4I`fiHiuj5EOoUUVK71p^A#Zs1(qiGj9;rC4lmM`Vs>< zjGj!OdvE``KwTra=#tILC{IhCf+N_!f5RRGxfa`Jar)QBN|_KbbYXax4|$IiF7P^$ zM+Ub3e-}^8OzAs-GP@RB7^$#)e@+l!*b^F?L!rbSLbIz7ZyIAJ;-d7@uuwi{Cyf1@ zj!Dwyrs=DjQUy9bJS7J&P@8%Zlv;!RCD?1%IllcSYJaQWWBLg+*|6?^3eS-ye}?v( zPa%A|$VbKFxu*KBZQESVFTyBkrm)j`+)D`gSuw|!w{ToKYn{)}VNGfonT_<0B_>7> zJ7oZCsC7H&c(5@W{JUP-MULD9)DcQx){FL63&bWJJ3NrPbpq{iEPtaJ&=vEJ*qRpI z|7l~cAFx7B=B`en_d))(G=&*&f58=#T8X@1TS2bCmhjivUF>_AwIYWaVaNS7JPAzW z4xZBtn=oYLZ?$#PVJyTayvE%irVZ@6+D$2xO|dv8oHnc>7*nv@xuJ z4V=wNa8n+TsrR=U)f6cd!flb;y8pJ4WNm-snm)N(C50^Vl3U^M?3S~ye^EOd-y%0c zE#VYbBJpX|Z)W_oPs#=diGvXM@yHAA(&1Y;1)-_xWYmx6MD9CfnQq&KVl+X3-LsvF zNmj5388Vx(iVqrD7bw0pjS?Om%k&jkAUmE|#RT5Wo{b6<{|@q!wV(+Jk?q|g?pQmj zxGiX%0|3zoG={fZmu(3Ef02eQa3ermDol<>*meHuctVY;k$u$mIGc~L7p>uzezBO$ zc8Z@%QJaOmvDA%4bRD|`UNjcQ-^E1Na8*Tu?tpPJTKGaO=f?^h1hUi}2|K?4zKw0( zT73nPIOz8Z(jhE=4*t>l;_A8u0geS%7w<-4teZ|#Lnj7yYzPF7e`;&P$73G2I2O=d z61EaBYSrRF*^*7iRSFF|U{j16Jey6;G6))Z$_kGby#?h^hC%|2#!H=?e`sdT%m9?< z^k>@=8_M^2-_-s34&k&5kE(RINlEMI?{+60F5Gqr9xrQ!Hz{`dqp1ZoSXth)yiJJ9 z$=;hqfQ_k^Qc6N-e;ZRaJBuL#-)fF_kOl9e@rN!8`>C}Uy;z&1cY8ZG-stJFi0|BI zD`N|q>AsTzWTkvc_@?E$($x>8^3}iJVfAn5$sX$2NQk}w%r)iIH-S~d!-!~pGSQ*` z<7Zqa39s4~y`;>Xf@XiE67Z%?Q7EaOyySwORwEzy9&+O$e^aj|4GMt)aVS_-2rVxo zB?;8mm26qVNK}+-pwvWEXG>TVsa53OqCjRxj4W_&hYXCGZ`p3Rp_mZK30u(sx=kaB z+L*v2Cni0AK2jtMpaQEKlF*QV3)tjrXj*1hX=%s(|8MtnI5n1ch#sKLrEGCeta-uQ zFUfR^(;}qMe~{jVL}Z%G-5F%ju+wPPV`iVJ-dasEjD=ONDQcFarsvm7i=*kZXl0j2cXiiPOVbfZivz_bjZPo5xrPkP(>URr73qGC zK6D}Tg9b^%jPhCUJ-uV;<&uSQBiBzr`epcg=ZJ`rS_#=)g2*xbaZZ8ccXN^qh4HE}>ODKLtQ;7Ya2%%^i-|hh1 zed`i-p?t`7SZM>;58okEnK=>*+RRL`Q^7KmGQB36K<^ytm_y(?6-NRev)LQVwrc0U z|F5bVt^XP87KKGi5L&-de2HM}#e$Z|pXG%Ov{aXX3TV$hSRsy{5hiv2k9SH3$)N5@ ze}M)X!P|OVx^(0QpYO_~hNDhA{sBUHxoo~;^y+Grt^W~Bk!K$i7?-SuBv{V3FlnU1 zp%_-Or8Q$dZrZ294z@2eNl5as%jv?+u(?KC1|ro3sn%WkL}JhQ#9E`&)*z}Ft5;PK z$nC^}BBwX`ztouJ0wvzq(}{g}Cv=f;f63)R&*7@OzIlM6e6PR+F?~>;O;*}NW?&v5 z%26YrcRU7IMFoT!JYyi1==#_a)ULH^;6VkkNwG-T5RoVNT5|afLAF9ofA6?( z&Xs%u+cH(Kt0k3q{`GD+STaayYWyfDbdCrzId>gWOG8JCmZQO*0JGAuSM!f276cB& z1yzyVc&T^(AR|(8ZTDsKO*ET8mlSD7Wp4hdwi)=^>WLpZgT(GQRww20GZ2snMT9`r znrhNJcwQe-I1NjRwn%OCSBMu8e*#4TGnr9+(>M=K$S`ddpRlL-UF9ZL5noZE(7W0M zX93EDkOF6Q4jnm$kXnn&)hH}T3AzTzCE?*d6D)*1qqUXemYtPpP!tAw@t&qA2_9br zp4-P=KAGj(@Y}$VwsK!w#}K{9f7H(VrM$2F z={zPt@`<>$#g9J1ie^HKm^x&Wkk4eE+VT5^j19l1F}{1`3-~Xk9?{LvqQ@~Yldl9H zLy13dd_a~_-J^;Vfx)a+<6ix}B4RLd$?^n5ebnRtaqlvp=yDl@3BNob_62gS^bWUz zJj?d!2~y+F-cc_7rN1wUe+ck=YwH(XI&x&Y&(VnPIHI5u@qeRcsJWn^`2N5pAb`t= zxw*v%w~V?n6h@>bEw$IB_zH>53H*o(V(CcMCcw5_#-dd78&98f8lhn&&H(;rN+K&2 z8-#=ILNM0K=(hiZXIncGYpMYOEx%CL3n@D{I=Cdwbnq(c4V&-}2 zlcV7l6RDv}&}ZV8J7Tk`t^)s6z<|DsfEM|JYr> bdtE}L({X+8ri#7vDbHhK`fkublj;pDjpo9F`my0000SW^{RQVRmU|00000VRmU|ZE0pPkr-eJRsaG30000D>al?i z0TqgEWMOm?0165iVn6rx2nc92ATq_XqyfkQe_#ZzPw0uh6S&D&Vs{{U9F^j>d^G8A z`u80Hu`#!vVd)^*?+a}VjYx2p3hYdf&?-2h?5B%H#ooZ~t+YF9^Wp00J|mQk)2>H0alu|mEEbF+gw7e9a|%O}5zZ}0f7 zLA_f$1z#B@RlH5^yzezPNA`XjUYqV38^@J`HJxOdVX+F+lNTLxNMq6Y5arX+s+cn6 zoqXxs z5lB~}wfWsO)n-p1Hwbq$`4aGO0rLEwH81zQ_8vZsk65FM6R_?`DH2xq`KCaC{v|)5 z?NpY|hfP2U3N;zsz#&)&QGUSwY-Q~KOXoI7%ScjRm#ywyge_kc(-8|XmL zyo8${B=`nwDPLZ{ESHw=2k^3%;=F(6r)9F)^QaDijNf_74biOoc z$Ml-c7SW=H+>aaRlN|6%CiHLcaT<5Yq*w%>-qaET@a(dJh{z*>sVfkXe@V6NykiaA zo1z94Y(>7Dha@KD81?{J+vNJpfq_AlIj7d0%ZCPfCNlf%6=ne&?J7$ivVn?6^7UDO70Q@W)V)P{YqI50zd2z{4QHUbDgs#nC<@cM zEJ}>5p8OzW&R+=5)}^R1e?&uxDa(j*#hriLhKZg9=kk*I>-!snQZ1J;7WA{& zB&ktwV31BMWM-AL>{(DRAUl#ez5Pk%v3yuMyPV39nG%ZX_%$!@{Au1ZZ5=Z zgBJ}+vsjWdM(D8KSdAk81sjH??b!U_k|T5UKGt=Gv@*#JS0fqsf2C^P^*iG7Pw`kv zg#w0@eny!r^T8B@2??S%Cdcc;x6ZwG#YxYHF?H?(9lBEp z_eU%hoj0+7p;(>k!1^u>-6_|+3}zO%O1r_fVk&8Z2X;Ie^W)Q%Vac%rCA8C?;w>4za2qkbKb`(g&{6@Pj!XAe)W%#A&j)x zsdyjK^VV-SP=D5Sk*Io?b)c5xk2c&sfO2x;+)QuXnhuGvk>={%q6-O^)!Re4_cV-u zOHCuvj5(NcQ48>X^w$OmplIt{v zePpJ;igU8>-UzISDIy=b>)OA9OF}Fvh}@yQ(H%Pz@Sn_K)HOski)8<~tXw`2o1b^( zw0jjSkYLS(e&K{9%hIZXNY>^x%fnvUlAdQdqd{fQY+Np6#P)y)akmsG69hQx99C}_ zJm|`W`N8qge?b)w@0Mwq>r}RzoXRlq?sF?+4cVs!sNt^aURa%%qMS)+BUXAS(YPPR za!%Hu&`ls1ulU5X31`p%C6O&E#1w{&D&U9*W=E!=P{|;+OWbIkS!mdNt9KMbx)!m7 zq#*azTl>7JN?M=+2<|2z0bI>y{U^fMk&KvO?hhs+e|xDjz@+X>Z*RJt&v(h&P;3Kw zqi4eRBB!2U0Cu&uVb+ZWM3eQ$vS#dUa1`{S59QnFNa@ z=)3M@CMHjhtc>6uEA{ig5VenK*>3qHT?c@}w4D#9`t`Ny(cr9l-TOVp2Tpf7qCLEa zPJ_HS;Fz%8M;nP=;#!T}>Xjh@GDE80Z2;ble;?k!e)$TV$;cHY)G~z^%;!#yQsP#3 z*}4S@p**90Sf3tL%)+2%c|yWGYzIeEf~}qzZcG6n``8Q+rouUZX$`+4(-;%Enx2Lm zn%~$H=50wTDq$m>h)sTkU1hM77>Gj=68F%`v_IGXepSm$3m59uEa*ELS&_^AOMCz7 zf8d;5_MkPYkmrNPoBbA^t2Z2%M_m1VZmeAmDE3ypltw_covYW$nrj~4UO11B5amI< z8dH;$rLHE*MTaDOPYK&-!&qg$r(Eba#`us+sc#Fd(ZnNBMI`Cpgvdiz{7i{hd+Hx_ zisLvGbt#(Fw~+Av=~}(xL+q8DR{Xr<)#9Gi*w)fP58}i)2LmH+lAMA#T_o-Yl=0# z>2>Yc%eG2U0Ouag?Qw~9@a4F9pa0pYNGpbNTwFrjF|Y=*Lk3p;Bwsk{l3E5ve+AUu z7m2AB^UD{n6{Ca$zo>~SOi5xTvz4J9Jco;H2d+6CdgV`4E2|`FdsL4hV6M1I$fJS! z3gV1oFNN0Bhx`!Wa8qMxVMf74goJ*_a2Vh?2C!D2gf$V zLw*j3I~!sFWq$IDv}J;~j=Fs_%eDAB*Ey#ty6D!B+?BMC5)kaY|43y$Md36 ziw;%;6_lY-SMY?wOBTFjZt<+~Z;uo2hmCtUVWgaFo91+u;%%6quxXf7e-(OJ4yTYF zQuOM6ybSVJWeW5&&|_rtr3E$+RHjp!yK8v;`3aG|c#<@PS}XkyDse(;1z(@MXaRUh zpX8p60|d_|`G}t#ns1qntB{p0JpJVo@7i1<<)}ycw)M6;)!GN0p7ai*&;^Hi4!D~g z5~UJpu(uax7FIw%2kO>^e^$KGbeL!44IQ<`+f1U^-e$@xY$9W*+(>y|mooA+@$fov zd(`Sld8A|+7>fEeQN)xtfP-zq`FI$jLiG`&ROj@iREac4@9K-dDu9d>Z^WVb|- z><_vc+|Mr-hTb_7mX3`_Gs(MJ)hRACxd=pPS0U;q#ctI3;c