From f1ae9bed894997c4f5a4ad13118eaf2ad55f7fa3 Mon Sep 17 00:00:00 2001 From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> Date: Wed, 30 Oct 2024 14:05:32 -0400 Subject: [PATCH] Regenerate addon API docs with reorganization (#2209) All five addons now use the structure we expect of having a flat list of module pages, along with an index page. Thanks to this PR, we can now run `checkOrphanPages.ts` on the addon projects. --- docs/api/qiskit-addon-cutting/_toc.json | 171 +---- docs/api/qiskit-addon-cutting/cut-gates.mdx | 34 - docs/api/qiskit-addon-cutting/cut-wires.mdx | 32 - .../device-constraints.mdx | 31 - .../expand-observables.mdx | 43 -- docs/api/qiskit-addon-cutting/find-cuts.mdx | 40 - .../generate-cutting-experiments.mdx | 47 -- docs/api/qiskit-addon-cutting/index.mdx | 163 +--- .../instructions-cut-wire.mdx | 31 - ...instructions-move.mdx => instructions.mdx} | 45 +- .../optimization-parameters.mdx | 36 - .../partition-circuit-qubits.mdx | 37 - .../partition-problem.mdx | 46 -- .../partitioned-cutting-problem.mdx | 33 - .../qiskit-addon-cutting.mdx | 284 +++++++ .../qpd-base-qpd-gate.mdx | 41 - .../qpd-decompose-qpd-instructions.mdx | 40 - .../qpd-generate-qpd-weights.mdx | 33 - .../qiskit-addon-cutting/qpd-qpd-basis.mdx | 49 -- .../qpd-qpdbasis-from-instruction.mdx | 34 - .../qpd-single-qubit-qpd-gate.mdx | 42 -- .../qpd-two-qubit-qpd-gate.mdx | 36 - .../qiskit-addon-cutting/qpd-weight-type.mdx | 25 - docs/api/qiskit-addon-cutting/qpd.mdx | 176 +++++ .../reconstruct-expectation-values.mdx | 43 -- .../qiskit-addon-cutting/release-notes.mdx | 42 +- .../utils-bitwise-bit-count.mdx | 16 - .../qiskit-addon-cutting/utils-bitwise.mdx | 24 + .../utils-iteration-unique-by-eq.mdx | 32 - .../utils-iteration-unique-by-id.mdx | 28 - .../qiskit-addon-cutting/utils-iteration.mdx | 58 ++ ...le-grouping-commuting-observable-group.mdx | 35 - ...ervable-grouping-observable-collection.mdx | 48 -- ...ng-observables-restricted-to-subsystem.mdx | 38 - .../utils-observable-grouping.mdx | 66 ++ .../utils-simulation-exact-sampler.mdx | 56 -- ...mulation-simulate-statevector-outcomes.mdx | 24 - .../qiskit-addon-cutting/utils-simulation.mdx | 56 ++ .../utils-transforms-separated-circuits.mdx | 34 - ...arate-circuit.mdx => utils-transforms.mdx} | 36 +- ...s-transpiler-passes-consolidate-resets.mdx | 37 - ...s-transpiler-passes-remove-final-reset.mdx | 37 - .../utils-transpiler-passes.mdx | 30 + docs/api/qiskit-addon-mpf/_toc.json | 4 + docs/api/qiskit-addon-mpf/index.mdx | 5 + .../api/qiskit-addon-mpf/qiskit-addon-mpf.mdx | 16 - docs/api/qiskit-addon-mpf/static-lse.mdx | 76 -- .../static-setup-approximate-model.mdx | 70 -- .../static-setup-exact-model.mdx | 69 -- .../api/qiskit-addon-mpf/static-setup-lse.mdx | 60 -- docs/api/qiskit-addon-mpf/static.mdx | 253 ++++++- docs/api/qiskit-addon-obp/_toc.json | 37 + docs/api/qiskit-addon-obp/backpropagate.mdx | 49 -- docs/api/qiskit-addon-obp/index.mdx | 10 + .../api/qiskit-addon-obp/qiskit-addon-obp.mdx | 60 +- docs/api/qiskit-addon-obp/release-notes.mdx | 22 +- .../utils-metadata-obp-metadata.mdx | 14 +- .../utils-metadata-slice-metadata.mdx | 4 +- docs/api/qiskit-addon-obp/utils-metadata.mdx | 15 +- .../utils-operations-apply-op-to.mdx | 48 -- .../utils-operations-reduce-op.mdx | 47 -- .../utils-operations-to-global-op.mdx | 34 - .../api/qiskit-addon-obp/utils-operations.mdx | 144 +++- .../utils-simplify-operator-budget.mdx | 53 -- .../utils-simplify-simplify-metadata.mdx | 42 -- .../utils-simplify-simplify.mdx | 30 - docs/api/qiskit-addon-obp/utils-simplify.mdx | 110 ++- .../utils-truncating-setup-budget.mdx | 50 -- ...tils-truncating-truncate-binary-search.mdx | 36 - ...ils-truncating-truncation-error-budget.mdx | 52 -- .../api/qiskit-addon-obp/utils-truncating.mdx | 123 ++- ...s-visualization-plot-accumulated-error.mdx | 36 - ...ualization-plot-left-over-error-budget.mdx | 36 - .../utils-visualization-plot-num-paulis.mdx | 40 - ...tils-visualization-plot-num-qwc-groups.mdx | 40 - ...isualization-plot-num-truncated-paulis.mdx | 44 -- .../utils-visualization-plot-slice-errors.mdx | 46 -- .../utils-visualization-plot-sum-paulis.mdx | 48 -- .../qiskit-addon-obp/utils-visualization.mdx | 243 +++++- docs/api/qiskit-addon-obp/utils.mdx | 15 - docs/api/qiskit-addon-sqd/_toc.json | 20 + ...recovery-post-select-by-hamming-weight.mdx | 30 - ...ration-recovery-recover-configurations.mdx | 49 -- .../configuration-recovery.mdx | 77 +- .../counts-counts-to-arrays.mdx | 29 - ...unts-generate-counts-bipartite-hamming.mdx | 38 - .../counts-generate-counts-uniform.mdx | 34 - .../counts-normalize-counts-dict.mdx | 20 - docs/api/qiskit-addon-sqd/counts.mdx | 101 ++- .../fermion-bitstring-matrix-to-ci-strs.mdx | 31 - ...n-bitstring-matrix-to-sorted-addresses.mdx | 35 - ...fermion-enlarge-batch-from-transitions.mdx | 29 - .../fermion-flip-orbital-occupancies.mdx | 30 - .../fermion-optimize-orbitals.mdx | 62 -- .../fermion-rotate-integrals.mdx | 43 -- .../fermion-solve-fermion.mdx | 47 -- docs/api/qiskit-addon-sqd/fermion.mdx | 230 +++++- docs/api/qiskit-addon-sqd/index.mdx | 9 + .../api/qiskit-addon-sqd/qiskit-addon-sqd.mdx | 20 - .../qubit-matrix-elements-from-pauli.mdx | 47 -- .../qubit-project-operator-to-subspace.mdx | 44 -- .../qiskit-addon-sqd/qubit-solve-qubit.mdx | 45 -- .../qubit-sort-and-remove-duplicates.mdx | 30 - docs/api/qiskit-addon-sqd/qubit.mdx | 147 +++- docs/api/qiskit-addon-sqd/release-notes.mdx | 16 +- .../subsampling-postselect-and-subsample.mdx | 44 -- .../subsampling-subsample.mdx | 39 - docs/api/qiskit-addon-sqd/subsampling.mdx | 81 +- docs/api/qiskit-addon-utils/_toc.json | 33 + .../coloring-auto-color-edges.mdx | 28 - .../coloring-is-valid-edge-coloring.mdx | 30 - docs/api/qiskit-addon-utils/coloring.mdx | 56 +- docs/api/qiskit-addon-utils/index.mdx | 10 + ...rators-generate-time-evolution-circuit.mdx | 60 -- ...em-generators-generate-xyz-hamiltonian.mdx | 75 -- ...roblem-generators-pauli-order-strategy.mdx | 38 - .../qiskit-addon-utils/problem-generators.mdx | 162 +++- .../qiskit-addon-utils/qiskit-addon-utils.mdx | 17 - docs/api/qiskit-addon-utils/release-notes.mdx | 2 +- .../slicing-combine-slices.mdx | 33 - .../slicing-slice-by-barriers.mdx | 30 - .../slicing-slice-by-coloring.mdx | 84 --- .../slicing-slice-by-depth.mdx | 31 - .../slicing-slice-by-gate-types.mdx | 32 - .../slicing-transpiler-passes.mdx | 15 +- .../qiskit-addon-utils/slicing-transpiler.mdx | 13 - docs/api/qiskit-addon-utils/slicing.mdx | 183 ++++- public/api/qiskit-addon-cutting/objects.inv | Bin 3889 -> 2976 bytes public/api/qiskit-addon-mpf/objects.inv | Bin 1709 -> 1570 bytes public/api/qiskit-addon-obp/objects.inv | Bin 3217 -> 2722 bytes public/api/qiskit-addon-sqd/objects.inv | Bin 3671 -> 3000 bytes public/api/qiskit-addon-utils/objects.inv | Bin 2367 -> 1990 bytes .../qiskit_addon_cutting-instructions-1.svg | 714 ++++++++++++++++++ ...it_addon_obp-utils-visualization-10_00.png | Bin 0 -> 22833 bytes ...it_addon_obp-utils-visualization-10_01.png | Bin 0 -> 29161 bytes ...it_addon_obp-utils-visualization-10_02.png | Bin 0 -> 15360 bytes ...it_addon_obp-utils-visualization-10_03.png | Bin 0 -> 21541 bytes ...it_addon_obp-utils-visualization-10_04.png | Bin 0 -> 13809 bytes ...it_addon_obp-utils-visualization-12_00.png | Bin 0 -> 22833 bytes ...it_addon_obp-utils-visualization-12_01.png | Bin 0 -> 29161 bytes ...it_addon_obp-utils-visualization-12_02.png | Bin 0 -> 15360 bytes ...it_addon_obp-utils-visualization-12_03.png | Bin 0 -> 21541 bytes ...it_addon_obp-utils-visualization-12_04.png | Bin 0 -> 13809 bytes ...it_addon_obp-utils-visualization-12_05.png | Bin 0 -> 16643 bytes ...it_addon_obp-utils-visualization-14_00.png | Bin 0 -> 22833 bytes ...it_addon_obp-utils-visualization-14_01.png | Bin 0 -> 29161 bytes ...it_addon_obp-utils-visualization-14_02.png | Bin 0 -> 15360 bytes ...it_addon_obp-utils-visualization-14_03.png | Bin 0 -> 21541 bytes ...it_addon_obp-utils-visualization-14_04.png | Bin 0 -> 13809 bytes ...it_addon_obp-utils-visualization-14_05.png | Bin 0 -> 16643 bytes ...it_addon_obp-utils-visualization-14_06.png | Bin 0 -> 18098 bytes ...qiskit_addon_obp-utils-visualization-2.png | Bin 0 -> 22833 bytes ...kit_addon_obp-utils-visualization-4_00.png | Bin 0 -> 22833 bytes ...kit_addon_obp-utils-visualization-4_01.png | Bin 0 -> 29161 bytes ...kit_addon_obp-utils-visualization-6_00.png | Bin 0 -> 22833 bytes ...kit_addon_obp-utils-visualization-6_01.png | Bin 0 -> 29161 bytes ...kit_addon_obp-utils-visualization-6_02.png | Bin 0 -> 15360 bytes ...kit_addon_obp-utils-visualization-8_00.png | Bin 0 -> 22833 bytes ...kit_addon_obp-utils-visualization-8_01.png | Bin 0 -> 29161 bytes ...kit_addon_obp-utils-visualization-8_02.png | Bin 0 -> 15360 bytes ...kit_addon_obp-utils-visualization-8_03.png | Bin 0 -> 21541 bytes ...iskit_addon_utils-problem_generators-1.png | Bin 0 -> 27044 bytes scripts/js/commands/checkOrphanPages.ts | 5 +- scripts/js/lib/links/ignores.ts | 9 +- 164 files changed, 3567 insertions(+), 3890 deletions(-) delete mode 100644 docs/api/qiskit-addon-cutting/cut-gates.mdx delete mode 100644 docs/api/qiskit-addon-cutting/cut-wires.mdx delete mode 100644 docs/api/qiskit-addon-cutting/device-constraints.mdx delete mode 100644 docs/api/qiskit-addon-cutting/expand-observables.mdx delete mode 100644 docs/api/qiskit-addon-cutting/find-cuts.mdx delete mode 100644 docs/api/qiskit-addon-cutting/generate-cutting-experiments.mdx delete mode 100644 docs/api/qiskit-addon-cutting/instructions-cut-wire.mdx rename docs/api/qiskit-addon-cutting/{instructions-move.mdx => instructions.mdx} (66%) delete mode 100644 docs/api/qiskit-addon-cutting/optimization-parameters.mdx delete mode 100644 docs/api/qiskit-addon-cutting/partition-circuit-qubits.mdx delete mode 100644 docs/api/qiskit-addon-cutting/partition-problem.mdx delete mode 100644 docs/api/qiskit-addon-cutting/partitioned-cutting-problem.mdx create mode 100644 docs/api/qiskit-addon-cutting/qiskit-addon-cutting.mdx delete mode 100644 docs/api/qiskit-addon-cutting/qpd-base-qpd-gate.mdx delete mode 100644 docs/api/qiskit-addon-cutting/qpd-decompose-qpd-instructions.mdx delete mode 100644 docs/api/qiskit-addon-cutting/qpd-generate-qpd-weights.mdx delete mode 100644 docs/api/qiskit-addon-cutting/qpd-qpd-basis.mdx delete mode 100644 docs/api/qiskit-addon-cutting/qpd-qpdbasis-from-instruction.mdx delete mode 100644 docs/api/qiskit-addon-cutting/qpd-single-qubit-qpd-gate.mdx delete mode 100644 docs/api/qiskit-addon-cutting/qpd-two-qubit-qpd-gate.mdx delete mode 100644 docs/api/qiskit-addon-cutting/qpd-weight-type.mdx create mode 100644 docs/api/qiskit-addon-cutting/qpd.mdx delete mode 100644 docs/api/qiskit-addon-cutting/reconstruct-expectation-values.mdx delete mode 100644 docs/api/qiskit-addon-cutting/utils-bitwise-bit-count.mdx create mode 100644 docs/api/qiskit-addon-cutting/utils-bitwise.mdx delete mode 100644 docs/api/qiskit-addon-cutting/utils-iteration-unique-by-eq.mdx delete mode 100644 docs/api/qiskit-addon-cutting/utils-iteration-unique-by-id.mdx create mode 100644 docs/api/qiskit-addon-cutting/utils-iteration.mdx delete mode 100644 docs/api/qiskit-addon-cutting/utils-observable-grouping-commuting-observable-group.mdx delete mode 100644 docs/api/qiskit-addon-cutting/utils-observable-grouping-observable-collection.mdx delete mode 100644 docs/api/qiskit-addon-cutting/utils-observable-grouping-observables-restricted-to-subsystem.mdx create mode 100644 docs/api/qiskit-addon-cutting/utils-observable-grouping.mdx delete mode 100644 docs/api/qiskit-addon-cutting/utils-simulation-exact-sampler.mdx delete mode 100644 docs/api/qiskit-addon-cutting/utils-simulation-simulate-statevector-outcomes.mdx create mode 100644 docs/api/qiskit-addon-cutting/utils-simulation.mdx delete mode 100644 docs/api/qiskit-addon-cutting/utils-transforms-separated-circuits.mdx rename docs/api/qiskit-addon-cutting/{utils-transforms-separate-circuit.mdx => utils-transforms.mdx} (53%) delete mode 100644 docs/api/qiskit-addon-cutting/utils-transpiler-passes-consolidate-resets.mdx delete mode 100644 docs/api/qiskit-addon-cutting/utils-transpiler-passes-remove-final-reset.mdx create mode 100644 docs/api/qiskit-addon-cutting/utils-transpiler-passes.mdx create mode 100644 docs/api/qiskit-addon-mpf/index.mdx delete mode 100644 docs/api/qiskit-addon-mpf/qiskit-addon-mpf.mdx delete mode 100644 docs/api/qiskit-addon-mpf/static-lse.mdx delete mode 100644 docs/api/qiskit-addon-mpf/static-setup-approximate-model.mdx delete mode 100644 docs/api/qiskit-addon-mpf/static-setup-exact-model.mdx delete mode 100644 docs/api/qiskit-addon-mpf/static-setup-lse.mdx delete mode 100644 docs/api/qiskit-addon-obp/backpropagate.mdx create mode 100644 docs/api/qiskit-addon-obp/index.mdx delete mode 100644 docs/api/qiskit-addon-obp/utils-operations-apply-op-to.mdx delete mode 100644 docs/api/qiskit-addon-obp/utils-operations-reduce-op.mdx delete mode 100644 docs/api/qiskit-addon-obp/utils-operations-to-global-op.mdx delete mode 100644 docs/api/qiskit-addon-obp/utils-simplify-operator-budget.mdx delete mode 100644 docs/api/qiskit-addon-obp/utils-simplify-simplify-metadata.mdx delete mode 100644 docs/api/qiskit-addon-obp/utils-simplify-simplify.mdx delete mode 100644 docs/api/qiskit-addon-obp/utils-truncating-setup-budget.mdx delete mode 100644 docs/api/qiskit-addon-obp/utils-truncating-truncate-binary-search.mdx delete mode 100644 docs/api/qiskit-addon-obp/utils-truncating-truncation-error-budget.mdx delete mode 100644 docs/api/qiskit-addon-obp/utils-visualization-plot-accumulated-error.mdx delete mode 100644 docs/api/qiskit-addon-obp/utils-visualization-plot-left-over-error-budget.mdx delete mode 100644 docs/api/qiskit-addon-obp/utils-visualization-plot-num-paulis.mdx delete mode 100644 docs/api/qiskit-addon-obp/utils-visualization-plot-num-qwc-groups.mdx delete mode 100644 docs/api/qiskit-addon-obp/utils-visualization-plot-num-truncated-paulis.mdx delete mode 100644 docs/api/qiskit-addon-obp/utils-visualization-plot-slice-errors.mdx delete mode 100644 docs/api/qiskit-addon-obp/utils-visualization-plot-sum-paulis.mdx delete mode 100644 docs/api/qiskit-addon-obp/utils.mdx delete mode 100644 docs/api/qiskit-addon-sqd/configuration-recovery-post-select-by-hamming-weight.mdx delete mode 100644 docs/api/qiskit-addon-sqd/configuration-recovery-recover-configurations.mdx delete mode 100644 docs/api/qiskit-addon-sqd/counts-counts-to-arrays.mdx delete mode 100644 docs/api/qiskit-addon-sqd/counts-generate-counts-bipartite-hamming.mdx delete mode 100644 docs/api/qiskit-addon-sqd/counts-generate-counts-uniform.mdx delete mode 100644 docs/api/qiskit-addon-sqd/counts-normalize-counts-dict.mdx delete mode 100644 docs/api/qiskit-addon-sqd/fermion-bitstring-matrix-to-ci-strs.mdx delete mode 100644 docs/api/qiskit-addon-sqd/fermion-bitstring-matrix-to-sorted-addresses.mdx delete mode 100644 docs/api/qiskit-addon-sqd/fermion-enlarge-batch-from-transitions.mdx delete mode 100644 docs/api/qiskit-addon-sqd/fermion-flip-orbital-occupancies.mdx delete mode 100644 docs/api/qiskit-addon-sqd/fermion-optimize-orbitals.mdx delete mode 100644 docs/api/qiskit-addon-sqd/fermion-rotate-integrals.mdx delete mode 100644 docs/api/qiskit-addon-sqd/fermion-solve-fermion.mdx create mode 100644 docs/api/qiskit-addon-sqd/index.mdx delete mode 100644 docs/api/qiskit-addon-sqd/qiskit-addon-sqd.mdx delete mode 100644 docs/api/qiskit-addon-sqd/qubit-matrix-elements-from-pauli.mdx delete mode 100644 docs/api/qiskit-addon-sqd/qubit-project-operator-to-subspace.mdx delete mode 100644 docs/api/qiskit-addon-sqd/qubit-solve-qubit.mdx delete mode 100644 docs/api/qiskit-addon-sqd/qubit-sort-and-remove-duplicates.mdx delete mode 100644 docs/api/qiskit-addon-sqd/subsampling-postselect-and-subsample.mdx delete mode 100644 docs/api/qiskit-addon-sqd/subsampling-subsample.mdx delete mode 100644 docs/api/qiskit-addon-utils/coloring-auto-color-edges.mdx delete mode 100644 docs/api/qiskit-addon-utils/coloring-is-valid-edge-coloring.mdx create mode 100644 docs/api/qiskit-addon-utils/index.mdx delete mode 100644 docs/api/qiskit-addon-utils/problem-generators-generate-time-evolution-circuit.mdx delete mode 100644 docs/api/qiskit-addon-utils/problem-generators-generate-xyz-hamiltonian.mdx delete mode 100644 docs/api/qiskit-addon-utils/problem-generators-pauli-order-strategy.mdx delete mode 100644 docs/api/qiskit-addon-utils/qiskit-addon-utils.mdx delete mode 100644 docs/api/qiskit-addon-utils/slicing-combine-slices.mdx delete mode 100644 docs/api/qiskit-addon-utils/slicing-slice-by-barriers.mdx delete mode 100644 docs/api/qiskit-addon-utils/slicing-slice-by-coloring.mdx delete mode 100644 docs/api/qiskit-addon-utils/slicing-slice-by-depth.mdx delete mode 100644 docs/api/qiskit-addon-utils/slicing-slice-by-gate-types.mdx delete mode 100644 docs/api/qiskit-addon-utils/slicing-transpiler.mdx create mode 100644 public/images/api/qiskit-addon-cutting/qiskit_addon_cutting-instructions-1.svg create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-10_00.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-10_01.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-10_02.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-10_03.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-10_04.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-12_00.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-12_01.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-12_02.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-12_03.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-12_04.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-12_05.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-14_00.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-14_01.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-14_02.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-14_03.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-14_04.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-14_05.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-14_06.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-2.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-4_00.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-4_01.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-6_00.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-6_01.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-6_02.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-8_00.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-8_01.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-8_02.png create mode 100644 public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-8_03.png create mode 100644 public/images/api/qiskit-addon-utils/qiskit_addon_utils-problem_generators-1.png diff --git a/docs/api/qiskit-addon-cutting/_toc.json b/docs/api/qiskit-addon-cutting/_toc.json index 502ff98d816..3cf15272071 100644 --- a/docs/api/qiskit-addon-cutting/_toc.json +++ b/docs/api/qiskit-addon-cutting/_toc.json @@ -7,144 +7,39 @@ }, { "title": "qiskit_addon_cutting", - "children": [ - { - "title": "Module overview", - "url": "/api/qiskit-addon-cutting" - }, - { - "title": "BaseQPDGate", - "url": "/api/qiskit-addon-cutting/qpd-base-qpd-gate" - }, - { - "title": "bit_count", - "url": "/api/qiskit-addon-cutting/utils-bitwise-bit-count" - }, - { - "title": "CommutingObservableGroup", - "url": "/api/qiskit-addon-cutting/utils-observable-grouping-commuting-observable-group" - }, - { - "title": "ConsolidateResets", - "url": "/api/qiskit-addon-cutting/utils-transpiler-passes-consolidate-resets" - }, - { - "title": "cut_gates", - "url": "/api/qiskit-addon-cutting/cut-gates" - }, - { - "title": "cut_wires", - "url": "/api/qiskit-addon-cutting/cut-wires" - }, - { - "title": "CutWire", - "url": "/api/qiskit-addon-cutting/instructions-cut-wire" - }, - { - "title": "decompose_qpd_instructions", - "url": "/api/qiskit-addon-cutting/qpd-decompose-qpd-instructions" - }, - { - "title": "DeviceConstraints", - "url": "/api/qiskit-addon-cutting/device-constraints" - }, - { - "title": "ExactSampler", - "url": "/api/qiskit-addon-cutting/utils-simulation-exact-sampler" - }, - { - "title": "expand_observables", - "url": "/api/qiskit-addon-cutting/expand-observables" - }, - { - "title": "find_cuts", - "url": "/api/qiskit-addon-cutting/find-cuts" - }, - { - "title": "generate_cutting_experiments", - "url": "/api/qiskit-addon-cutting/generate-cutting-experiments" - }, - { - "title": "generate_qpd_weights", - "url": "/api/qiskit-addon-cutting/qpd-generate-qpd-weights" - }, - { - "title": "Move", - "url": "/api/qiskit-addon-cutting/instructions-move" - }, - { - "title": "ObservableCollection", - "url": "/api/qiskit-addon-cutting/utils-observable-grouping-observable-collection" - }, - { - "title": "observables_restricted_to_subsystem", - "url": "/api/qiskit-addon-cutting/utils-observable-grouping-observables-restricted-to-subsystem" - }, - { - "title": "OptimizationParameters", - "url": "/api/qiskit-addon-cutting/optimization-parameters" - }, - { - "title": "partition_circuit_qubits", - "url": "/api/qiskit-addon-cutting/partition-circuit-qubits" - }, - { - "title": "partition_problem", - "url": "/api/qiskit-addon-cutting/partition-problem" - }, - { - "title": "PartitionedCuttingProblem", - "url": "/api/qiskit-addon-cutting/partitioned-cutting-problem" - }, - { - "title": "QPDBasis", - "url": "/api/qiskit-addon-cutting/qpd-qpd-basis" - }, - { - "title": "qpdbasis_from_instruction", - "url": "/api/qiskit-addon-cutting/qpd-qpdbasis-from-instruction" - }, - { - "title": "reconstruct_expectation_values", - "url": "/api/qiskit-addon-cutting/reconstruct-expectation-values" - }, - { - "title": "RemoveFinalReset", - "url": "/api/qiskit-addon-cutting/utils-transpiler-passes-remove-final-reset" - }, - { - "title": "separate_circuit", - "url": "/api/qiskit-addon-cutting/utils-transforms-separate-circuit" - }, - { - "title": "SeparatedCircuits", - "url": "/api/qiskit-addon-cutting/utils-transforms-separated-circuits" - }, - { - "title": "simulate_statevector_outcomes", - "url": "/api/qiskit-addon-cutting/utils-simulation-simulate-statevector-outcomes" - }, - { - "title": "SingleQubitQPDGate", - "url": "/api/qiskit-addon-cutting/qpd-single-qubit-qpd-gate" - }, - { - "title": "TwoQubitQPDGate", - "url": "/api/qiskit-addon-cutting/qpd-two-qubit-qpd-gate" - }, - { - "title": "unique_by_eq", - "url": "/api/qiskit-addon-cutting/utils-iteration-unique-by-eq" - }, - { - "title": "unique_by_id", - "url": "/api/qiskit-addon-cutting/utils-iteration-unique-by-id" - }, - { - "title": "WeightType", - "url": "/api/qiskit-addon-cutting/qpd-weight-type" - } - ] + "url": "/api/qiskit-addon-cutting/qiskit-addon-cutting" + }, + { + "title": "qiskit_addon_cutting.instructions", + "url": "/api/qiskit-addon-cutting/instructions" + }, + { + "title": "qiskit_addon_cutting.qpd", + "url": "/api/qiskit-addon-cutting/qpd" + }, + { + "title": "qiskit_addon_cutting.utils.bitwise", + "url": "/api/qiskit-addon-cutting/utils-bitwise" + }, + { + "title": "qiskit_addon_cutting.utils.iteration", + "url": "/api/qiskit-addon-cutting/utils-iteration" + }, + { + "title": "qiskit_addon_cutting.utils.observable_grouping", + "url": "/api/qiskit-addon-cutting/utils-observable-grouping" + }, + { + "title": "qiskit_addon_cutting.utils.simulation", + "url": "/api/qiskit-addon-cutting/utils-simulation" + }, + { + "title": "qiskit_addon_cutting.utils.transforms", + "url": "/api/qiskit-addon-cutting/utils-transforms" + }, + { + "title": "qiskit_addon_cutting.utils.transpiler_passes", + "url": "/api/qiskit-addon-cutting/utils-transpiler-passes" }, { "title": "Release notes", diff --git a/docs/api/qiskit-addon-cutting/cut-gates.mdx b/docs/api/qiskit-addon-cutting/cut-gates.mdx deleted file mode 100644 index 4b324566278..00000000000 --- a/docs/api/qiskit-addon-cutting/cut-gates.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: cut_gates -description: API reference for qiskit_addon_cutting.cut_gates -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_cutting.cut_gates ---- - - - -# qiskit\_addon\_cutting.cut\_gates - - - Transform specified gates into [`TwoQubitQPDGate`](qpd-two-qubit-qpd-gate "qiskit_addon_cutting.qpd.TwoQubitQPDGate")s. - - **Parameters** - - * **circuit** ([`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")) – The circuit containing gates to be decomposed - * **gate\_ids** ([`Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")\[[`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")]) – The indices of the gates to decompose - * **inplace** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – Flag denoting whether to copy the input circuit before acting on it - - **Return type** - - [`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)"), [`list`](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")\[[`QPDBasis`](qpd-qpd-basis "qiskit_addon_cutting.qpd.qpd_basis.QPDBasis")]] - - **Returns** - - A copy of the input circuit with the specified gates replaced with [`TwoQubitQPDGate`](qpd-two-qubit-qpd-gate "qiskit_addon_cutting.qpd.TwoQubitQPDGate")s and a list of [`QPDBasis`](qpd-qpd-basis "qiskit_addon_cutting.qpd.QPDBasis") instances – one for each decomposed gate. - - **Raises** - - [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The input circuit should contain no classical bits or registers. - - diff --git a/docs/api/qiskit-addon-cutting/cut-wires.mdx b/docs/api/qiskit-addon-cutting/cut-wires.mdx deleted file mode 100644 index 5800119212c..00000000000 --- a/docs/api/qiskit-addon-cutting/cut-wires.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: cut_wires -description: API reference for qiskit_addon_cutting.cut_wires -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_cutting.cut_wires ---- - - - -# qiskit\_addon\_cutting.cut\_wires - - - Transform all [`CutWire`](instructions-cut-wire "qiskit_addon_cutting.instructions.CutWire") instructions in a circuit to [`Move`](instructions-move "qiskit_addon_cutting.instructions.Move") instructions marked for cutting. - - The returned circuit will have one newly allocated qubit for every [`CutWire`](instructions-cut-wire "qiskit_addon_cutting.instructions.CutWire") instruction. - - See Sec. 3 and Appendix A of [2302.03366v1](https://arxiv.org/abs/2302.03366v1) for more information about the two different representations of wire cuts: single-qubit ([`CutWire`](instructions-cut-wire "qiskit_addon_cutting.instructions.CutWire")) vs. two-qubit ([`Move`](instructions-move "qiskit_addon_cutting.instructions.Move")). - - **Parameters** - - **circuit** ([`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")) – Original circuit with [`CutWire`](instructions-cut-wire "qiskit_addon_cutting.instructions.CutWire") instructions - - **Returns** - - New circuit with [`CutWire`](instructions-cut-wire "qiskit_addon_cutting.instructions.CutWire") instructions replaced by [`Move`](instructions-move "qiskit_addon_cutting.instructions.Move") instructions wrapped in `TwoQubitQPDGate`s - - **Return type** - - circuit - - diff --git a/docs/api/qiskit-addon-cutting/device-constraints.mdx b/docs/api/qiskit-addon-cutting/device-constraints.mdx deleted file mode 100644 index 6b5431b7867..00000000000 --- a/docs/api/qiskit-addon-cutting/device-constraints.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: DeviceConstraints -description: API reference for qiskit_addon_cutting.DeviceConstraints -in_page_toc_min_heading_level: 1 -python_api_type: class -python_api_name: qiskit_addon_cutting.DeviceConstraints ---- - - - -# qiskit\_addon\_cutting.DeviceConstraints - - - Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.13)") - - Specify the constraints (qubits per subcircuit) that must be respected. - - ## Methods - - | | | - | ----------------------------------- | ------------------------------------------- | - | `__init__`(qubits\_per\_subcircuit) | | - | `get_qpu_width`() | Return the number of qubits per subcircuit. | - - ## Attributes - - | | | - | ----------------------- | - | - | `qubits_per_subcircuit` | | - - diff --git a/docs/api/qiskit-addon-cutting/expand-observables.mdx b/docs/api/qiskit-addon-cutting/expand-observables.mdx deleted file mode 100644 index 766ffa07455..00000000000 --- a/docs/api/qiskit-addon-cutting/expand-observables.mdx +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: expand_observables -description: API reference for qiskit_addon_cutting.expand_observables -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_cutting.expand_observables ---- - - - -# qiskit\_addon\_cutting.expand\_observables - - - Expand observable(s) according to the qubit mapping between `original_circuit` and `final_circuit`. - - The `Qubit`s on `final_circuit` must be a superset of those on `original_circuit`. - - Given a `PauliList` of observables, this function returns new observables with identity operators placed on the qubits that did not exist in `original_circuit`. This way, observables on `original_circuit` can be mapped to appropriate observables on `final_circuit`. - - This function is designed to be used after calling `final_circuit = transform_cuts_to_moves(original_circuit)` (see `transform_cuts_to_moves()`). - - This function requires `observables.num_qubits == original_circuit.num_qubits` and returns new observables such that `retval.num_qubits == final_circuit.num_qubits`. - - **Parameters** - - * **observables** ([`PauliList`](/api/qiskit/qiskit.quantum_info.PauliList "(in Qiskit v1.2)")) – Observables corresponding to `original_circuit` - * **original\_circuit** ([`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")) – Original circuit - * **final\_circuit** ([`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")) – Final circuit, whose qubits the original `observables` should be expanded to - - **Return type** - - [`PauliList`](/api/qiskit/qiskit.quantum_info.PauliList "(in Qiskit v1.2)") - - **Returns** - - New $N$-qubit observables which are compatible with the $N$-qubit `final_circuit` - - **Raises** - - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – `observables` and `original_circuit` have different number of qubits. - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Qubit from `original_circuit` cannot be found in `final_circuit`. - - diff --git a/docs/api/qiskit-addon-cutting/find-cuts.mdx b/docs/api/qiskit-addon-cutting/find-cuts.mdx deleted file mode 100644 index 53e94280ef3..00000000000 --- a/docs/api/qiskit-addon-cutting/find-cuts.mdx +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: find_cuts -description: API reference for qiskit_addon_cutting.find_cuts -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_cutting.find_cuts ---- - - - -# qiskit\_addon\_cutting.find\_cuts - - - Find cut locations in a circuit, given optimization parameters and cutting constraints. - - **Parameters** - - * **circuit** ([`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")) – The circuit to cut. The input circuit may not contain gates acting on more than two qubits. - * **optimization** ([`OptimizationParameters`](optimization-parameters "qiskit_addon_cutting.automated_cut_finding.OptimizationParameters")) – Options for controlling optimizer behavior. Currently, the optimal cuts are chosen using Dijkstra’s best-first search algorithm. - * **constraints** ([`DeviceConstraints`](device-constraints "qiskit_addon_cutting.automated_cut_finding.DeviceConstraints")) – Constraints on how the circuit may be partitioned - - **Return type** - - [`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)"), [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)"), [`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")]] - - **Returns** - - A circuit containing [`BaseQPDGate`](qpd-base-qpd-gate "qiskit_addon_cutting.qpd.BaseQPDGate") instances. The subcircuits resulting from cutting these gates will be runnable on the devices meeting the `constraints`. - - **A metadata dictionary:** - - * cuts: A list of length-2 tuples describing each cut in the output circuit. The tuples are formatted as `(cut_type: str, cut_id: int)`. The cut ID is the index of the cut gate or wire in the output circuit’s `data` field. - * sampling\_overhead: The sampling overhead incurred from cutting the specified gates and wires. - * minimum\_reached: A bool indicating whether or not the search conclusively found the minimum of cost function. `minimum_reached = False` could also mean that the cost returned was actually the lowest possible cost but that the search was not allowed to run long enough to prove that this was the case. - - **Raises** - - [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The input circuit contains a gate acting on more than 2 qubits. - - diff --git a/docs/api/qiskit-addon-cutting/generate-cutting-experiments.mdx b/docs/api/qiskit-addon-cutting/generate-cutting-experiments.mdx deleted file mode 100644 index 49d2b8db851..00000000000 --- a/docs/api/qiskit-addon-cutting/generate-cutting-experiments.mdx +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: generate_cutting_experiments -description: API reference for qiskit_addon_cutting.generate_cutting_experiments -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_cutting.generate_cutting_experiments ---- - - - -# qiskit\_addon\_cutting.generate\_cutting\_experiments - - - Generate cutting subexperiments and their associated coefficients. - - If the input, `circuits`, is a `QuantumCircuit` instance, the output subexperiments will be contained within a 1D array, and `observables` is expected to be a `PauliList` instance. - - If the input circuit and observables are specified by dictionaries with partition labels as keys, the output subexperiments will be returned as a dictionary which maps each partition label to a 1D array containing the subexperiments associated with that partition. - - In both cases, the subexperiment lists are ordered as follows: - - > $[sample_{0}observable_{0}, \ldots, sample_{0}observable_{N-1}, sample_{1}observable_{0}, \ldots, sample_{M-1}observable_{N-1}]$ - - The coefficients will always be returned as a 1D array – one coefficient for each unique sample. - - **Parameters** - - * **circuits** (QuantumCircuit | dict\[Hashable, QuantumCircuit]) – The circuit(s) to partition and separate - * **observables** (PauliList | dict\[Hashable, PauliList]) – The observable(s) to evaluate for each unique sample - * **num\_samples** (int | float) – The number of samples to draw from the quasi-probability distribution. If set to infinity, the weights will be generated rigorously rather than by sampling from the distribution. - - **Return type** - - tuple\[list\[QuantumCircuit] | dict\[Hashable, list\[QuantumCircuit]], list\[tuple\[float, WeightType]]] - - **Returns** - - A tuple containing the cutting experiments and their associated coefficients. If the input circuits is a `QuantumCircuit` instance, the output subexperiments will be a sequence of circuits – one for every unique sample and observable. If the input circuits are represented as a dictionary keyed by partition labels, the output subexperiments will also be a dictionary keyed by partition labels and containing the subexperiments for each partition. The coefficients are always a sequence of length-2 tuples, where each tuple contains the coefficient and the `WeightType`. Each coefficient corresponds to one unique sample. - - **Raises** - - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – `num_samples` must be at least one. - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – `circuits` and `observables` are incompatible types - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – `SingleQubitQPDGate` instances must have their cut ID appended to the gate label so they may be associated with other gates belonging to the same cut. - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – `SingleQubitQPDGate` instances are not allowed in unseparated circuits. - - diff --git a/docs/api/qiskit-addon-cutting/index.mdx b/docs/api/qiskit-addon-cutting/index.mdx index add344534d7..b6ff5ae5916 100644 --- a/docs/api/qiskit-addon-cutting/index.mdx +++ b/docs/api/qiskit-addon-cutting/index.mdx @@ -1,150 +1,13 @@ ---- -title: qiskit_addon_cutting -description: API reference for qiskit_addon_cutting -in_page_toc_min_heading_level: 2 -python_api_type: module -python_api_name: qiskit_addon_cutting ---- - - - -# API References - -## Circuit Cutting - -Circuit Cutting ([`qiskit_addon_cutting`](#module-qiskit_addon_cutting "qiskit_addon_cutting")). - - - -### Circuit Cutting - -| | | -| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`cut_wires`](cut-wires "qiskit_addon_cutting.cut_wires") | Transform all [`CutWire`](instructions-cut-wire "qiskit_addon_cutting.instructions.CutWire") instructions in a circuit to [`Move`](instructions-move "qiskit_addon_cutting.instructions.Move") instructions marked for cutting. | -| [`expand_observables`](expand-observables "qiskit_addon_cutting.expand_observables") | Expand observable(s) according to the qubit mapping between `original_circuit` and `final_circuit`. | -| [`partition_circuit_qubits`](partition-circuit-qubits "qiskit_addon_cutting.partition_circuit_qubits") | Replace all nonlocal gates belonging to more than one partition with instances of [`TwoQubitQPDGate`](qpd-two-qubit-qpd-gate "qiskit_addon_cutting.qpd.TwoQubitQPDGate"). | -| [`partition_problem`](partition-problem "qiskit_addon_cutting.partition_problem") | Separate an input circuit and observable(s). | -| [`cut_gates`](cut-gates "qiskit_addon_cutting.cut_gates") | Transform specified gates into [`TwoQubitQPDGate`](qpd-two-qubit-qpd-gate "qiskit_addon_cutting.qpd.TwoQubitQPDGate")s. | -| [`generate_cutting_experiments`](generate-cutting-experiments "qiskit_addon_cutting.generate_cutting_experiments") | Generate cutting subexperiments and their associated coefficients. | -| [`reconstruct_expectation_values`](reconstruct-expectation-values "qiskit_addon_cutting.reconstruct_expectation_values") | Reconstruct an expectation value from the results of the sub-experiments. | - -| | | -| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -| [`PartitionedCuttingProblem`](partitioned-cutting-problem "qiskit_addon_cutting.PartitionedCuttingProblem") | The result of decomposing and separating a circuit and observable(s). | -| [`instructions.CutWire`](instructions-cut-wire "qiskit_addon_cutting.instructions.CutWire") | An instruction for denoting a wire cut location. | -| [`instructions.Move`](instructions-move "qiskit_addon_cutting.instructions.Move") | A two-qubit instruction representing a reset of the second qubit followed by a swap. | - -#### Automatic Cut Finding - -| | | -| --------------------------------------------------------- | --------------------------------------------------------------------------------------- | -| [`find_cuts`](find-cuts "qiskit_addon_cutting.find_cuts") | Find cut locations in a circuit, given optimization parameters and cutting constraints. | - -| | | -| ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -| [`OptimizationParameters`](optimization-parameters "qiskit_addon_cutting.OptimizationParameters") | Specify parameters that control the optimization. | -| [`DeviceConstraints`](device-constraints "qiskit_addon_cutting.DeviceConstraints") | Specify the constraints (qubits per subcircuit) that must be respected. | - -### Quasi-Probability Decomposition (QPD) - -| | | -| --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -| [`qpd.QPDBasis`](qpd-qpd-basis "qiskit_addon_cutting.qpd.QPDBasis") | Basis in which to decompose an operation. | -| [`qpd.BaseQPDGate`](qpd-base-qpd-gate "qiskit_addon_cutting.qpd.BaseQPDGate") | Base class for a gate to be decomposed using quasiprobability decomposition. | -| [`qpd.SingleQubitQPDGate`](qpd-single-qubit-qpd-gate "qiskit_addon_cutting.qpd.SingleQubitQPDGate") | Single qubit gate to be decomposed using quasiprobability decomposition. | -| [`qpd.TwoQubitQPDGate`](qpd-two-qubit-qpd-gate "qiskit_addon_cutting.qpd.TwoQubitQPDGate") | Two qubit gate to be decomposed using quasiprobability decomposition. | -| [`qpd.WeightType`](qpd-weight-type "qiskit_addon_cutting.qpd.WeightType") | Type of weight associated with a QPD sample. | - -| | | -| ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | -| [`qpd.generate_qpd_weights`](qpd-generate-qpd-weights "qiskit_addon_cutting.qpd.generate_qpd_weights") | Generate weights from the joint quasiprobability distribution. | -| [`qpd.decompose_qpd_instructions`](qpd-decompose-qpd-instructions "qiskit_addon_cutting.qpd.decompose_qpd_instructions") | Replace all QPD instructions in the circuit with local Qiskit operations and measurements. | -| [`qpd.qpdbasis_from_instruction`](qpd-qpdbasis-from-instruction "qiskit_addon_cutting.qpd.qpdbasis_from_instruction") | Generate a [`QPDBasis`](qpd-qpd-basis "qiskit_addon_cutting.qpd.QPDBasis") object, given a supported operation. | - - - -## Utilities - -Utility functions. - - - - - -### Bitwise utilities ([`qiskit_addon_cutting.utils.bitwise`](#module-qiskit_addon_cutting.utils.bitwise "qiskit_addon_cutting.utils.bitwise")) - -Bitwise utilities. - -| | | -| ------------------------------------------------------------------------------------------- | ------------------------- | -| [`bit_count`](utils-bitwise-bit-count "qiskit_addon_cutting.utils.bitwise.bit_count")(x, /) | Count number of set bits. | - - - - - -### Iteration utilities ([`qiskit_addon_cutting.utils.iteration`](#module-qiskit_addon_cutting.utils.iteration "qiskit_addon_cutting.utils.iteration")) - -Iteration utilities. - -| | | -| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | -| [`unique_by_id`](utils-iteration-unique-by-id "qiskit_addon_cutting.utils.iteration.unique_by_id")(iterable, /) | Return unique objects in `iterable`, by identity. | -| [`unique_by_eq`](utils-iteration-unique-by-eq "qiskit_addon_cutting.utils.iteration.unique_by_eq")(iterable, /) | Return unique objects in `iterable`, by equality. | - - - - - -### Observable grouping ([`qiskit_addon_cutting.utils.observable_grouping`](#module-qiskit_addon_cutting.utils.observable_grouping "qiskit_addon_cutting.utils.observable_grouping")) - -Module for conducting Pauli observable grouping. - -| | | -| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -| [`observables_restricted_to_subsystem`](utils-observable-grouping-observables-restricted-to-subsystem "qiskit_addon_cutting.utils.observable_grouping.observables_restricted_to_subsystem")(qubits, ...) | Restrict each observable to its support on a given subsystem. | -| [`CommutingObservableGroup`](utils-observable-grouping-commuting-observable-group "qiskit_addon_cutting.utils.observable_grouping.CommutingObservableGroup")(general\_observable, ...) | Set of mutually qubit-wise commuting observables. | -| [`ObservableCollection`](utils-observable-grouping-observable-collection "qiskit_addon_cutting.utils.observable_grouping.ObservableCollection")(observables, /) | Collection of observables organized for efficient taking of measurements. | - - - - - -### Simulation ([`qiskit_addon_cutting.utils.simulation`](#module-qiskit_addon_cutting.utils.simulation "qiskit_addon_cutting.utils.simulation")) - -Simulation of precise measurement outcome probabilities. - -| | | -| -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | -| [`simulate_statevector_outcomes`](utils-simulation-simulate-statevector-outcomes "qiskit_addon_cutting.utils.simulation.simulate_statevector_outcomes")(qc, /) | Return each classical outcome along with its precise probability. | -| [`ExactSampler`](utils-simulation-exact-sampler "qiskit_addon_cutting.utils.simulation.ExactSampler")(\*\[, options]) | Sampler which returns exact probabilities for each possible outcome. | - - - - - -### Transforms ([`qiskit_addon_cutting.utils.transforms`](#module-qiskit_addon_cutting.utils.transforms "qiskit_addon_cutting.utils.transforms")) - -Functions for manipulating quantum circuits. - -| | | -| ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | -| [`separate_circuit`](utils-transforms-separate-circuit "qiskit_addon_cutting.utils.transforms.separate_circuit")(circuit\[, partition\_labels]) | Separate the circuit into its disconnected components. | - -| | | -| --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| [`SeparatedCircuits`](utils-transforms-separated-circuits "qiskit_addon_cutting.utils.transforms.SeparatedCircuits")(subcircuits, qubit\_map) | Named tuple for result of [`separate_circuit()`](utils-transforms-separate-circuit "qiskit_addon_cutting.utils.transforms.separate_circuit"). | - - - - - -### Transpiler passes ([`qiskit_addon_cutting.utils.transpiler_passes`](#module-qiskit_addon_cutting.utils.transpiler_passes "qiskit_addon_cutting.utils.transpiler_passes")) - -Transpiler passes useful for circuit knitting. - -| | | -| ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | -| [`RemoveFinalReset`](utils-transpiler-passes-remove-final-reset "qiskit_addon_cutting.utils.transpiler_passes.RemoveFinalReset")(\*args, \*\*kwargs) | Remove reset when it is the final instruction on a qubit wire. | -| [`ConsolidateResets`](utils-transpiler-passes-consolidate-resets "qiskit_addon_cutting.utils.transpiler_passes.ConsolidateResets")(\*args, \*\*kwargs) | Consolidate a run duplicate resets in to a single reset. | - + + +# `qiskit-addon-cutting` API reference + +* [Circuit cutting (`qiskit_addon_cutting`)](qiskit-addon-cutting) +* [Instructions (`qiskit_addon_cutting.instructions`)](instructions) +* [Quasi-Probability Decomposition (QPD) (`qiskit_addon_cutting.qpd`)](qpd) +* [Bitwise utilities (`qiskit_addon_cutting.utils.bitwise`)](utils-bitwise) +* [Iteration utilities (`qiskit_addon_cutting.utils.iteration`)](utils-iteration) +* [Observable grouping (`qiskit_addon_cutting.utils.observable_grouping`)](utils-observable-grouping) +* [Simulation utilities (`qiskit_addon_cutting.utils.simulation`)](utils-simulation) +* [Transforms (`qiskit_addon_cutting.utils.transforms`)](utils-transforms) +* [Transpiler passes (`qiskit_addon_cutting.utils.transpiler_passes`)](utils-transpiler-passes) diff --git a/docs/api/qiskit-addon-cutting/instructions-cut-wire.mdx b/docs/api/qiskit-addon-cutting/instructions-cut-wire.mdx deleted file mode 100644 index 328efa08218..00000000000 --- a/docs/api/qiskit-addon-cutting/instructions-cut-wire.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: CutWire -description: API reference for qiskit_addon_cutting.instructions.CutWire -in_page_toc_min_heading_level: 1 -python_api_type: class -python_api_name: qiskit_addon_cutting.instructions.CutWire ---- - - - -# qiskit\_addon\_cutting.instructions.CutWire - - - Bases: [`Gate`](/api/qiskit/qiskit.circuit.Gate "(in Qiskit v1.2)") - - An instruction for denoting a wire cut location. - - Create CutWire instruction. - - ## Methods - - | | | - | -------------------- | --------------------------- | - | `__init__`(\[label]) | Create CutWire instruction. | - - ## Attributes - - | | - | - | - - diff --git a/docs/api/qiskit-addon-cutting/instructions-move.mdx b/docs/api/qiskit-addon-cutting/instructions.mdx similarity index 66% rename from docs/api/qiskit-addon-cutting/instructions-move.mdx rename to docs/api/qiskit-addon-cutting/instructions.mdx index a1adefdae20..cb9d189fda7 100644 --- a/docs/api/qiskit-addon-cutting/instructions-move.mdx +++ b/docs/api/qiskit-addon-cutting/instructions.mdx @@ -1,18 +1,32 @@ --- -title: Move -description: API reference for qiskit_addon_cutting.instructions.Move -in_page_toc_min_heading_level: 1 -python_api_type: class -python_api_name: qiskit_addon_cutting.instructions.Move +title: instructions +description: API reference for qiskit_addon_cutting.instructions +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_addon_cutting.instructions --- - + -# qiskit\_addon\_cutting.instructions.Move + - - Bases: [`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v1.2)") +# Instructions +`qiskit_addon_cutting.instructions` + +Quantum circuit `Instruction`s useful for circuit cutting. + +### CutWire + + + An instruction for denoting a wire cut location. + + Create CutWire instruction. + + +### Move + + A two-qubit instruction representing a reset of the second qubit followed by a swap. **Circuit Symbol:** @@ -50,21 +64,10 @@ python_api_name: qiskit_addon_cutting.instructions.Move qc.draw("mpl") ``` - ![../\_images/qiskit\_addon\_cutting-instructions-Move-1.svg](/images/api/qiskit-addon-cutting/qiskit_addon_cutting-instructions-Move-1.svg) + ![../\_images/qiskit\_addon\_cutting-instructions-1.svg](/images/api/qiskit-addon-cutting/qiskit_addon_cutting-instructions-1.svg) A full demonstration of the [`Move`](#qiskit_addon_cutting.instructions.Move "qiskit_addon_cutting.instructions.Move") instruction is available in [the introductory tutorial on wire cutting](https://qiskit.github.io/qiskit-addon-cutting/tutorials/03_wire_cutting_via_move_instruction.html). Create a [`Move`](#qiskit_addon_cutting.instructions.Move "qiskit_addon_cutting.instructions.Move") instruction. - - ## Methods - - | | | - | -------------------- | ---------------------------------------------------------------------------------------------------------------- | - | `__init__`(\[label]) | Create a [`Move`](#qiskit_addon_cutting.instructions.Move "qiskit_addon_cutting.instructions.Move") instruction. | - - ## Attributes - - | | - | - | diff --git a/docs/api/qiskit-addon-cutting/optimization-parameters.mdx b/docs/api/qiskit-addon-cutting/optimization-parameters.mdx deleted file mode 100644 index 9094f8873a1..00000000000 --- a/docs/api/qiskit-addon-cutting/optimization-parameters.mdx +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: OptimizationParameters -description: API reference for qiskit_addon_cutting.OptimizationParameters -in_page_toc_min_heading_level: 1 -python_api_type: class -python_api_name: qiskit_addon_cutting.OptimizationParameters ---- - - - -# qiskit\_addon\_cutting.OptimizationParameters - - - Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.13)") - - Specify parameters that control the optimization. - - If either of the constraints specified by `max_backjumps` or `max_gamma` are exceeded, the search terminates but nevertheless returns the result of a greedy best first search, which gives an *upper-bound* on gamma. - - ## Methods - - | | | - | ---------------------------------------------------- | - | - | `__init__`(\[seed, max\_gamma, max\_backjumps, ...]) | | - - ## Attributes - - | | | - | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | - | `gate_lo` | Bool indicating whether or not to allow LO gate cuts while finding cuts. | - | `max_backjumps` | Maximum number of backjumps that can be performed before the search is forced to terminate; setting it to `None` implies that no such restriction is placed. | - | `max_gamma` | Maximum allowed value of gamma which, if exceeded, forces the search to terminate. | - | `seed` | The seed to use when initializing Numpy random number generators in the best first search priority queue. | - | `wire_lo` | Bool indicating whether or not to allow LO wire cuts while finding cuts. | - - diff --git a/docs/api/qiskit-addon-cutting/partition-circuit-qubits.mdx b/docs/api/qiskit-addon-cutting/partition-circuit-qubits.mdx deleted file mode 100644 index 88592da45d9..00000000000 --- a/docs/api/qiskit-addon-cutting/partition-circuit-qubits.mdx +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: partition_circuit_qubits -description: API reference for qiskit_addon_cutting.partition_circuit_qubits -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_cutting.partition_circuit_qubits ---- - - - -# qiskit\_addon\_cutting.partition\_circuit\_qubits - - - Replace all nonlocal gates belonging to more than one partition with instances of [`TwoQubitQPDGate`](qpd-two-qubit-qpd-gate "qiskit_addon_cutting.qpd.TwoQubitQPDGate"). - - [`TwoQubitQPDGate`](qpd-two-qubit-qpd-gate "qiskit_addon_cutting.qpd.TwoQubitQPDGate")s belonging to a single partition will not be affected. - - **Parameters** - - * **circuit** ([`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")) – The circuit to partition - * **partition\_labels** ([`Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")\[[`Hashable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Hashable "(in Python v3.13)")]) – A sequence containing a partition label for each qubit in the input circuit. Nonlocal gates belonging to more than one partition will be replaced with [`TwoQubitQPDGate`](qpd-two-qubit-qpd-gate "qiskit_addon_cutting.qpd.TwoQubitQPDGate")s. - * **inplace** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – Flag denoting whether to copy the input circuit before acting on it - - **Return type** - - [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)") - - **Returns** - - The output circuit with each nonlocal gate spanning two partitions replaced by a [`TwoQubitQPDGate`](qpd-two-qubit-qpd-gate "qiskit_addon_cutting.qpd.TwoQubitQPDGate") - - **Raises** - - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The length of partition\_labels does not equal the number of qubits in the circuit. - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Input circuit contains unsupported gate. - - diff --git a/docs/api/qiskit-addon-cutting/partition-problem.mdx b/docs/api/qiskit-addon-cutting/partition-problem.mdx deleted file mode 100644 index e391d3bf590..00000000000 --- a/docs/api/qiskit-addon-cutting/partition-problem.mdx +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: partition_problem -description: API reference for qiskit_addon_cutting.partition_problem -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_cutting.partition_problem ---- - - - -# qiskit\_addon\_cutting.partition\_problem - - - Separate an input circuit and observable(s). - - If `partition_labels` is provided, then qubits with matching partition labels will be grouped together, and non-local gates spanning more than one partition will be cut apart. The label `None` is treated specially: any qubit with that partition label must be unused in the circuit. - - If `partition_labels` is not provided, then it will be determined automatically from the connectivity of the circuit. This automatic determination ignores any [`TwoQubitQPDGate`](qpd-two-qubit-qpd-gate "qiskit_addon_cutting.qpd.TwoQubitQPDGate")s in the `circuit`, as these denote instructions that are explicitly destined for cutting. The resulting partition labels, in the automatic case, will be consecutive integers starting with 0. Qubits which are idle throughout the circuit will be assigned a partition label of `None`. - - All cut instructions will be replaced with [`SingleQubitQPDGate`](qpd-single-qubit-qpd-gate "qiskit_addon_cutting.qpd.SingleQubitQPDGate")s. - - If provided, `observables` will be separated along the boundaries specified by the partition labels. - - **Parameters** - - * **circuit** (QuantumCircuit) – The circuit to partition and separate - * **partition\_labels** (Sequence\[Hashable] | None) – A sequence of labels, such that each label corresponds to the circuit qubit with the same index - * **observables** (PauliList | None) – The observables to separate - - **Return type** - - PartitionedCuttingProblem - - **Returns** - - A tuple containing a dictionary mapping a partition label to a subcircuit, a list of QPD bases (one for each circuit gate or wire which was decomposed), and, optionally, a dictionary mapping a partition label to a list of Pauli observables. - - **Raises** - - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The number of partition labels does not equal the number of qubits in the circuit. - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – An input observable acts on a different number of qubits than the input circuit. - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – An input observable has a phase not equal to 1. - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – A qubit with a label of `None` is not idle - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The input circuit should contain no classical bits or registers. - - diff --git a/docs/api/qiskit-addon-cutting/partitioned-cutting-problem.mdx b/docs/api/qiskit-addon-cutting/partitioned-cutting-problem.mdx deleted file mode 100644 index 9d8741f8e45..00000000000 --- a/docs/api/qiskit-addon-cutting/partitioned-cutting-problem.mdx +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: PartitionedCuttingProblem -description: API reference for qiskit_addon_cutting.PartitionedCuttingProblem -in_page_toc_min_heading_level: 1 -python_api_type: class -python_api_name: qiskit_addon_cutting.PartitionedCuttingProblem ---- - - - -# qiskit\_addon\_cutting.PartitionedCuttingProblem - - - Bases: [`NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple "(in Python v3.13)") - - The result of decomposing and separating a circuit and observable(s). - - Create new instance of PartitionedCuttingProblem(subcircuits, bases, subobservables) - - ## Methods - - | | - | - | - - ## Attributes - - | | | - | ---------------- | ------------------------ | - | `bases` | Alias for field number 1 | - | `subcircuits` | Alias for field number 0 | - | `subobservables` | Alias for field number 2 | - - diff --git a/docs/api/qiskit-addon-cutting/qiskit-addon-cutting.mdx b/docs/api/qiskit-addon-cutting/qiskit-addon-cutting.mdx new file mode 100644 index 00000000000..534def3a14f --- /dev/null +++ b/docs/api/qiskit-addon-cutting/qiskit-addon-cutting.mdx @@ -0,0 +1,284 @@ +--- +title: qiskit_addon_cutting +description: API reference for qiskit_addon_cutting +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_addon_cutting +--- + + + + + +# Circuit cutting + +`qiskit_addon_cutting` + +Circuit cutting. + +### cut\_wires + + + Transform all [`CutWire`](instructions#cutwire "qiskit_addon_cutting.instructions.CutWire") instructions in a circuit to [`Move`](instructions#move "qiskit_addon_cutting.instructions.Move") instructions marked for cutting. + + The returned circuit will have one newly allocated qubit for every [`CutWire`](instructions#cutwire "qiskit_addon_cutting.instructions.CutWire") instruction. + + See Sec. 3 and Appendix A of [2302.03366v1](https://arxiv.org/abs/2302.03366v1) for more information about the two different representations of wire cuts: single-qubit ([`CutWire`](instructions#cutwire "qiskit_addon_cutting.instructions.CutWire")) vs. two-qubit ([`Move`](instructions#move "qiskit_addon_cutting.instructions.Move")). + + **Parameters** + + **circuit** ([`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")) – Original circuit with [`CutWire`](instructions#cutwire "qiskit_addon_cutting.instructions.CutWire") instructions + + **Returns** + + New circuit with [`CutWire`](instructions#cutwire "qiskit_addon_cutting.instructions.CutWire") instructions replaced by [`Move`](instructions#move "qiskit_addon_cutting.instructions.Move") instructions wrapped in `TwoQubitQPDGate`s + + **Return type** + + circuit + + +### expand\_observables + + + Expand observable(s) according to the qubit mapping between `original_circuit` and `final_circuit`. + + The `Qubit`s on `final_circuit` must be a superset of those on `original_circuit`. + + Given a `PauliList` of observables, this function returns new observables with identity operators placed on the qubits that did not exist in `original_circuit`. This way, observables on `original_circuit` can be mapped to appropriate observables on `final_circuit`. + + This function is designed to be used after calling `final_circuit = transform_cuts_to_moves(original_circuit)` (see `transform_cuts_to_moves()`). + + This function requires `observables.num_qubits == original_circuit.num_qubits` and returns new observables such that `retval.num_qubits == final_circuit.num_qubits`. + + **Parameters** + + * **observables** ([`PauliList`](/api/qiskit/qiskit.quantum_info.PauliList "(in Qiskit v1.2)")) – Observables corresponding to `original_circuit` + * **original\_circuit** ([`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")) – Original circuit + * **final\_circuit** ([`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")) – Final circuit, whose qubits the original `observables` should be expanded to + + **Return type** + + [`PauliList`](/api/qiskit/qiskit.quantum_info.PauliList "(in Qiskit v1.2)") + + **Returns** + + New $N$-qubit observables which are compatible with the $N$-qubit `final_circuit` + + **Raises** + + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – `observables` and `original_circuit` have different number of qubits. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Qubit from `original_circuit` cannot be found in `final_circuit`. + + +### partition\_circuit\_qubits + + + Replace all nonlocal gates belonging to more than one partition with instances of [`TwoQubitQPDGate`](qpd#twoqubitqpdgate "qiskit_addon_cutting.qpd.TwoQubitQPDGate"). + + [`TwoQubitQPDGate`](qpd#twoqubitqpdgate "qiskit_addon_cutting.qpd.TwoQubitQPDGate")s belonging to a single partition will not be affected. + + **Parameters** + + * **circuit** ([`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")) – The circuit to partition + * **partition\_labels** ([`Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")\[[`Hashable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Hashable "(in Python v3.13)")]) – A sequence containing a partition label for each qubit in the input circuit. Nonlocal gates belonging to more than one partition will be replaced with [`TwoQubitQPDGate`](qpd#twoqubitqpdgate "qiskit_addon_cutting.qpd.TwoQubitQPDGate")s. + * **inplace** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – Flag denoting whether to copy the input circuit before acting on it + + **Return type** + + [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)") + + **Returns** + + The output circuit with each nonlocal gate spanning two partitions replaced by a [`TwoQubitQPDGate`](qpd#twoqubitqpdgate "qiskit_addon_cutting.qpd.TwoQubitQPDGate") + + **Raises** + + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The length of partition\_labels does not equal the number of qubits in the circuit. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Input circuit contains unsupported gate. + + +### partition\_problem + + + Separate an input circuit and observable(s). + + If `partition_labels` is provided, then qubits with matching partition labels will be grouped together, and non-local gates spanning more than one partition will be cut apart. The label `None` is treated specially: any qubit with that partition label must be unused in the circuit. + + If `partition_labels` is not provided, then it will be determined automatically from the connectivity of the circuit. This automatic determination ignores any [`TwoQubitQPDGate`](qpd#twoqubitqpdgate "qiskit_addon_cutting.qpd.TwoQubitQPDGate")s in the `circuit`, as these denote instructions that are explicitly destined for cutting. The resulting partition labels, in the automatic case, will be consecutive integers starting with 0. Qubits which are idle throughout the circuit will be assigned a partition label of `None`. + + All cut instructions will be replaced with [`SingleQubitQPDGate`](qpd#singlequbitqpdgate "qiskit_addon_cutting.qpd.SingleQubitQPDGate")s. + + If provided, `observables` will be separated along the boundaries specified by the partition labels. + + **Parameters** + + * **circuit** (QuantumCircuit) – The circuit to partition and separate + * **partition\_labels** (Sequence\[Hashable] | None) – A sequence of labels, such that each label corresponds to the circuit qubit with the same index + * **observables** (PauliList | None) – The observables to separate + + **Return type** + + PartitionedCuttingProblem + + **Returns** + + A tuple containing a dictionary mapping a partition label to a subcircuit, a list of QPD bases (one for each circuit gate or wire which was decomposed), and, optionally, a dictionary mapping a partition label to a list of Pauli observables. + + **Raises** + + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The number of partition labels does not equal the number of qubits in the circuit. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – An input observable acts on a different number of qubits than the input circuit. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – An input observable has a phase not equal to 1. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – A qubit with a label of `None` is not idle + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The input circuit should contain no classical bits or registers. + + +### cut\_gates + + + Transform specified gates into [`TwoQubitQPDGate`](qpd#twoqubitqpdgate "qiskit_addon_cutting.qpd.TwoQubitQPDGate")s. + + **Parameters** + + * **circuit** ([`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")) – The circuit containing gates to be decomposed + * **gate\_ids** ([`Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")\[[`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")]) – The indices of the gates to decompose + * **inplace** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – Flag denoting whether to copy the input circuit before acting on it + + **Return type** + + [`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)"), [`list`](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")\[[`QPDBasis`](qpd#qpdbasis "qiskit_addon_cutting.qpd.qpd_basis.QPDBasis")]] + + **Returns** + + A copy of the input circuit with the specified gates replaced with [`TwoQubitQPDGate`](qpd#twoqubitqpdgate "qiskit_addon_cutting.qpd.TwoQubitQPDGate")s and a list of [`QPDBasis`](qpd#qpdbasis "qiskit_addon_cutting.qpd.QPDBasis") instances – one for each decomposed gate. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The input circuit should contain no classical bits or registers. + + +### generate\_cutting\_experiments + + + Generate cutting subexperiments and their associated coefficients. + + If the input, `circuits`, is a `QuantumCircuit` instance, the output subexperiments will be contained within a 1D array, and `observables` is expected to be a `PauliList` instance. + + If the input circuit and observables are specified by dictionaries with partition labels as keys, the output subexperiments will be returned as a dictionary which maps each partition label to a 1D array containing the subexperiments associated with that partition. + + In both cases, the subexperiment lists are ordered as follows: + + > $[sample_{0}observable_{0}, \ldots, sample_{0}observable_{N-1}, sample_{1}observable_{0}, \ldots, sample_{M-1}observable_{N-1}]$ + + The coefficients will always be returned as a 1D array – one coefficient for each unique sample. + + **Parameters** + + * **circuits** (QuantumCircuit | dict\[Hashable, QuantumCircuit]) – The circuit(s) to partition and separate + * **observables** (PauliList | dict\[Hashable, PauliList]) – The observable(s) to evaluate for each unique sample + * **num\_samples** (int | float) – The number of samples to draw from the quasi-probability distribution. If set to infinity, the weights will be generated rigorously rather than by sampling from the distribution. + + **Return type** + + tuple\[list\[QuantumCircuit] | dict\[Hashable, list\[QuantumCircuit]], list\[tuple\[float, WeightType]]] + + **Returns** + + A tuple containing the cutting experiments and their associated coefficients. If the input circuits is a `QuantumCircuit` instance, the output subexperiments will be a sequence of circuits – one for every unique sample and observable. If the input circuits are represented as a dictionary keyed by partition labels, the output subexperiments will also be a dictionary keyed by partition labels and containing the subexperiments for each partition. The coefficients are always a sequence of length-2 tuples, where each tuple contains the coefficient and the `WeightType`. Each coefficient corresponds to one unique sample. + + **Raises** + + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – `num_samples` must be at least one. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – `circuits` and `observables` are incompatible types + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – `SingleQubitQPDGate` instances must have their cut ID appended to the gate label so they may be associated with other gates belonging to the same cut. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – `SingleQubitQPDGate` instances are not allowed in unseparated circuits. + + +### reconstruct\_expectation\_values + + + Reconstruct an expectation value from the results of the sub-experiments. + + **Parameters** + + * **results** (SamplerResult | PrimitiveResult | dict\[Hashable, SamplerResult | PrimitiveResult]) – + + The results from running the cutting subexperiments. If the cut circuit was not partitioned between qubits and run separately, this argument should be a [`SamplerResult`](/api/qiskit/qiskit.primitives.SamplerResult "(in Qiskit v1.2)") instance or a dictionary mapping a single partition to the results. If the circuit was partitioned and its pieces were run separately, this argument should be a dictionary mapping partition labels to the results from each partition’s subexperiments. + + The subexperiment results are expected to be ordered in the same way the subexperiments are ordered in the output of [`generate_cutting_experiments()`](#qiskit_addon_cutting.generate_cutting_experiments "qiskit_addon_cutting.generate_cutting_experiments") – one result for every sample and observable, as shown below. The Qiskit Sampler primitive will return the results in the same order the experiments are submitted, so users who do not use [`generate_cutting_experiments()`](#qiskit_addon_cutting.generate_cutting_experiments "qiskit_addon_cutting.generate_cutting_experiments") to generate their experiments should take care to order their subexperiments as follows before submitting them to the sampler primitive: + + $[sample_{0}observable_{0}, \ldots, sample_{0}observable_{N-1}, sample_{1}observable_{0}, \ldots, sample_{M-1}observable_{N-1}]$ + + * **coefficients** (Sequence\[tuple\[float, WeightType]]) – A sequence containing the coefficient associated with each unique subexperiment. Each element is a tuple containing the coefficient (a `float`) together with its [`WeightType`](qpd#weighttype "qiskit_addon_cutting.qpd.WeightType"), which denotes how the value was generated. The contribution from each subexperiment will be multiplied by its corresponding coefficient, and the resulting terms will be summed to obtain the reconstructed expectation value. + + * **observables** (PauliList | dict\[Hashable, PauliList]) – The observable(s) for which the expectation values will be calculated. This should be a [`PauliList`](/api/qiskit/qiskit.quantum_info.PauliList "(in Qiskit v1.2)") if `results` is a [`SamplerResult`](/api/qiskit/qiskit.primitives.SamplerResult "(in Qiskit v1.2)") instance. Otherwise, it should be a dictionary mapping partition labels to the observables associated with that partition. + + **Return type** + + list\[float] + + **Returns** + + A `list` of `float`s, such that each float is an expectation value corresponding to the input observable in the same position + + **Raises** + + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – `observables` and `results` are of incompatible types. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – An input observable has a phase not equal to 1. + + +### PartitionedCuttingProblem + + + The result of decomposing and separating a circuit and observable(s). + + Create new instance of PartitionedCuttingProblem(subcircuits, bases, subobservables) + + +## Automatic Cut Finding + +### find\_cuts + + + Find cut locations in a circuit, given optimization parameters and cutting constraints. + + **Parameters** + + * **circuit** ([`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")) – The circuit to cut. The input circuit may not contain gates acting on more than two qubits. + * **optimization** ([`OptimizationParameters`](#qiskit_addon_cutting.OptimizationParameters "qiskit_addon_cutting.automated_cut_finding.OptimizationParameters")) – Options for controlling optimizer behavior. Currently, the optimal cuts are chosen using Dijkstra’s best-first search algorithm. + * **constraints** ([`DeviceConstraints`](#qiskit_addon_cutting.DeviceConstraints "qiskit_addon_cutting.automated_cut_finding.DeviceConstraints")) – Constraints on how the circuit may be partitioned + + **Return type** + + [`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)"), [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)"), [`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")]] + + **Returns** + + A circuit containing [`BaseQPDGate`](qpd#baseqpdgate "qiskit_addon_cutting.qpd.BaseQPDGate") instances. The subcircuits resulting from cutting these gates will be runnable on the devices meeting the `constraints`. + + **A metadata dictionary:** + + * cuts: A list of length-2 tuples describing each cut in the output circuit. The tuples are formatted as `(cut_type: str, cut_id: int)`. The cut ID is the index of the cut gate or wire in the output circuit’s `data` field. + * sampling\_overhead: The sampling overhead incurred from cutting the specified gates and wires. + * minimum\_reached: A bool indicating whether or not the search conclusively found the minimum of cost function. `minimum_reached = False` could also mean that the cost returned was actually the lowest possible cost but that the search was not allowed to run long enough to prove that this was the case. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The input circuit contains a gate acting on more than 2 qubits. + + +### OptimizationParameters + + + Specify parameters that control the optimization. + + If either of the constraints specified by `max_backjumps` or `max_gamma` are exceeded, the search terminates but nevertheless returns the result of a greedy best first search, which gives an *upper-bound* on gamma. + + +### DeviceConstraints + + + Specify the constraints (qubits per subcircuit) that must be respected. + + diff --git a/docs/api/qiskit-addon-cutting/qpd-base-qpd-gate.mdx b/docs/api/qiskit-addon-cutting/qpd-base-qpd-gate.mdx deleted file mode 100644 index 1a1b84efd6f..00000000000 --- a/docs/api/qiskit-addon-cutting/qpd-base-qpd-gate.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: BaseQPDGate -description: API reference for qiskit_addon_cutting.qpd.BaseQPDGate -in_page_toc_min_heading_level: 1 -python_api_type: class -python_api_name: qiskit_addon_cutting.qpd.BaseQPDGate ---- - - - -# qiskit\_addon\_cutting.qpd.BaseQPDGate - - - Bases: [`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v1.2)") - - Base class for a gate to be decomposed using quasiprobability decomposition. - - Initialize the instruction, and assign member variables. - - **Parameters** - - * **name** (str) – Name of the QPD gate. - * **basis** (QPDBasis) – A probabilistic basis to which the gate should be decomposed - * **num\_qubits** (int) – The number of qubits on which the QPD gate acts - * **basis\_id** (int | None) – An index to the basis to which the gate should be decomposed. This index is to basis.maps. - * **label** (str | None) – An optional label for the gate - - ## Methods - - | | | - | ------------------------------------------------ | -------------------------------------------------------- | - | `__init__`(name, basis, num\_qubits, \*\[, ...]) | Initialize the instruction, and assign member variables. | - - ## Attributes - - | | | - | ---------- | ------------------------------------------- | - | `basis` | Quasiprobability decomposition basis. | - | `basis_id` | Index to basis used to decompose this gate. | - - diff --git a/docs/api/qiskit-addon-cutting/qpd-decompose-qpd-instructions.mdx b/docs/api/qiskit-addon-cutting/qpd-decompose-qpd-instructions.mdx deleted file mode 100644 index 691f8be1871..00000000000 --- a/docs/api/qiskit-addon-cutting/qpd-decompose-qpd-instructions.mdx +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: decompose_qpd_instructions -description: API reference for qiskit_addon_cutting.qpd.decompose_qpd_instructions -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_cutting.qpd.decompose_qpd_instructions ---- - - - -# qiskit\_addon\_cutting.qpd.decompose\_qpd\_instructions - - - Replace all QPD instructions in the circuit with local Qiskit operations and measurements. - - **Parameters** - - * **circuit** (QuantumCircuit) – The circuit containing QPD instructions - * **instruction\_ids** (Sequence\[Sequence\[int]]) – A 2D sequence, such that each inner sequence corresponds to indices of instructions comprising one decomposition in the circuit. The elements within a common sequence belong to a common decomposition and should be sampled together. - * **map\_ids** (Sequence\[int] | None) – Indices to a specific linear mapping to be applied to the decompositions in the circuit. If no map IDs are provided, the circuit will be decomposed randomly according to the decompositions’ joint probability distribution. - - **Return type** - - QuantumCircuit - - **Returns** - - Circuit which has had all its [`BaseQPDGate`](qpd-base-qpd-gate "qiskit_addon_cutting.qpd.BaseQPDGate") instances decomposed into local operations. - - The circuit will contain a new, final classical register to contain the QPD measurement outcomes (accessible at `retval.cregs[-1]`). - - **Raises** - - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – An index in `instruction_ids` corresponds to a gate which is not a [`BaseQPDGate`](qpd-base-qpd-gate "qiskit_addon_cutting.qpd.BaseQPDGate") instance. - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – A list within instruction\_ids is not length 1 or 2. - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The total number of indices in `instruction_ids` does not equal the number of [`BaseQPDGate`](qpd-base-qpd-gate "qiskit_addon_cutting.qpd.BaseQPDGate") instances in the circuit. - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Gates within the same decomposition hold different QPD bases. - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Length of `map_ids` does not equal the number of decompositions in the circuit. - - diff --git a/docs/api/qiskit-addon-cutting/qpd-generate-qpd-weights.mdx b/docs/api/qiskit-addon-cutting/qpd-generate-qpd-weights.mdx deleted file mode 100644 index e638bbe5a43..00000000000 --- a/docs/api/qiskit-addon-cutting/qpd-generate-qpd-weights.mdx +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: generate_qpd_weights -description: API reference for qiskit_addon_cutting.qpd.generate_qpd_weights -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_cutting.qpd.generate_qpd_weights ---- - - - -# qiskit\_addon\_cutting.qpd.generate\_qpd\_weights - - - Generate weights from the joint quasiprobability distribution. - - Each weight whose absolute value is above a threshold of `1 / num_samples` will be evaluated exactly. The remaining weights – those in the tail of the distribution – will then be sampled from, resulting in at most `num_samples` unique weights. - - **Parameters** - - * **qpd\_bases** ([`Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")\[[`QPDBasis`](qpd-qpd-basis "qiskit_addon_cutting.qpd.qpd_basis.QPDBasis")]) – The [`QPDBasis`](qpd-qpd-basis "qiskit_addon_cutting.qpd.QPDBasis") objects from which to generate weights - * **num\_samples** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – Controls the number of weights to generate - - **Return type** - - [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")\[[`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)"), [`...`](https://docs.python.org/3/library/constants.html#Ellipsis "(in Python v3.13)")], [`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)"), [`WeightType`](qpd-weight-type "qiskit_addon_cutting.qpd.weights.WeightType")]] - - **Returns** - - A mapping from a given decomposition to its weight. Keys are tuples of indices – one index per input [`QPDBasis`](qpd-qpd-basis "qiskit_addon_cutting.qpd.QPDBasis"). The indices correspond to a specific decomposition mapping in the basis. - - Values are tuples. The first element is a number corresponding to the weight of the contribution. The second element is the [`WeightType`](qpd-weight-type "qiskit_addon_cutting.qpd.WeightType"), either `EXACT` or `SAMPLED`. - - diff --git a/docs/api/qiskit-addon-cutting/qpd-qpd-basis.mdx b/docs/api/qiskit-addon-cutting/qpd-qpd-basis.mdx deleted file mode 100644 index 790c6bdfc77..00000000000 --- a/docs/api/qiskit-addon-cutting/qpd-qpd-basis.mdx +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: QPDBasis -description: API reference for qiskit_addon_cutting.qpd.QPDBasis -in_page_toc_min_heading_level: 1 -python_api_type: class -python_api_name: qiskit_addon_cutting.qpd.QPDBasis ---- - - - -# qiskit\_addon\_cutting.qpd.QPDBasis - - - Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.13)") - - Basis in which to decompose an operation. - - This class defines a basis in which a quantum operation will be decomposed. The ideal (noise-free) quantum operation will be decomposed into a quasiprobabilistic mixture of noisy circuits. - - Assign member variables. - - **Parameters** - - * **maps** ([`Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")\[[`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[`Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")\[[`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v1.2)")], [`...`](https://docs.python.org/3/library/constants.html#Ellipsis "(in Python v3.13)")]]) – A sequence of tuples describing the noisy operations probabilistically used to simulate an ideal quantum operation. - * **coeffs** ([`Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")\[[`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")]) – Coefficients for quasiprobability representation. Each coefficient can be any real number. - - **Returns** - - None - - ## Methods - - | | | - | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | - | `__init__`(maps, coeffs) | Assign member variables. | - | `from_instruction`(gate, /) | Generate a [`QPDBasis`](#qiskit_addon_cutting.qpd.QPDBasis "qiskit_addon_cutting.qpd.QPDBasis") object, given a supported operation. | - - ## Attributes - - | | | - | --------------- | -------------------------------------------------------- | - | `coeffs` | Quasiprobability decomposition coefficients. | - | `kappa` | Get the square root of the sampling overhead. | - | `maps` | Get mappings for each qubit in the decomposition. | - | `num_qubits` | Get number of qubits that this decomposition acts on. | - | `overhead` | Get the sampling overhead. | - | `probabilities` | Get the probabilities on which the maps will be sampled. | - - diff --git a/docs/api/qiskit-addon-cutting/qpd-qpdbasis-from-instruction.mdx b/docs/api/qiskit-addon-cutting/qpd-qpdbasis-from-instruction.mdx deleted file mode 100644 index f9ac7e5c3c4..00000000000 --- a/docs/api/qiskit-addon-cutting/qpd-qpdbasis-from-instruction.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: qpdbasis_from_instruction -description: API reference for qiskit_addon_cutting.qpd.qpdbasis_from_instruction -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_cutting.qpd.qpdbasis_from_instruction ---- - - - -# qiskit\_addon\_cutting.qpd.qpdbasis\_from\_instruction - - - Generate a [`QPDBasis`](qpd-qpd-basis "qiskit_addon_cutting.qpd.QPDBasis") object, given a supported operation. - - All two-qubit gates which implement the [`to_matrix()`](/api/qiskit/qiskit.circuit.Gate#to_matrix "(in Qiskit v1.2)") method are supported. This should include the vast majority of gates with no unbound parameters, but there are some special cases (see, e.g., [qiskit issue #10396](https://github.com/Qiskit/qiskit-terra/issues/10396)). - - The [`Move`](instructions-move "qiskit_addon_cutting.instructions.Move") operation, which can be used to specify a wire cut, is also supported. - - **Return type** - - [`QPDBasis`](qpd-qpd-basis "qiskit_addon_cutting.qpd.qpd_basis.QPDBasis") - - **Returns** - - The newly-instantiated [`QPDBasis`](qpd-qpd-basis "qiskit_addon_cutting.qpd.QPDBasis") object - - **Raises** - - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Instruction not supported. - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Cannot decompose instruction with unbound parameters. - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – `to_matrix` conversion of two-qubit gate failed. - - diff --git a/docs/api/qiskit-addon-cutting/qpd-single-qubit-qpd-gate.mdx b/docs/api/qiskit-addon-cutting/qpd-single-qubit-qpd-gate.mdx deleted file mode 100644 index f0533565d89..00000000000 --- a/docs/api/qiskit-addon-cutting/qpd-single-qubit-qpd-gate.mdx +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: SingleQubitQPDGate -description: API reference for qiskit_addon_cutting.qpd.SingleQubitQPDGate -in_page_toc_min_heading_level: 1 -python_api_type: class -python_api_name: qiskit_addon_cutting.qpd.SingleQubitQPDGate ---- - - - -# qiskit\_addon\_cutting.qpd.SingleQubitQPDGate - - - Bases: [`BaseQPDGate`](qpd-base-qpd-gate "qiskit_addon_cutting.qpd.instructions.qpd_gate.BaseQPDGate") - - Single qubit gate to be decomposed using quasiprobability decomposition. - - This gate could be part of a larger decomposition on many qubits, or it could be a standalone single gate decomposition. - - Initialize the single qubit QPD gate, and assign member variables. - - **Parameters** - - **qubit\_id** (int) – This gate’s relative index to the decomposition which it belongs. Single qubit QPDGates should have qubit\_id 0 if they describe a local decomposition, such as a wire cut. - - **Raises** - - [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – qubit\_id is out of range - - ## Methods - - | | | - | ----------------------------------------------------- | ------------------------------------------------------------------ | - | `__init__`(basis, qubit\_id, \*\[, basis\_id, label]) | Initialize the single qubit QPD gate, and assign member variables. | - - ## Attributes - - | | | - | ---------- | --------------------------------------------------------------- | - | `qubit_id` | Relative qubit index of this gate in the overall decomposition. | - - diff --git a/docs/api/qiskit-addon-cutting/qpd-two-qubit-qpd-gate.mdx b/docs/api/qiskit-addon-cutting/qpd-two-qubit-qpd-gate.mdx deleted file mode 100644 index b81e1afa8b5..00000000000 --- a/docs/api/qiskit-addon-cutting/qpd-two-qubit-qpd-gate.mdx +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: TwoQubitQPDGate -description: API reference for qiskit_addon_cutting.qpd.TwoQubitQPDGate -in_page_toc_min_heading_level: 1 -python_api_type: class -python_api_name: qiskit_addon_cutting.qpd.TwoQubitQPDGate ---- - - - -# qiskit\_addon\_cutting.qpd.TwoQubitQPDGate - - - Bases: [`BaseQPDGate`](qpd-base-qpd-gate "qiskit_addon_cutting.qpd.instructions.qpd_gate.BaseQPDGate") - - Two qubit gate to be decomposed using quasiprobability decomposition. - - Initialize the two qubit QPD gate. - - **Raises** - - [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The [`QPDBasis`](qpd-qpd-basis "qiskit_addon_cutting.qpd.QPDBasis") acts on a number of qubits not equal to 2. - - ## Methods - - | | | - | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | `__init__`(basis, \*\[, basis\_id, label]) | Initialize the two qubit QPD gate. | - | `from_instruction`(instruction, /) | Create a [`TwoQubitQPDGate`](#qiskit_addon_cutting.qpd.TwoQubitQPDGate "qiskit_addon_cutting.qpd.TwoQubitQPDGate") which represents a cut version of the given `instruction`. | - - ## Attributes - - | | - | - | - - diff --git a/docs/api/qiskit-addon-cutting/qpd-weight-type.mdx b/docs/api/qiskit-addon-cutting/qpd-weight-type.mdx deleted file mode 100644 index d7e1b8ce1a3..00000000000 --- a/docs/api/qiskit-addon-cutting/qpd-weight-type.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: WeightType -description: API reference for qiskit_addon_cutting.qpd.WeightType -in_page_toc_min_heading_level: 1 -python_api_type: class -python_api_name: qiskit_addon_cutting.qpd.WeightType ---- - - - -# qiskit\_addon\_cutting.qpd.WeightType - - - Bases: [`Enum`](https://docs.python.org/3/library/enum.html#enum.Enum "(in Python v3.13)") - - Type of weight associated with a QPD sample. - - ## Attributes - - | | | - | --------- | ------------------------------------------------------------ | - | `EXACT` | A weight given in proportion to its exact weight | - | `SAMPLED` | A weight that was determined through some sampling procedure | - - diff --git a/docs/api/qiskit-addon-cutting/qpd.mdx b/docs/api/qiskit-addon-cutting/qpd.mdx new file mode 100644 index 00000000000..78cd4c182c8 --- /dev/null +++ b/docs/api/qiskit-addon-cutting/qpd.mdx @@ -0,0 +1,176 @@ +--- +title: qpd +description: API reference for qiskit_addon_cutting.qpd +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_addon_cutting.qpd +--- + + + + + +# Quasi-Probability Decomposition (QPD) + +`qiskit_addon_cutting.qpd` + +Main quasiprobability decomposition functionality. + +### QPDBasis + + + Basis in which to decompose an operation. + + This class defines a basis in which a quantum operation will be decomposed. The ideal (noise-free) quantum operation will be decomposed into a quasiprobabilistic mixture of noisy circuits. + + Assign member variables. + + **Parameters** + + * **maps** ([`Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")\[[`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[`Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")\[[`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v1.2)")], [`...`](https://docs.python.org/3/library/constants.html#Ellipsis "(in Python v3.13)")]]) – A sequence of tuples describing the noisy operations probabilistically used to simulate an ideal quantum operation. + * **coeffs** ([`Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")\[[`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")]) – Coefficients for quasiprobability representation. Each coefficient can be any real number. + + **Returns** + + None + + +### BaseQPDGate + + + Base class for a gate to be decomposed using quasiprobability decomposition. + + Initialize the instruction, and assign member variables. + + **Parameters** + + * **name** (str) – Name of the QPD gate. + * **basis** (QPDBasis) – A `QPDBasis` to which the gate should be decomposed + * **num\_qubits** (int) – The number of qubits on which the QPD gate acts + * **basis\_id** (int | None) – An index to the basis to which the gate should be decomposed. This index is to `basis.maps`. + * **label** (str | None) – An optional label for the gate + + +### SingleQubitQPDGate + + + Single qubit gate to be decomposed using quasiprobability decomposition. + + This gate could be part of a larger decomposition on many qubits, or it could be a standalone single gate decomposition. + + Initialize the single qubit QPD gate, and assign member variables. + + **Parameters** + + * **basis** (QPDBasis) – A `QPDBasis` to which the gate should be decomposed + * **qubit\_id** (int) – This gate’s relative index to the decomposition which it belongs. Single qubit QPDGates should have qubit\_id 0 if they describe a local decomposition, such as a wire cut. + * **basis\_id** (int | None) – An index to the basis to which the gate should be decomposed. This index is to `basis.maps`. + * **label** (str | None) – An optional label for the gate + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – qubit\_id is out of range + + +### TwoQubitQPDGate + + + Two qubit gate to be decomposed using quasiprobability decomposition. + + Initialize the two qubit QPD gate. + + **Parameters** + + * **basis** (QPDBasis) – A `QPDBasis` to which the gate should be decomposed + * **basis\_id** (int | None) – An index to the basis to which the gate should be decomposed. This index is to `basis.maps`. + * **label** (str | None) – An optional label for the gate + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The [`QPDBasis`](#qiskit_addon_cutting.qpd.QPDBasis "qiskit_addon_cutting.qpd.QPDBasis") acts on a number of qubits not equal to 2. + + +### WeightType + + + Type of weight associated with a QPD sample. + + +### generate\_qpd\_weights + + + Generate weights from the joint quasiprobability distribution. + + Each weight whose absolute value is above a threshold of `1 / num_samples` will be evaluated exactly. The remaining weights – those in the tail of the distribution – will then be sampled from, resulting in at most `num_samples` unique weights. + + **Parameters** + + * **qpd\_bases** ([`Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")\[[`QPDBasis`](#qiskit_addon_cutting.qpd.QPDBasis "qiskit_addon_cutting.qpd.qpd_basis.QPDBasis")]) – The [`QPDBasis`](#qiskit_addon_cutting.qpd.QPDBasis "qiskit_addon_cutting.qpd.QPDBasis") objects from which to generate weights + * **num\_samples** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – Controls the number of weights to generate + + **Return type** + + [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")\[[`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)"), [`...`](https://docs.python.org/3/library/constants.html#Ellipsis "(in Python v3.13)")], [`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)"), [`WeightType`](#qiskit_addon_cutting.qpd.WeightType "qiskit_addon_cutting.qpd.weights.WeightType")]] + + **Returns** + + A mapping from a given decomposition to its weight. Keys are tuples of indices – one index per input [`QPDBasis`](#qiskit_addon_cutting.qpd.QPDBasis "qiskit_addon_cutting.qpd.QPDBasis"). The indices correspond to a specific decomposition mapping in the basis. + + Values are tuples. The first element is a number corresponding to the weight of the contribution. The second element is the [`WeightType`](#qiskit_addon_cutting.qpd.WeightType "qiskit_addon_cutting.qpd.WeightType"), either `EXACT` or `SAMPLED`. + + +### decompose\_qpd\_instructions + + + Replace all QPD instructions in the circuit with local Qiskit operations and measurements. + + **Parameters** + + * **circuit** (QuantumCircuit) – The circuit containing QPD instructions + * **instruction\_ids** (Sequence\[Sequence\[int]]) – A 2D sequence, such that each inner sequence corresponds to indices of instructions comprising one decomposition in the circuit. The elements within a common sequence belong to a common decomposition and should be sampled together. + * **map\_ids** (Sequence\[int] | None) – Indices to a specific linear mapping to be applied to the decompositions in the circuit. If no map IDs are provided, the circuit will be decomposed randomly according to the decompositions’ joint probability distribution. + * **inplace** (bool) – If `True`, the `circuit` will be modified in place. + + **Return type** + + QuantumCircuit + + **Returns** + + Circuit which has had all its [`BaseQPDGate`](#qiskit_addon_cutting.qpd.BaseQPDGate "qiskit_addon_cutting.qpd.BaseQPDGate") instances decomposed into local operations. + + The circuit will contain a new, final classical register to contain the QPD measurement outcomes (accessible at `retval.cregs[-1]`). + + **Raises** + + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – An index in `instruction_ids` corresponds to a gate which is not a [`BaseQPDGate`](#qiskit_addon_cutting.qpd.BaseQPDGate "qiskit_addon_cutting.qpd.BaseQPDGate") instance. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – A list within instruction\_ids is not length 1 or 2. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The total number of indices in `instruction_ids` does not equal the number of [`BaseQPDGate`](#qiskit_addon_cutting.qpd.BaseQPDGate "qiskit_addon_cutting.qpd.BaseQPDGate") instances in the circuit. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Gates within the same decomposition hold different QPD bases. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Length of `map_ids` does not equal the number of decompositions in the circuit. + + +### qpdbasis\_from\_instruction + + + Generate a [`QPDBasis`](#qiskit_addon_cutting.qpd.QPDBasis "qiskit_addon_cutting.qpd.QPDBasis") object, given a supported operation. + + All two-qubit gates which implement the [`to_matrix()`](/api/qiskit/qiskit.circuit.Gate#to_matrix "(in Qiskit v1.2)") method are supported. This should include the vast majority of gates with no unbound parameters, but there are some special cases (see, e.g., [qiskit issue #10396](https://github.com/Qiskit/qiskit-terra/issues/10396)). + + The [`Move`](instructions#move "qiskit_addon_cutting.instructions.Move") operation, which can be used to specify a wire cut, is also supported. + + **Return type** + + [`QPDBasis`](#qiskit_addon_cutting.qpd.QPDBasis "qiskit_addon_cutting.qpd.qpd_basis.QPDBasis") + + **Returns** + + The newly-instantiated [`QPDBasis`](#qiskit_addon_cutting.qpd.QPDBasis "qiskit_addon_cutting.qpd.QPDBasis") object + + **Raises** + + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Instruction not supported. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Cannot decompose instruction with unbound parameters. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – `to_matrix` conversion of two-qubit gate failed. + + diff --git a/docs/api/qiskit-addon-cutting/reconstruct-expectation-values.mdx b/docs/api/qiskit-addon-cutting/reconstruct-expectation-values.mdx deleted file mode 100644 index 8d8d356e95b..00000000000 --- a/docs/api/qiskit-addon-cutting/reconstruct-expectation-values.mdx +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: reconstruct_expectation_values -description: API reference for qiskit_addon_cutting.reconstruct_expectation_values -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_cutting.reconstruct_expectation_values ---- - - - -# qiskit\_addon\_cutting.reconstruct\_expectation\_values - - - Reconstruct an expectation value from the results of the sub-experiments. - - **Parameters** - - * **results** (SamplerResult | PrimitiveResult | dict\[Hashable, SamplerResult | PrimitiveResult]) – - - The results from running the cutting subexperiments. If the cut circuit was not partitioned between qubits and run separately, this argument should be a [`SamplerResult`](/api/qiskit/qiskit.primitives.SamplerResult "(in Qiskit v1.2)") instance or a dictionary mapping a single partition to the results. If the circuit was partitioned and its pieces were run separately, this argument should be a dictionary mapping partition labels to the results from each partition’s subexperiments. - - The subexperiment results are expected to be ordered in the same way the subexperiments are ordered in the output of [`generate_cutting_experiments()`](generate-cutting-experiments "qiskit_addon_cutting.generate_cutting_experiments") – one result for every sample and observable, as shown below. The Qiskit Sampler primitive will return the results in the same order the experiments are submitted, so users who do not use [`generate_cutting_experiments()`](generate-cutting-experiments "qiskit_addon_cutting.generate_cutting_experiments") to generate their experiments should take care to order their subexperiments as follows before submitting them to the sampler primitive: - - $[sample_{0}observable_{0}, \ldots, sample_{0}observable_{N-1}, sample_{1}observable_{0}, \ldots, sample_{M-1}observable_{N-1}]$ - - * **coefficients** (Sequence\[tuple\[float, WeightType]]) – A sequence containing the coefficient associated with each unique subexperiment. Each element is a tuple containing the coefficient (a `float`) together with its [`WeightType`](qpd-weight-type "qiskit_addon_cutting.qpd.WeightType"), which denotes how the value was generated. The contribution from each subexperiment will be multiplied by its corresponding coefficient, and the resulting terms will be summed to obtain the reconstructed expectation value. - - * **observables** (PauliList | dict\[Hashable, PauliList]) – The observable(s) for which the expectation values will be calculated. This should be a [`PauliList`](/api/qiskit/qiskit.quantum_info.PauliList "(in Qiskit v1.2)") if `results` is a [`SamplerResult`](/api/qiskit/qiskit.primitives.SamplerResult "(in Qiskit v1.2)") instance. Otherwise, it should be a dictionary mapping partition labels to the observables associated with that partition. - - **Return type** - - list\[float] - - **Returns** - - A `list` of `float`s, such that each float is an expectation value corresponding to the input observable in the same position - - **Raises** - - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – `observables` and `results` are of incompatible types. - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – An input observable has a phase not equal to 1. - - diff --git a/docs/api/qiskit-addon-cutting/release-notes.mdx b/docs/api/qiskit-addon-cutting/release-notes.mdx index b089729d234..36ccaf49666 100644 --- a/docs/api/qiskit-addon-cutting/release-notes.mdx +++ b/docs/api/qiskit-addon-cutting/release-notes.mdx @@ -26,9 +26,9 @@ The most notable change in this release is that the package has been renamed to ### New Features -* A new `minimum_reached` field has been added to the metadata outputted by `circuit_knitting.cutting.find_cuts()` to check if the cut-finder found a cut scheme that minimized the sampling overhead. Note that the search algorithm employed by the cut-finder is *guaranteed* to find the optimal solution, that is, the solution with the minimum sampling overhead, provided it is allowed to run long enough. The user is free to time-restrict the search by passing in suitable values for `max_backjumps` and/or `max_gamma` to [`OptimizationParameters`](optimization-parameters "qiskit_addon_cutting.OptimizationParameters"). If the search is terminated prematurely in this way, the metadata may indicate that the minimum was not reached, even though the returned solution was actually the optimal solution. This would mean that the search that was performed was not exhaustive enough to prove that the returned solution was optimal. +* A new `minimum_reached` field has been added to the metadata outputted by `circuit_knitting.cutting.find_cuts()` to check if the cut-finder found a cut scheme that minimized the sampling overhead. Note that the search algorithm employed by the cut-finder is *guaranteed* to find the optimal solution, that is, the solution with the minimum sampling overhead, provided it is allowed to run long enough. The user is free to time-restrict the search by passing in suitable values for `max_backjumps` and/or `max_gamma` to [`OptimizationParameters`](qiskit-addon-cutting#optimizationparameters "qiskit_addon_cutting.OptimizationParameters"). If the search is terminated prematurely in this way, the metadata may indicate that the minimum was not reached, even though the returned solution was actually the optimal solution. This would mean that the search that was performed was not exhaustive enough to prove that the returned solution was optimal. -* When specifying instances of [`OptimizationParameters`](optimization-parameters "qiskit_addon_cutting.OptimizationParameters") that are inputted to `circuit_knitting.cutting.find_cuts()`, the user can now control whether the cut-finder looks only for gate cuts, only for wire cuts, or both, by setting the bools `gate_lo` and `wire_lo` appropriately. The default value of both of these is set to `True` and so the default search considers the possibility of both gate and wire cuts. +* When specifying instances of [`OptimizationParameters`](qiskit-addon-cutting#optimizationparameters "qiskit_addon_cutting.OptimizationParameters") that are inputted to `circuit_knitting.cutting.find_cuts()`, the user can now control whether the cut-finder looks only for gate cuts, only for wire cuts, or both, by setting the bools `gate_lo` and `wire_lo` appropriately. The default value of both of these is set to `True` and so the default search considers the possibility of both gate and wire cuts. @@ -40,7 +40,7 @@ The most notable change in this release is that the package has been renamed to * The `CutQC` subpackage has been removed, along with its two associated utility modules, `circuit_knitting.utils.metrics` and `circuit_knitting.utils.conversion`. Users are now encouraged to use the automatic cut-finding and gate/wire cutting from the `circuit_knitting.cutting` package. -* The behavior of [`separate_circuit()`](utils-transforms-separate-circuit "qiskit_addon_cutting.utils.transforms.separate_circuit") and [`partition_problem()`](partition-problem "qiskit_addon_cutting.partition_problem") have changed so that idle qubits are discarded by default. Previously, each idle qubit was placed in its own subcircuit if `partition_labels` was not provided. +* The behavior of [`separate_circuit()`](utils-transforms#separate_circuit "qiskit_addon_cutting.utils.transforms.separate_circuit") and [`partition_problem()`](qiskit-addon-cutting#partition_problem "qiskit_addon_cutting.partition_problem") have changed so that idle qubits are discarded by default. Previously, each idle qubit was placed in its own subcircuit if `partition_labels` was not provided. @@ -66,7 +66,7 @@ The 0.7.1 release provides a workaround to ensure that the experiments generated ### Other Notes -* The [`generate_cutting_experiments()`](generate-cutting-experiments "qiskit_addon_cutting.generate_cutting_experiments") function has been optimized for faster execution. +* The [`generate_cutting_experiments()`](qiskit-addon-cutting#generate_cutting_experiments "qiskit_addon_cutting.generate_cutting_experiments") function has been optimized for faster execution. @@ -106,7 +106,7 @@ The 0.7 release introduces an automated cut finding code for the new circuit cut ### Deprecation Notes -* The `circuit_knitting.cutting.cutqc` package is deprecated and will be removed no sooner than Circuit Knitting Toolbox 0.8.0. The wire cutting functionality in the `circuit_knitting.cutting` package is what will be maintained going forward. Additionally, there is a new automated gate and wire cut-finding functionality in the `circuit_knitting.cutting.automated_cut_finding` module. A [tutorial](https://github.com/Qiskit-Extensions/circuit-knitting-toolbox/blob/main/docs/circuit_cutting/tutorials/04_automatic_cut_finding.ipynb) has been added to demonstrate automated cut-finding. +* The `circuit_knitting.cutting.cutqc` package is deprecated and will be removed no sooner than Circuit Knitting Toolbox 0.8.0. The wire cutting functionality in the `circuit_knitting.cutting` package is what will be maintained going forward. Additionally, there is a new automated gate and wire cut-finding functionality in the `circuit_knitting.cutting.automated_cut_finding` module. A [tutorial](https://github.com/Qiskit/qiskit-addon-cutting/blob/stable/0.7/docs/circuit_cutting/tutorials/04_automatic_cut_finding.ipynb) has been added to demonstrate automated cut-finding. @@ -136,15 +136,15 @@ The 0.7 release introduces an automated cut finding code for the new circuit cut * Removed the `circuit_knitting_toolbox` import path. Users should now import from `circuit_knitting` instead. -* Removed the `circuit_knitting.cutting.decompose_gates` function, which has been deprecated since the 0.3 release. [`cut_gates()`](cut-gates "qiskit_addon_cutting.cut_gates") should be used instead. +* Removed the `circuit_knitting.cutting.decompose_gates` function, which has been deprecated since the 0.3 release. [`cut_gates()`](qiskit-addon-cutting#cut_gates "qiskit_addon_cutting.cut_gates") should be used instead. * Removed the `circuit_knitting.cutting.cutting_evaluation` module, which has been deprecated since the 0.4 release. Users should first call `circuit_knitting.cutting.generate_cutting_experiments()` to generate the subexperiment circuits and then submit these circuits directly to the desired Sampler(s). -* Removed the `circuit_knitting.cutting.qpd.generate_qpd_samples` function, which has been deprecated since the 0.3 release. [`generate_qpd_weights()`](qpd-generate-qpd-weights "qiskit_addon_cutting.qpd.generate_qpd_weights") should be used instead. +* Removed the `circuit_knitting.cutting.qpd.generate_qpd_samples` function, which has been deprecated since the 0.3 release. [`generate_qpd_weights()`](qpd#generate_qpd_weights "qiskit_addon_cutting.qpd.generate_qpd_weights") should be used instead. -* Removed the `circuit_knitting.cutting.qpd.qpdbasis_from_gate` function, which has been deprecated since the 0.3 release. [`qpdbasis_from_instruction()`](qpd-qpdbasis-from-instruction "qiskit_addon_cutting.qpd.qpdbasis_from_instruction") should be used instead. +* Removed the `circuit_knitting.cutting.qpd.qpdbasis_from_gate` function, which has been deprecated since the 0.3 release. [`qpdbasis_from_instruction()`](qpd#qpdbasis_from_instruction "qiskit_addon_cutting.qpd.qpdbasis_from_instruction") should be used instead. -* The [`generate_cutting_experiments()`](generate-cutting-experiments "qiskit_addon_cutting.generate_cutting_experiments") function now performs some optimizations on the generated circuits before returning them to the user. In particular, it performs the [`RemoveResetInZeroState`](/api/qiskit/qiskit.transpiler.passes.RemoveResetInZeroState "(in Qiskit v1.2)"), [`RemoveFinalReset`](utils-transpiler-passes-remove-final-reset "qiskit_addon_cutting.utils.transpiler_passes.RemoveFinalReset"), and [`ConsolidateResets`](utils-transpiler-passes-consolidate-resets "qiskit_addon_cutting.utils.transpiler_passes.ConsolidateResets") passes, so that circuits with cut wires and no re-used qubits are transformed into subexperiments that contain no `Reset`s. This allows such circuits to work on a greater variety of hardware backends. +* The [`generate_cutting_experiments()`](qiskit-addon-cutting#generate_cutting_experiments "qiskit_addon_cutting.generate_cutting_experiments") function now performs some optimizations on the generated circuits before returning them to the user. In particular, it performs the [`RemoveResetInZeroState`](/api/qiskit/qiskit.transpiler.passes.RemoveResetInZeroState "(in Qiskit v1.2)"), [`RemoveFinalReset`](utils-transpiler-passes#removefinalreset "qiskit_addon_cutting.utils.transpiler_passes.RemoveFinalReset"), and [`ConsolidateResets`](utils-transpiler-passes#consolidateresets "qiskit_addon_cutting.utils.transpiler_passes.ConsolidateResets") passes, so that circuits with cut wires and no re-used qubits are transformed into subexperiments that contain no `Reset`s. This allows such circuits to work on a greater variety of hardware backends. @@ -152,7 +152,7 @@ The 0.7 release introduces an automated cut finding code for the new circuit cut ### Bug Fixes -* It is now possible to serialize [`SingleQubitQPDGate`](qpd-single-qubit-qpd-gate "qiskit_addon_cutting.qpd.SingleQubitQPDGate")s using [`qpy`](/api/qiskit/qpy#module-qiskit.qpy "(in Qiskit v1.2)"), but some other issues with serialization and deserialization still remain. See issue [#455](https://github.com/Qiskit-Extensions/circuit-knitting-toolbox/issues/445) for details. +* It is now possible to serialize [`SingleQubitQPDGate`](qpd#singlequbitqpdgate "qiskit_addon_cutting.qpd.SingleQubitQPDGate")s using [`qpy`](/api/qiskit/qpy#module-qiskit.qpy "(in Qiskit v1.2)"), but some other issues with serialization and deserialization still remain. See issue [#455](https://github.com/Qiskit-Extensions/circuit-knitting-toolbox/issues/445) for details. @@ -208,7 +208,7 @@ The primary purpose of this release is to swap the order of the classical regist ### Prelude -The primary goal of this release is to modify the circuit cutting workflow to enable direct use of the Sampler primitive. Previously, the Sampler was called in `execute_experiments()`, a function which is now deprecated in favor of [`generate_cutting_experiments()`](generate-cutting-experiments "qiskit_addon_cutting.generate_cutting_experiments"). +The primary goal of this release is to modify the circuit cutting workflow to enable direct use of the Sampler primitive. Previously, the Sampler was called in `execute_experiments()`, a function which is now deprecated in favor of [`generate_cutting_experiments()`](qiskit-addon-cutting#generate_cutting_experiments "qiskit_addon_cutting.generate_cutting_experiments"). @@ -216,7 +216,7 @@ The primary goal of this release is to modify the circuit cutting workflow to en ### New Features -* Added a module, `circuit_knitting.cutting.cutting_experiments`, which is intended to hold functions used for generating the quantum experiments needed for circuit cutting. This module will initially hold one function, [`generate_cutting_experiments()`](generate-cutting-experiments "qiskit_addon_cutting.generate_cutting_experiments"), which can be used to generate quantum experiments, given an input circuit containing [`BaseQPDGate`](qpd-base-qpd-gate "qiskit_addon_cutting.qpd.BaseQPDGate") instances, some observables, and a number of times the joint quasi-probability distribution for the cuts should be sampled. +* Added a module, `circuit_knitting.cutting.cutting_experiments`, which is intended to hold functions used for generating the quantum experiments needed for circuit cutting. This module will initially hold one function, [`generate_cutting_experiments()`](qiskit-addon-cutting#generate_cutting_experiments "qiskit_addon_cutting.generate_cutting_experiments"), which can be used to generate quantum experiments, given an input circuit containing [`BaseQPDGate`](qpd#baseqpdgate "qiskit_addon_cutting.qpd.BaseQPDGate") instances, some observables, and a number of times the joint quasi-probability distribution for the cuts should be sampled. @@ -226,9 +226,9 @@ The primary goal of this release is to modify the circuit cutting workflow to en * The `circuit-knitting-toolbox` Python package now depends on `qiskit` rather than `qiskit-terra`. This should have no user-visible effects, but it is something to keep in mind if one sees dependency errors when upgrading CKT. -* The `execute_experiments()` function now returns a [`SamplerResult`](/api/qiskit/qiskit.primitives.SamplerResult "(in Qiskit v1.2)") instance for each circuit partition, rather than the 3D list of quasi-distributions returned previously. The quasi-distribution for each subexperiment can be accessed via the `quasi_dists` field of [`SamplerResult`](/api/qiskit/qiskit.primitives.SamplerResult "(in Qiskit v1.2)"). The number of QPD bits contained in each subexperiment will be included in the `num_qpd_bits` field of the `metadata` dictionary for each experiment result. The output of this function is still valid as input to [`reconstruct_expectation_values()`](reconstruct-expectation-values "qiskit_addon_cutting.reconstruct_expectation_values"). +* The `execute_experiments()` function now returns a [`SamplerResult`](/api/qiskit/qiskit.primitives.SamplerResult "(in Qiskit v1.2)") instance for each circuit partition, rather than the 3D list of quasi-distributions returned previously. The quasi-distribution for each subexperiment can be accessed via the `quasi_dists` field of [`SamplerResult`](/api/qiskit/qiskit.primitives.SamplerResult "(in Qiskit v1.2)"). The number of QPD bits contained in each subexperiment will be included in the `num_qpd_bits` field of the `metadata` dictionary for each experiment result. The output of this function is still valid as input to [`reconstruct_expectation_values()`](qiskit-addon-cutting#reconstruct_expectation_values "qiskit_addon_cutting.reconstruct_expectation_values"). -* [`reconstruct_expectation_values()`](reconstruct-expectation-values "qiskit_addon_cutting.reconstruct_expectation_values") now takes, as its first argument, a [`SamplerResult`](/api/qiskit/qiskit.primitives.SamplerResult "(in Qiskit v1.2)") instance or a dictionary mapping partition labels to [`SamplerResult`](/api/qiskit/qiskit.primitives.SamplerResult "(in Qiskit v1.2)") instances. This new `results` argument replaces the old `quasi_dists` argument. The [`SamplerResult`](/api/qiskit/qiskit.primitives.SamplerResult "(in Qiskit v1.2)") instances are expected to contain the number of QPD bits used in each circuit input to the Sampler. This should be specified in the `num_qpd_bits` field of the experiment result metadata. +* [`reconstruct_expectation_values()`](qiskit-addon-cutting#reconstruct_expectation_values "qiskit_addon_cutting.reconstruct_expectation_values") now takes, as its first argument, a [`SamplerResult`](/api/qiskit/qiskit.primitives.SamplerResult "(in Qiskit v1.2)") instance or a dictionary mapping partition labels to [`SamplerResult`](/api/qiskit/qiskit.primitives.SamplerResult "(in Qiskit v1.2)") instances. This new `results` argument replaces the old `quasi_dists` argument. The [`SamplerResult`](/api/qiskit/qiskit.primitives.SamplerResult "(in Qiskit v1.2)") instances are expected to contain the number of QPD bits used in each circuit input to the Sampler. This should be specified in the `num_qpd_bits` field of the experiment result metadata. @@ -236,7 +236,7 @@ The primary goal of this release is to modify the circuit cutting workflow to en ### Deprecation Notes -* The `execute_experiments()` function has been deprecated. Going forward, users should first call [`generate_cutting_experiments()`](generate-cutting-experiments "qiskit_addon_cutting.generate_cutting_experiments") to generate the subexperiment circuits and then submit these circuits directly to the desired Sampler(s). The [tutorials](https://qiskit.github.io/qiskit-addon-cutting/tutorials/index.html) have been updated with this new workflow. +* The `execute_experiments()` function has been deprecated. Going forward, users should first call [`generate_cutting_experiments()`](qiskit-addon-cutting#generate_cutting_experiments "qiskit_addon_cutting.generate_cutting_experiments") to generate the subexperiment circuits and then submit these circuits directly to the desired Sampler(s). The [tutorials](https://qiskit.github.io/qiskit-addon-cutting/tutorials/index.html) have been updated with this new workflow. @@ -273,7 +273,7 @@ The 0.3.0 release introduces significant new features while maintaining backward * [`iSwapGate`](/api/qiskit/qiskit.circuit.library.iSwapGate "(in Qiskit v1.2)") * [`DCXGate`](/api/qiskit/qiskit.circuit.library.DCXGate "(in Qiskit v1.2)") -* [`partition_problem()`](partition-problem "qiskit_addon_cutting.partition_problem") now works even if `partition_labels` is not explicitly provided. In this case, the labels are determined automatically from the connectivity of the input circuit. For the sake of determining connectivity, [`TwoQubitQPDGate`](qpd-two-qubit-qpd-gate "qiskit_addon_cutting.qpd.TwoQubitQPDGate")s are ignored, as these instructions are already marked for cutting. To support this workflow, this release also introduces a new method, `TwoQubitQPDGate.from_instruction()`, which allows one to create a [`TwoQubitQPDGate`](qpd-two-qubit-qpd-gate "qiskit_addon_cutting.qpd.TwoQubitQPDGate") that wraps a given instruction. +* [`partition_problem()`](qiskit-addon-cutting#partition_problem "qiskit_addon_cutting.partition_problem") now works even if `partition_labels` is not explicitly provided. In this case, the labels are determined automatically from the connectivity of the input circuit. For the sake of determining connectivity, [`TwoQubitQPDGate`](qpd#twoqubitqpdgate "qiskit_addon_cutting.qpd.TwoQubitQPDGate")s are ignored, as these instructions are already marked for cutting. To support this workflow, this release also introduces a new method, `TwoQubitQPDGate.from_instruction()`, which allows one to create a [`TwoQubitQPDGate`](qpd#twoqubitqpdgate "qiskit_addon_cutting.qpd.TwoQubitQPDGate") that wraps a given instruction. * Dynamic Definition code has been added to the `cutqc` module. See pull request [#285](https://github.com/Qiskit-Extensions/circuit-knitting-toolbox/pull/285) for details. @@ -295,7 +295,7 @@ The 0.3.0 release introduces significant new features while maintaining backward * The dependency on the `qiskit.opflow` module has been removed from entanglement forging. With this change, Qiskit Nature 0.6.0 is now required. However, Qiskit Nature 0.6.0 is incompatible with Quantum Serverless, so users that wish to use entanglement forging with Quantum Serverless must remain on version 0.2 of the Circuit Knitting Toolbox until [issue #108](https://github.com/Qiskit-Extensions/circuit-knitting-toolbox/issues/108) is resolved. -* [`BaseQPDGate`](qpd-base-qpd-gate "qiskit_addon_cutting.qpd.BaseQPDGate") instances in subcircuits returned from [`partition_circuit_qubits()`](partition-circuit-qubits "qiskit_addon_cutting.partition_circuit_qubits") and [`partition_problem()`](partition-problem "qiskit_addon_cutting.partition_problem") will now have labels prefixed with “cut”, rather than “qpd”. +* [`BaseQPDGate`](qpd#baseqpdgate "qiskit_addon_cutting.qpd.BaseQPDGate") instances in subcircuits returned from [`partition_circuit_qubits()`](qiskit-addon-cutting#partition_circuit_qubits "qiskit_addon_cutting.partition_circuit_qubits") and [`partition_problem()`](qiskit-addon-cutting#partition_problem "qiskit_addon_cutting.partition_problem") will now have labels prefixed with “cut”, rather than “qpd”. @@ -303,7 +303,7 @@ The 0.3.0 release introduces significant new features while maintaining backward ### Deprecation Notes -* `decompose_gates()` is deprecated and will be removed no sooner than v0.4.0. Users should migrate to the identical [`cut_gates()`](cut-gates "qiskit_addon_cutting.cut_gates") function. +* `decompose_gates()` is deprecated and will be removed no sooner than v0.4.0. Users should migrate to the identical [`cut_gates()`](qiskit-addon-cutting#cut_gates "qiskit_addon_cutting.cut_gates") function. * `generate_qpd_samples()` has been renamed to `generate_qpd_weights()`. The original name will be removed no sooner than version 0.4 of the Circuit Knitting Toolbox. @@ -342,7 +342,7 @@ The 0.3.0 release introduces significant new features while maintaining backward The foundation of the `circuit_cutting` package is the `circuit_knitting_toolbox.circuit_cutting.qpd` sub-package. The `qpd` package allows for easy transformation of [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)") gates and wires into elements which may be decomposed to a probabilistic set of basis gates. See `QPDBasis` and `BaseQPDGate` classes for more information. -Additionally, 0.2.0 includes a set of functions which allow for easy implementation of gate cutting workflows. These functions are built on top of the `circuit_knitting_toolbox.circuit_cutting.qpd` package. Like all circuit knitting techniques, gate cutting can be described as three consecutive stages: *decomposition* of a problem, *execution* of many subexperiments, and *reconstruction* of a simulated output of the original problem. These steps may be implemented with the `circuit_cutting` package using only a few primary functions, namely, the [`partition_problem()`](partition-problem "qiskit_addon_cutting.partition_problem"), `decompose_gates()`, `execute_experiments()`, and [`reconstruct_expectation_values()`](reconstruct-expectation-values "qiskit_addon_cutting.reconstruct_expectation_values") functions. Check out the [tutorials](https://qiskit.github.io/qiskit-addon-cutting/tutorials/index.html) for a look at a couple of example circuit cutting workflows. +Additionally, 0.2.0 includes a set of functions which allow for easy implementation of gate cutting workflows. These functions are built on top of the `circuit_knitting_toolbox.circuit_cutting.qpd` package. Like all circuit knitting techniques, gate cutting can be described as three consecutive stages: *decomposition* of a problem, *execution* of many subexperiments, and *reconstruction* of a simulated output of the original problem. These steps may be implemented with the `circuit_cutting` package using only a few primary functions, namely, the [`partition_problem()`](qiskit-addon-cutting#partition_problem "qiskit_addon_cutting.partition_problem"), `decompose_gates()`, `execute_experiments()`, and [`reconstruct_expectation_values()`](qiskit-addon-cutting#reconstruct_expectation_values "qiskit_addon_cutting.reconstruct_expectation_values") functions. Check out the [tutorials](https://qiskit.github.io/qiskit-addon-cutting/tutorials/index.html) for a look at a couple of example circuit cutting workflows. @@ -352,7 +352,7 @@ Additionally, 0.2.0 includes a set of functions which allow for easy implementat * Addition of a `qpd` package which allows for easy transformation of [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)") gates and wires into elements which may be decomposed to a probabilistic set of basis gates. See `QPDBasis` and `BaseQPDGate` classes for more information. -* Addition of `cutting_decomposition`, `cutting_execution`, and `cutting_reconstruction` modules. These modules provide several functions which allow for easy implementation of gate cutting workflows, namely, the [`partition_problem()`](partition-problem "qiskit_addon_cutting.partition_problem"), `decompose_gates()`, `execute_experiments()`, and [`reconstruct_expectation_values()`](reconstruct-expectation-values "qiskit_addon_cutting.reconstruct_expectation_values") functions. +* Addition of `cutting_decomposition`, `cutting_execution`, and `cutting_reconstruction` modules. These modules provide several functions which allow for easy implementation of gate cutting workflows, namely, the [`partition_problem()`](qiskit-addon-cutting#partition_problem "qiskit_addon_cutting.partition_problem"), `decompose_gates()`, `execute_experiments()`, and [`reconstruct_expectation_values()`](qiskit-addon-cutting#reconstruct_expectation_values "qiskit_addon_cutting.reconstruct_expectation_values") functions. @@ -360,7 +360,7 @@ Additionally, 0.2.0 includes a set of functions which allow for easy implementat * The `circuit_cutting` package only supports [`PauliList`](/api/qiskit/qiskit.quantum_info.PauliList "(in Qiskit v1.2)") observables for calculating expectation values. Support for calculating expectation values for more observable types, including [`SparsePauliOp`](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)"), is expected no sooner than 0.3.0. -* The `Sampler`s from Qiskit and Qiskit Aer do not support mid-circuit measurements in statevector mode. For more on generating exact quasi-distributions using the [`BaseSampler`](/api/qiskit/qiskit.primitives.BaseSampler "(in Qiskit v1.2)") interface, check out our [how-to guide](https://github.com/Qiskit-Extensions/circuit-knitting-toolbox/tree/main/docs/circuit_cutting/how-tos/how_to_generate_exact_quasi_dists_from_sampler.ipynb). +* The `Sampler`s from Qiskit and Qiskit Aer do not support mid-circuit measurements in statevector mode. For more on generating exact quasi-distributions using the [`BaseSampler`](/api/qiskit/qiskit.primitives.BaseSampler "(in Qiskit v1.2)") interface, check out our [how-to guide](https://github.com/Qiskit/qiskit-addon-cutting/blob/stable/0.7/docs/circuit_cutting/how-tos/how_to_generate_exact_quasi_dists_from_sampler.ipynb). * The `circuit_cutting` package generally does not yet support input circuits with user-added classical bits, so by extension, it does not yet support dynamic circuits. diff --git a/docs/api/qiskit-addon-cutting/utils-bitwise-bit-count.mdx b/docs/api/qiskit-addon-cutting/utils-bitwise-bit-count.mdx deleted file mode 100644 index 84318ac1034..00000000000 --- a/docs/api/qiskit-addon-cutting/utils-bitwise-bit-count.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: bit_count -description: API reference for qiskit_addon_cutting.utils.bitwise.bit_count -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_cutting.utils.bitwise.bit_count ---- - - - -# qiskit\_addon\_cutting.utils.bitwise.bit\_count - - - Count number of set bits. - - diff --git a/docs/api/qiskit-addon-cutting/utils-bitwise.mdx b/docs/api/qiskit-addon-cutting/utils-bitwise.mdx new file mode 100644 index 00000000000..529f152b75a --- /dev/null +++ b/docs/api/qiskit-addon-cutting/utils-bitwise.mdx @@ -0,0 +1,24 @@ +--- +title: bitwise +description: API reference for qiskit_addon_cutting.utils.bitwise +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_addon_cutting.utils.bitwise +--- + + + + + +# Bitwise utilities + +`qiskit_addon_cutting.utils.bitwise` + +Module for bitwise utilities. + +### bit\_count + + + Count number of set bits. + + diff --git a/docs/api/qiskit-addon-cutting/utils-iteration-unique-by-eq.mdx b/docs/api/qiskit-addon-cutting/utils-iteration-unique-by-eq.mdx deleted file mode 100644 index 75898ce70ee..00000000000 --- a/docs/api/qiskit-addon-cutting/utils-iteration-unique-by-eq.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: unique_by_eq -description: API reference for qiskit_addon_cutting.utils.iteration.unique_by_eq -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_cutting.utils.iteration.unique_by_eq ---- - - - -# qiskit\_addon\_cutting.utils.iteration.unique\_by\_eq - - - Return unique objects in `iterable`, by equality. - - This function is only appropriate if (i) there are a small number of objects, and (ii) the objects are not guaranteed to be hashable. Otherwise, a `dict` or `set` is a better choice. - - This function may potentially make a comparison between all pairs of elements, so it executes in $O(n^2)$ time in the worst case, in contrast to a `dict` or `set`, both of which can be constructed in $O(n)$ time. - - ```python - >>> a = {0} - >>> list(unique_by_eq([a, a])) - [{0}] - :rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`list\`` - ``` - - ```python - >>> list(unique_by_eq([a, a.copy()])) - [{0}] - ``` - - diff --git a/docs/api/qiskit-addon-cutting/utils-iteration-unique-by-id.mdx b/docs/api/qiskit-addon-cutting/utils-iteration-unique-by-id.mdx deleted file mode 100644 index 40cf0a7bb54..00000000000 --- a/docs/api/qiskit-addon-cutting/utils-iteration-unique-by-id.mdx +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: unique_by_id -description: API reference for qiskit_addon_cutting.utils.iteration.unique_by_id -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_cutting.utils.iteration.unique_by_id ---- - - - -# qiskit\_addon\_cutting.utils.iteration.unique\_by\_id - - - Return unique objects in `iterable`, by identity. - - ```python - >>> a = {0} - >>> list(unique_by_id([a, a])) - [{0}] - :rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~collections.abc.ValuesView\`` - ``` - - ```python - >>> list(unique_by_id([a, a.copy()])) - [{0}, {0}] - ``` - - diff --git a/docs/api/qiskit-addon-cutting/utils-iteration.mdx b/docs/api/qiskit-addon-cutting/utils-iteration.mdx new file mode 100644 index 00000000000..35c08a81fa2 --- /dev/null +++ b/docs/api/qiskit-addon-cutting/utils-iteration.mdx @@ -0,0 +1,58 @@ +--- +title: iteration +description: API reference for qiskit_addon_cutting.utils.iteration +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_addon_cutting.utils.iteration +--- + + + + + +# Iteration utilities + +`qiskit_addon_cutting.utils.iteration` + +Iteration utilities. + +### unique\_by\_id + + + Return unique objects in `iterable`, by identity. + + ```python + >>> a = {0} + >>> list(unique_by_id([a, a])) + [{0}] + :rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~collections.abc.ValuesView\`` + ``` + + ```python + >>> list(unique_by_id([a, a.copy()])) + [{0}, {0}] + ``` + + +### unique\_by\_eq + + + Return unique objects in `iterable`, by equality. + + This function is only appropriate if (i) there are a small number of objects, and (ii) the objects are not guaranteed to be hashable. Otherwise, a `dict` or `set` is a better choice. + + This function may potentially make a comparison between all pairs of elements, so it executes in $O(n^2)$ time in the worst case, in contrast to a `dict` or `set`, both of which can be constructed in $O(n)$ time. + + ```python + >>> a = {0} + >>> list(unique_by_eq([a, a])) + [{0}] + :rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`list\`` + ``` + + ```python + >>> list(unique_by_eq([a, a.copy()])) + [{0}] + ``` + + diff --git a/docs/api/qiskit-addon-cutting/utils-observable-grouping-commuting-observable-group.mdx b/docs/api/qiskit-addon-cutting/utils-observable-grouping-commuting-observable-group.mdx deleted file mode 100644 index 07ca34b8d64..00000000000 --- a/docs/api/qiskit-addon-cutting/utils-observable-grouping-commuting-observable-group.mdx +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: CommutingObservableGroup -description: API reference for qiskit_addon_cutting.utils.observable_grouping.CommutingObservableGroup -in_page_toc_min_heading_level: 1 -python_api_type: class -python_api_name: qiskit_addon_cutting.utils.observable_grouping.CommutingObservableGroup ---- - - - -# qiskit\_addon\_cutting.utils.observable\_grouping.CommutingObservableGroup - - - Set of mutually qubit-wise commuting observables. - - ### \_\_init\_\_ - - - - ## Methods - - | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | - | - | [`__init__`](#qiskit_addon_cutting.utils.observable_grouping.CommutingObservableGroup.__init__ "qiskit_addon_cutting.utils.observable_grouping.CommutingObservableGroup.__init__")(general\_observable, ...) | | - - ## Attributes - - | | | - | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | `general_observable` | A single Pauli string that contains all qubit-wise measurements needed to measure everything in `commuting_observables`. | - | `commuting_observables` | Observables that can be measured simultaneously. | - | `pauli_indices` | The indices of non-identity [`Pauli`](/api/qiskit/qiskit.quantum_info.Pauli "(in Qiskit v1.2)")s in `general_observable`. | - | `pauli_bitmasks` | A bitmask for each observable in `commuting_observables`; given an element, each bit corresponds to whether the corresponding entry in `pauli_indices` is relevant to that observable. | - - diff --git a/docs/api/qiskit-addon-cutting/utils-observable-grouping-observable-collection.mdx b/docs/api/qiskit-addon-cutting/utils-observable-grouping-observable-collection.mdx deleted file mode 100644 index 6557cf971ec..00000000000 --- a/docs/api/qiskit-addon-cutting/utils-observable-grouping-observable-collection.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: ObservableCollection -description: API reference for qiskit_addon_cutting.utils.observable_grouping.ObservableCollection -in_page_toc_min_heading_level: 1 -python_api_type: class -python_api_name: qiskit_addon_cutting.utils.observable_grouping.ObservableCollection ---- - - - -# qiskit\_addon\_cutting.utils.observable\_grouping.ObservableCollection - - - Collection of observables organized for efficient taking of measurements. - - The observables are automatically organized into sets of mutually qubit-wise commuting observables, each represented by a [`CommutingObservableGroup`](utils-observable-grouping-commuting-observable-group "qiskit_addon_cutting.utils.observable_grouping.CommutingObservableGroup"). - - Assign member variables. - - **Parameters** - - **observables** (PauliList | Iterable\[Pauli]) – Observables of interest - - ### \_\_init\_\_ - - - Assign member variables. - - **Parameters** - - **observables** (PauliList | Iterable\[Pauli]) – Observables of interest - - - ## Methods - - | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | - | [`__init__`](#qiskit_addon_cutting.utils.observable_grouping.ObservableCollection.__init__ "qiskit_addon_cutting.utils.observable_grouping.ObservableCollection.__init__")(observables, /) | Assign member variables. | - | `construct_general_observables`(...) | Construct the most general observable from each set of mutually commuting observables. | - - ## Attributes - - | | | - | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | `groups` | List of [`CommutingObservableGroup`](utils-observable-grouping-commuting-observable-group "qiskit_addon_cutting.utils.observable_grouping.CommutingObservableGroup")s which, together, contain all desired observables. | - | `lookup` | Get dict which maps each [`Pauli`](/api/qiskit/qiskit.quantum_info.Pauli "(in Qiskit v1.2)") observable to a list of indices, `(i, j)`, to commuting observables in `groups`. | - - diff --git a/docs/api/qiskit-addon-cutting/utils-observable-grouping-observables-restricted-to-subsystem.mdx b/docs/api/qiskit-addon-cutting/utils-observable-grouping-observables-restricted-to-subsystem.mdx deleted file mode 100644 index 4b43d445fd5..00000000000 --- a/docs/api/qiskit-addon-cutting/utils-observable-grouping-observables-restricted-to-subsystem.mdx +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: observables_restricted_to_subsystem -description: API reference for qiskit_addon_cutting.utils.observable_grouping.observables_restricted_to_subsystem -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_cutting.utils.observable_grouping.observables_restricted_to_subsystem ---- - - - -# qiskit\_addon\_cutting.utils.observable\_grouping.observables\_restricted\_to\_subsystem - - - Restrict each observable to its support on a given subsystem. - - A [`PauliList`](/api/qiskit/qiskit.quantum_info.PauliList "(in Qiskit v1.2)") will be returned if a [`PauliList`](/api/qiskit/qiskit.quantum_info.PauliList "(in Qiskit v1.2)") is provided; otherwise, a `list[Pauli]` will be returned. - - Any phase information will be discarded, consistent with the standard behavior when slicing a Pauli. - - **Parameters** - - * **qubits** (Sequence\[int]) – The qubits in a subsystem - * **global\_observables** (Sequence\[Pauli] | PauliList) – The list of observables - - **Return type** - - list\[Pauli] | PauliList - - **Returns** - - Each [`Pauli`](/api/qiskit/qiskit.quantum_info.Pauli "(in Qiskit v1.2)") restricted to the subsystem. - - ```python - >>> observables_restricted_to_subsystem([1, 3], PauliList(["IXYZ", "iZZXX"])) - PauliList(['IY', 'ZX']) - ``` - - diff --git a/docs/api/qiskit-addon-cutting/utils-observable-grouping.mdx b/docs/api/qiskit-addon-cutting/utils-observable-grouping.mdx new file mode 100644 index 00000000000..2cdaaba3275 --- /dev/null +++ b/docs/api/qiskit-addon-cutting/utils-observable-grouping.mdx @@ -0,0 +1,66 @@ +--- +title: observable_grouping +description: API reference for qiskit_addon_cutting.utils.observable_grouping +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_addon_cutting.utils.observable_grouping +--- + + + + + +# Observable grouping + +`qiskit_addon_cutting.utils.observable_grouping` + +Module for conducting Pauli observable grouping. + +### observables\_restricted\_to\_subsystem + + + Restrict each observable to its support on a given subsystem. + + A [`PauliList`](/api/qiskit/qiskit.quantum_info.PauliList "(in Qiskit v1.2)") will be returned if a [`PauliList`](/api/qiskit/qiskit.quantum_info.PauliList "(in Qiskit v1.2)") is provided; otherwise, a `list[Pauli]` will be returned. + + Any phase information will be discarded, consistent with the standard behavior when slicing a Pauli. + + **Parameters** + + * **qubits** (Sequence\[int]) – The qubits in a subsystem + * **global\_observables** (Sequence\[Pauli] | PauliList) – The list of observables + + **Return type** + + list\[Pauli] | PauliList + + **Returns** + + Each [`Pauli`](/api/qiskit/qiskit.quantum_info.Pauli "(in Qiskit v1.2)") restricted to the subsystem. + + ```python + >>> observables_restricted_to_subsystem([1, 3], PauliList(["IXYZ", "iZZXX"])) + PauliList(['IY', 'ZX']) + ``` + + +### CommutingObservableGroup + + + Set of mutually qubit-wise commuting observables. + + +### ObservableCollection + + + Collection of observables organized for efficient taking of measurements. + + The observables are automatically organized into sets of mutually qubit-wise commuting observables, each represented by a [`CommutingObservableGroup`](#qiskit_addon_cutting.utils.observable_grouping.CommutingObservableGroup "qiskit_addon_cutting.utils.observable_grouping.CommutingObservableGroup"). + + Assign member variables. + + **Parameters** + + **observables** (PauliList | Iterable\[Pauli]) – Observables of interest + + diff --git a/docs/api/qiskit-addon-cutting/utils-simulation-exact-sampler.mdx b/docs/api/qiskit-addon-cutting/utils-simulation-exact-sampler.mdx deleted file mode 100644 index 82e4bff93e3..00000000000 --- a/docs/api/qiskit-addon-cutting/utils-simulation-exact-sampler.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: ExactSampler -description: API reference for qiskit_addon_cutting.utils.simulation.ExactSampler -in_page_toc_min_heading_level: 1 -python_api_type: class -python_api_name: qiskit_addon_cutting.utils.simulation.ExactSampler ---- - - - -# qiskit\_addon\_cutting.utils.simulation.ExactSampler - - - Sampler which returns exact probabilities for each possible outcome. - - This sampler supports: - - * all unitary gates - * projective measurements, anywhere in the circuit - * reset operations, anywhere in the circuit - * some (or all) classical bits can remain unused - * classical bits can be written more than once - - The samplers provided by [`qiskit.primitives`](/api/qiskit/primitives#module-qiskit.primitives "(in Qiskit v1.2)") and [`qiskit_aer.primitives`](https://qiskit.github.io/qiskit-aer/apidocs/aer_primitives.html#module-qiskit_aer.primitives "(in Qiskit Aer v0.15.0)") do not currently support all of the above functionality. Related upstream issues: - - * [https://github.com/Qiskit/qiskit-terra/issues/9657](https://github.com/Qiskit/qiskit-terra/issues/9657) - * [https://github.com/Qiskit/qiskit-aer/issues/1810](https://github.com/Qiskit/qiskit-aer/issues/1810) - * [https://github.com/Qiskit/qiskit-aer/issues/1811](https://github.com/Qiskit/qiskit-aer/issues/1811) - - **Parameters** - - **options** (dict | None) – Default options. - - ### \_\_init\_\_ - - - **Parameters** - - **options** (dict | None) – Default options. - - - ## Methods - - | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | - | [`__init__`](#qiskit_addon_cutting.utils.simulation.ExactSampler.__init__ "qiskit_addon_cutting.utils.simulation.ExactSampler.__init__")(\*\[, options]) | | - | `run`(circuits\[, parameter\_values]) | Run the job of the sampling of bitstrings. | - | `set_options`(\*\*fields) | Set options values for the estimator. | - - ## Attributes - - | | | - | --------- | ---------------------------------------- | - | `options` | Return options values for the estimator. | - - diff --git a/docs/api/qiskit-addon-cutting/utils-simulation-simulate-statevector-outcomes.mdx b/docs/api/qiskit-addon-cutting/utils-simulation-simulate-statevector-outcomes.mdx deleted file mode 100644 index ebbff5a7856..00000000000 --- a/docs/api/qiskit-addon-cutting/utils-simulation-simulate-statevector-outcomes.mdx +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: simulate_statevector_outcomes -description: API reference for qiskit_addon_cutting.utils.simulation.simulate_statevector_outcomes -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_cutting.utils.simulation.simulate_statevector_outcomes ---- - - - -# qiskit\_addon\_cutting.utils.simulation.simulate\_statevector\_outcomes - - - Return each classical outcome along with its precise probability. - - Circuit can contain mid-circuit, projective measurements. - - All gates are supported, along with measurements and reset operations. - - **Return type** - - [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")\[[`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)"), [`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")] - - diff --git a/docs/api/qiskit-addon-cutting/utils-simulation.mdx b/docs/api/qiskit-addon-cutting/utils-simulation.mdx new file mode 100644 index 00000000000..5f381f285da --- /dev/null +++ b/docs/api/qiskit-addon-cutting/utils-simulation.mdx @@ -0,0 +1,56 @@ +--- +title: simulation +description: API reference for qiskit_addon_cutting.utils.simulation +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_addon_cutting.utils.simulation +--- + + + + + +# Simulation utilities + +`qiskit_addon_cutting.utils.simulation` + +Simulation of precise measurement outcome probabilities. + +### simulate\_statevector\_outcomes + + + Return each classical outcome along with its precise probability. + + Circuit can contain mid-circuit, projective measurements. + + All gates are supported, along with measurements and reset operations. + + **Return type** + + [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")\[[`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)"), [`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")] + + +### ExactSampler + + + Sampler which returns exact probabilities for each possible outcome. + + This sampler supports: + + * all unitary gates + * projective measurements, anywhere in the circuit + * reset operations, anywhere in the circuit + * some (or all) classical bits can remain unused + * classical bits can be written more than once + + The samplers provided by [`qiskit.primitives`](/api/qiskit/primitives#module-qiskit.primitives "(in Qiskit v1.2)") and [`qiskit_aer.primitives`](https://qiskit.github.io/qiskit-aer/apidocs/aer_primitives.html#module-qiskit_aer.primitives "(in Qiskit Aer v0.15.0)") do not currently support all of the above functionality. Related upstream issues: + + * [https://github.com/Qiskit/qiskit/issues/9657](https://github.com/Qiskit/qiskit/issues/9657) + * [https://github.com/Qiskit/qiskit-aer/issues/1810](https://github.com/Qiskit/qiskit-aer/issues/1810) + * [https://github.com/Qiskit/qiskit-aer/issues/1811](https://github.com/Qiskit/qiskit-aer/issues/1811) + + **Parameters** + + **options** (dict | None) – Default options. + + diff --git a/docs/api/qiskit-addon-cutting/utils-transforms-separated-circuits.mdx b/docs/api/qiskit-addon-cutting/utils-transforms-separated-circuits.mdx deleted file mode 100644 index c4a8100abc1..00000000000 --- a/docs/api/qiskit-addon-cutting/utils-transforms-separated-circuits.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: SeparatedCircuits -description: API reference for qiskit_addon_cutting.utils.transforms.SeparatedCircuits -in_page_toc_min_heading_level: 1 -python_api_type: class -python_api_name: qiskit_addon_cutting.utils.transforms.SeparatedCircuits ---- - - - -# qiskit\_addon\_cutting.utils.transforms.SeparatedCircuits - - - Bases: [`NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple "(in Python v3.13)") - - Named tuple for result of [`separate_circuit()`](utils-transforms-separate-circuit "qiskit_addon_cutting.utils.transforms.separate_circuit"). - - `subcircuits` is a dict of circuits, keyed by each partition label. `qubit_map` is a list with length equal to the number of qubits in the original circuit. Each element of that list is a 2-tuple which includes the partition label of that qubit, together with the index of that qubit in the corresponding subcircuit. If the original qubit is unused and has been removed from the separated circuits, then that tuple will be equal to `(None, None)`. - - Create new instance of SeparatedCircuits(subcircuits, qubit\_map) - - ## Methods - - | | - | - | - - ## Attributes - - | | | - | ------------- | ------------------------ | - | `qubit_map` | Alias for field number 1 | - | `subcircuits` | Alias for field number 0 | - - diff --git a/docs/api/qiskit-addon-cutting/utils-transforms-separate-circuit.mdx b/docs/api/qiskit-addon-cutting/utils-transforms.mdx similarity index 53% rename from docs/api/qiskit-addon-cutting/utils-transforms-separate-circuit.mdx rename to docs/api/qiskit-addon-cutting/utils-transforms.mdx index ace93f555e5..a49884dedfa 100644 --- a/docs/api/qiskit-addon-cutting/utils-transforms-separate-circuit.mdx +++ b/docs/api/qiskit-addon-cutting/utils-transforms.mdx @@ -1,16 +1,24 @@ --- -title: separate_circuit -description: API reference for qiskit_addon_cutting.utils.transforms.separate_circuit -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_cutting.utils.transforms.separate_circuit +title: transforms +description: API reference for qiskit_addon_cutting.utils.transforms +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_addon_cutting.utils.transforms --- - + -# qiskit\_addon\_cutting.utils.transforms.separate\_circuit + - +# Transforms + +`qiskit_addon_cutting.utils.transforms` + +Functions for manipulating quantum circuits. + +### separate\_circuit + + Separate the circuit into its disconnected components. If `partition_labels` is provided, then the circuit will be separated according to those labels. A partition label of `None` is treated specially: it must be applied to an unused (idle) qubit, and that qubit will be removed when separating the circuit. @@ -48,7 +56,7 @@ python_api_name: qiskit_addon_cutting.utils.transforms.separate_circuit **Returns** - A [`SeparatedCircuits`](utils-transforms-separated-circuits "qiskit_addon_cutting.utils.transforms.SeparatedCircuits") named tuple containing the `subcircuits` and `qubit_map`. + A [`SeparatedCircuits`](#qiskit_addon_cutting.utils.transforms.SeparatedCircuits "qiskit_addon_cutting.utils.transforms.SeparatedCircuits") named tuple containing the `subcircuits` and `qubit_map`. **Raises** @@ -56,3 +64,13 @@ python_api_name: qiskit_addon_cutting.utils.transforms.separate_circuit * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Operation spans more than one partition. +### SeparatedCircuits + + + Named tuple for result of [`separate_circuit()`](#qiskit_addon_cutting.utils.transforms.separate_circuit "qiskit_addon_cutting.utils.transforms.separate_circuit"). + + `subcircuits` is a dict of circuits, keyed by each partition label. `qubit_map` is a list with length equal to the number of qubits in the original circuit. Each element of that list is a 2-tuple which includes the partition label of that qubit, together with the index of that qubit in the corresponding subcircuit. If the original qubit is unused and has been removed from the separated circuits, then that tuple will be equal to `(None, None)`. + + Create new instance of SeparatedCircuits(subcircuits, qubit\_map) + + diff --git a/docs/api/qiskit-addon-cutting/utils-transpiler-passes-consolidate-resets.mdx b/docs/api/qiskit-addon-cutting/utils-transpiler-passes-consolidate-resets.mdx deleted file mode 100644 index 952e2fbe971..00000000000 --- a/docs/api/qiskit-addon-cutting/utils-transpiler-passes-consolidate-resets.mdx +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: ConsolidateResets -description: API reference for qiskit_addon_cutting.utils.transpiler_passes.ConsolidateResets -in_page_toc_min_heading_level: 1 -python_api_type: class -python_api_name: qiskit_addon_cutting.utils.transpiler_passes.ConsolidateResets ---- - - - -# qiskit\_addon\_cutting.utils.transpiler\_passes.ConsolidateResets - - - Consolidate a run duplicate resets in to a single reset. - - ### \_\_init\_\_ - - - - ## Methods - - | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | - | [`__init__`](#qiskit_addon_cutting.utils.transpiler_passes.ConsolidateResets.__init__ "qiskit_addon_cutting.utils.transpiler_passes.ConsolidateResets.__init__")() | | - | `execute`(passmanager\_ir, state\[, callback]) | Execute optimization task for input Qiskit IR. | - | `name`() | Name of the pass. | - | `run`(dag) | Run the ConsolidateResets pass on `dag`. | - | `update_status`(state, run\_state) | Update workflow status. | - - ## Attributes - - | | | - | ------------------------ | ------------------------------------------- | - | `is_analysis_pass` | Check if the pass is an analysis pass. | - | `is_transformation_pass` | Check if the pass is a transformation pass. | - - diff --git a/docs/api/qiskit-addon-cutting/utils-transpiler-passes-remove-final-reset.mdx b/docs/api/qiskit-addon-cutting/utils-transpiler-passes-remove-final-reset.mdx deleted file mode 100644 index 981aab481c3..00000000000 --- a/docs/api/qiskit-addon-cutting/utils-transpiler-passes-remove-final-reset.mdx +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: RemoveFinalReset -description: API reference for qiskit_addon_cutting.utils.transpiler_passes.RemoveFinalReset -in_page_toc_min_heading_level: 1 -python_api_type: class -python_api_name: qiskit_addon_cutting.utils.transpiler_passes.RemoveFinalReset ---- - - - -# qiskit\_addon\_cutting.utils.transpiler\_passes.RemoveFinalReset - - - Remove reset when it is the final instruction on a qubit wire. - - ### \_\_init\_\_ - - - - ## Methods - - | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | - | [`__init__`](#qiskit_addon_cutting.utils.transpiler_passes.RemoveFinalReset.__init__ "qiskit_addon_cutting.utils.transpiler_passes.RemoveFinalReset.__init__")() | | - | `execute`(passmanager\_ir, state\[, callback]) | Execute optimization task for input Qiskit IR. | - | `name`() | Name of the pass. | - | `run`(dag) | Run the RemoveFinalReset pass on `dag`. | - | `update_status`(state, run\_state) | Update workflow status. | - - ## Attributes - - | | | - | ------------------------ | ------------------------------------------- | - | `is_analysis_pass` | Check if the pass is an analysis pass. | - | `is_transformation_pass` | Check if the pass is a transformation pass. | - - diff --git a/docs/api/qiskit-addon-cutting/utils-transpiler-passes.mdx b/docs/api/qiskit-addon-cutting/utils-transpiler-passes.mdx new file mode 100644 index 00000000000..888a8d4b32b --- /dev/null +++ b/docs/api/qiskit-addon-cutting/utils-transpiler-passes.mdx @@ -0,0 +1,30 @@ +--- +title: transpiler_passes +description: API reference for qiskit_addon_cutting.utils.transpiler_passes +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_addon_cutting.utils.transpiler_passes +--- + + + + + +# Transpiler passes + +`qiskit_addon_cutting.utils.transpiler_passes` + +Transpiler passes useful for circuit knitting. + +### RemoveFinalReset + + + Remove reset when it is the final instruction on a qubit wire. + + +### ConsolidateResets + + + Consolidate a run duplicate resets in to a single reset. + + diff --git a/docs/api/qiskit-addon-mpf/_toc.json b/docs/api/qiskit-addon-mpf/_toc.json index 092990b0c99..b607c4f3299 100644 --- a/docs/api/qiskit-addon-mpf/_toc.json +++ b/docs/api/qiskit-addon-mpf/_toc.json @@ -5,6 +5,10 @@ "title": "API index", "url": "/api/qiskit-addon-mpf" }, + { + "title": "qiskit_addon_mpf.static", + "url": "/api/qiskit-addon-mpf/static" + }, { "title": "Release notes", "url": "/api/qiskit-addon-mpf/release-notes" diff --git a/docs/api/qiskit-addon-mpf/index.mdx b/docs/api/qiskit-addon-mpf/index.mdx new file mode 100644 index 00000000000..16b0436d7fe --- /dev/null +++ b/docs/api/qiskit-addon-mpf/index.mdx @@ -0,0 +1,5 @@ + + +# `qiskit-addon-mpf` API reference + +* [Static MPFs (`qiskit_addon_mpf.static`)](static) diff --git a/docs/api/qiskit-addon-mpf/qiskit-addon-mpf.mdx b/docs/api/qiskit-addon-mpf/qiskit-addon-mpf.mdx deleted file mode 100644 index d50c2282427..00000000000 --- a/docs/api/qiskit-addon-mpf/qiskit-addon-mpf.mdx +++ /dev/null @@ -1,16 +0,0 @@ -# Qiskit addon: multi-product formulas (MPF) - - - - - -Multi-product formulas. - -| | -| - | - -## Submodules - -| | | -| --------------------------------------------------------------------------- | ------------ | -| [`static`](static#module-qiskit_addon_mpf.static "qiskit_addon_mpf.static") | Static MPFs. | diff --git a/docs/api/qiskit-addon-mpf/static-lse.mdx b/docs/api/qiskit-addon-mpf/static-lse.mdx deleted file mode 100644 index 2dca8caacaf..00000000000 --- a/docs/api/qiskit-addon-mpf/static-lse.mdx +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: LSE -description: API reference for qiskit_addon_mpf.static.LSE -in_page_toc_min_heading_level: 1 -python_api_type: class -python_api_name: qiskit_addon_mpf.static.LSE ---- - -# LSE - - - Bases: [`NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple "(in Python v3.13)") - - A `namedtuple` representing a linear system of equations. - -$$ -A x = b -$$ - - Create new instance of LSE(A, b) - - ## Attributes - - ### A - - - The left hand side of the LSE. - - - ### b - - - The right hand side of the LSE. - - - ### x - - - Returns the \$x\$ [`Variable`](https://www.cvxpy.org/api_reference/cvxpy.expressions.html#cvxpy.expressions.variable.Variable "(in CVXPY v1.5)"). - - - ## Methods - - ### count - - - Return number of occurrences of value. - - - ### index - - - Return first index of value. - - Raises ValueError if the value is not present. - - - ### solve - - - Return the solution to this LSE: $x=A^{-1}b$. - - **Returns** - - The solution to this LSE. - - **Raises** - - [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – if this LSE is parameterized with unassigned values. - - **Return type** - - [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)") - - - diff --git a/docs/api/qiskit-addon-mpf/static-setup-approximate-model.mdx b/docs/api/qiskit-addon-mpf/static-setup-approximate-model.mdx deleted file mode 100644 index bd59edf321c..00000000000 --- a/docs/api/qiskit-addon-mpf/static-setup-approximate-model.mdx +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: setup_approximate_model -description: API reference for qiskit_addon_mpf.static.setup_approximate_model -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_mpf.static.setup_approximate_model ---- - - - -# setup\_approximate\_model - - - Construct a [`cvxpy.Problem`](https://www.cvxpy.org/api_reference/cvxpy.problems.html#cvxpy.Problem "(in CVXPY v1.5)") for finding approximate static MPF coefficients. - - The optimization problem constructed by this class is defined as follows: - - * the cost function minimizes the sum of squares ([`sum_squares()`](https://www.cvxpy.org/api_reference/cvxpy.atoms.other_atoms.html#cvxpy.atoms.sum_squares.sum_squares "(in CVXPY v1.5)")) of the distances to an exact solution for all equations of the [`LSE`](static-lse "qiskit_addon_mpf.static.LSE"): - -$$ -\sum_i \left( \sum_j A_{ij} x_j - b_i \right)^2 -$$ - - * two constraints are set: - - 1. the variables must sum to 1: $\sum_i x_i == 1$ - 2. the L1-norm ([`norm1`](https://www.cvxpy.org/api_reference/cvxpy.atoms.other_atoms.html#cvxpy.atoms.norm1.norm1 "(in CVXPY v1.5)")) of the variables is bounded by `max_l1_norm` - - Here is an example: - - ```python - >>> from qiskit_addon_mpf.static import setup_lse, setup_approximate_model - >>> lse = setup_lse([1,2,3], order=2, symmetric=True) - >>> problem, coeffs = setup_approximate_model(lse, max_l1_norm=3.0) - >>> print(problem) - minimize quad_over_lin(Vstack([1. 1. 1.] @ x + -1.0, - [1. 0.25 0.11111111] @ x + -0.0, - [1. 0.0625 0.01234568] @ x + -0.0), 1.0) - subject to Sum(x, None, False) == 1.0 - norm1(x) <= 3.0 - ``` - - You can then solve the problem and extract the expansion coefficients like so: - - ```python - >>> final_cost = problem.solve() - >>> print(coeffs.value) - [ 0.03513467 -1. 1.96486533] - ``` - - **Parameters** - - * **lse** ([*LSE*](static-lse "qiskit_addon_mpf.static.lse.LSE")) – the linear system of equations from which to build the model. - * **max\_l1\_norm** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – the upper limit to use for the constrain of the L1-norm of the variables. - - **Returns** - - The optimization problem and coefficients variable. - - **Return type** - - [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*Problem*](https://www.cvxpy.org/api_reference/cvxpy.problems.html#cvxpy.Problem "(in CVXPY v1.5)"), [*Variable*](https://www.cvxpy.org/api_reference/cvxpy.expressions.html#cvxpy.expressions.variable.Variable "(in CVXPY v1.5)")] - - **References** - - ## \[1]: S. Zhuk et al., arXiv:2306.12569 (2023). - - [https://arxiv.org/abs/2306.12569](https://arxiv.org/abs/2306.12569) - - diff --git a/docs/api/qiskit-addon-mpf/static-setup-exact-model.mdx b/docs/api/qiskit-addon-mpf/static-setup-exact-model.mdx deleted file mode 100644 index a2508f059fa..00000000000 --- a/docs/api/qiskit-addon-mpf/static-setup-exact-model.mdx +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: setup_exact_model -description: API reference for qiskit_addon_mpf.static.setup_exact_model -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_mpf.static.setup_exact_model ---- - - - -# setup\_exact\_model - - - Construct a [`cvxpy.Problem`](https://www.cvxpy.org/api_reference/cvxpy.problems.html#cvxpy.Problem "(in CVXPY v1.5)") for finding exact static MPF coefficients. - - - The coefficients found via this optimization problem will be identical to the analytical ones obtained from the [`LSE.solve()`](static-lse#solve "qiskit_addon_mpf.static.LSE.solve") method. This additional interface exists to highlight the parallel to the [`setup_approximate_model()`](static-setup-approximate-model "qiskit_addon_mpf.static.setup_approximate_model") interface. It also serves educational purposes for how-to approach optimization problems targeting MPF coefficients. - - - The optimization problem constructed by this class is defined as follows: - - * the cost function minimizes the L1-norm ([`norm1`](https://www.cvxpy.org/api_reference/cvxpy.atoms.other_atoms.html#cvxpy.atoms.norm1.norm1 "(in CVXPY v1.5)")) of the variables ([`LSE.x`](static-lse#x "qiskit_addon_mpf.static.LSE.x")) - - * the constraints correspond to each equation of the [`LSE`](static-lse "qiskit_addon_mpf.static.LSE"): - -$$ -\sum_j A_{ij} x_j = b_i -$$ - - Here is an example: - - ```python - >>> from qiskit_addon_mpf.static import setup_lse, setup_exact_model - >>> lse = setup_lse([1,2,3], order=2, symmetric=True) - >>> problem, coeffs = setup_exact_model(lse) - >>> print(problem) - minimize norm1(x) - subject to Sum([1. 1. 1.] @ x, None, False) == 1.0 - Sum([1. 0.25 0.11111111] @ x, None, False) == 0.0 - Sum([1. 0.0625 0.01234568] @ x, None, False) == 0.0 - ``` - - You can then solve the problem and extract the expansion coefficients like so: - - ```python - >>> final_cost = problem.solve() - >>> print(coeffs.value) - [ 0.04166667 -1.06666667 2.025 ] - ``` - - **Parameters** - - **lse** ([*LSE*](static-lse "qiskit_addon_mpf.static.lse.LSE")) – the linear system of equations from which to build the model. - - **Returns** - - The optimization problem and coefficients variable. - - **Return type** - - [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*Problem*](https://www.cvxpy.org/api_reference/cvxpy.problems.html#cvxpy.Problem "(in CVXPY v1.5)"), [*Variable*](https://www.cvxpy.org/api_reference/cvxpy.expressions.html#cvxpy.expressions.variable.Variable "(in CVXPY v1.5)")] - - **References** - - ## \[1]: A. Carrera Vazquez et al., Quantum 7, 1067 (2023). - - [https://quantum-journal.org/papers/q-2023-07-25-1067/](https://quantum-journal.org/papers/q-2023-07-25-1067/) - - diff --git a/docs/api/qiskit-addon-mpf/static-setup-lse.mdx b/docs/api/qiskit-addon-mpf/static-setup-lse.mdx deleted file mode 100644 index 4dffd5e31a0..00000000000 --- a/docs/api/qiskit-addon-mpf/static-setup-lse.mdx +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: setup_lse -description: API reference for qiskit_addon_mpf.static.setup_lse -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_mpf.static.setup_lse ---- - - - -# setup\_lse - - - Return the linear system of equations for computing the static MPF coefficients. - - This function constructs the following linear system of equations: - -$$ -A x = b, -$$ - - with - -$$ -\begin{split}A_{0,j} &= 1 \\ -A_{i>0,j} &= k_{j}^{-(\chi + s(i-1))} \\ -b_0 &= 1 \\ -b_{i>0} &= 0\end{split} -$$ - - where \$\chi\$ is the `order`, \$s\$ is \$2\$ if `symmetric` is `True` and \$1\$ oterhwise, \$k\_\{j}\$ are the `trotter_steps`, and \$x\$ are the variables to solve for. The indices \$i\$ and \$j\$ start at \$0\$. - - Here is an example: - - ```python - >>> from qiskit_addon_mpf.static import setup_lse - >>> lse = setup_lse([1,2,3], order=2, symmetric=True) - >>> print(lse.A) - [[1. 1. 1. ] - [1. 0.25 0.11111111] - [1. 0.0625 0.01234568]] - >>> print(lse.b) - [1. 0. 0.] - ``` - - **Parameters** - - * **trotter\_steps** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*] |* [*Parameter*](https://www.cvxpy.org/api_reference/cvxpy.expressions.html#cvxpy.expressions.constants.parameter.Parameter "(in CVXPY v1.5)")) – the sequence of trotter steps from which to build \$A\$. Rather than a list of integers, this may also be a [`Parameter`](https://www.cvxpy.org/api_reference/cvxpy.expressions.html#cvxpy.expressions.constants.parameter.Parameter "(in CVXPY v1.5)") instance of the desired size. In this case, the constructed [`LSE`](static-lse "qiskit_addon_mpf.static.LSE") is parameterized whose values must be assigned before it can be solved. - * **order** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – the order of the individual product formulas making up the MPF. - * **symmetric** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – whether the individual product formulas making up the MPF are symmetric. For example, the Lie-Trotter formula is not symmetric, while Suzuki-Trotter is. - - **Returns** - - An [`LSE`](static-lse "qiskit_addon_mpf.static.LSE"). - - **Return type** - - [*LSE*](static-lse "qiskit_addon_mpf.static.lse.LSE") - - diff --git a/docs/api/qiskit-addon-mpf/static.mdx b/docs/api/qiskit-addon-mpf/static.mdx index 82596d7761e..e41a3178efd 100644 --- a/docs/api/qiskit-addon-mpf/static.mdx +++ b/docs/api/qiskit-addon-mpf/static.mdx @@ -1,26 +1,255 @@ -# Static MPFs +--- +title: static +description: API reference for qiskit_addon_mpf.static +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_addon_mpf.static +--- - + + +# Static MPFs + +`qiskit_addon_mpf.static` Static MPFs. ## Linear system of equations utilities -| | | -| ------------------------------------------------------------------- | -------------------------------------------------------------------------------- | -| [`LSE`](static-lse "qiskit_addon_mpf.static.LSE") | A `namedtuple` representing a linear system of equations. | -| [`setup_lse`](static-setup-lse "qiskit_addon_mpf.static.setup_lse") | Return the linear system of equations for computing the static MPF coefficients. | +### LSE + + + A `namedtuple` representing a linear system of equations. + +$$ +A x = b +$$ + + Create new instance of LSE(A, b) + + #### A + + + The left hand side of the LSE. + + + #### b + + + The right hand side of the LSE. + + + #### x + + + Returns the \$x\$ [`Variable`](https://www.cvxpy.org/api_reference/cvxpy.expressions.html#cvxpy.expressions.variable.Variable "(in CVXPY v1.5)"). + + + #### count + + + Return number of occurrences of value. + + + #### index + + + Return first index of value. + + Raises ValueError if the value is not present. + + + #### solve + + + Return the solution to this LSE: $x=A^{-1}b$. + + **Returns** + + The solution to this LSE. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – if this LSE is parameterized with unassigned values. + + **Return type** + + [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)") + + + +### setup\_lse + + + Return the linear system of equations for computing the static MPF coefficients. + + This function constructs the following linear system of equations: + +$$ +A x = b, +$$ + + with + +$$ +\begin{split}A_{0,j} &= 1 \\ +A_{i>0,j} &= k_{j}^{-(\chi + s(i-1))} \\ +b_0 &= 1 \\ +b_{i>0} &= 0\end{split} +$$ + + where \$\chi\$ is the `order`, \$s\$ is \$2\$ if `symmetric` is `True` and \$1\$ oterhwise, \$k\_\{j}\$ are the `trotter_steps`, and \$x\$ are the variables to solve for. The indices \$i\$ and \$j\$ start at \$0\$. + + Here is an example: + + ```python + >>> from qiskit_addon_mpf.static import setup_lse + >>> lse = setup_lse([1,2,3], order=2, symmetric=True) + >>> print(lse.A) + [[1. 1. 1. ] + [1. 0.25 0.11111111] + [1. 0.0625 0.01234568]] + >>> print(lse.b) + [1. 0. 0.] + ``` + + **Parameters** + + * **trotter\_steps** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*] |* [*Parameter*](https://www.cvxpy.org/api_reference/cvxpy.expressions.html#cvxpy.expressions.constants.parameter.Parameter "(in CVXPY v1.5)")) – the sequence of trotter steps from which to build \$A\$. Rather than a list of integers, this may also be a [`Parameter`](https://www.cvxpy.org/api_reference/cvxpy.expressions.html#cvxpy.expressions.constants.parameter.Parameter "(in CVXPY v1.5)") instance of the desired size. In this case, the constructed [`LSE`](#qiskit_addon_mpf.static.LSE "qiskit_addon_mpf.static.LSE") is parameterized whose values must be assigned before it can be solved. + * **order** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – the order of the individual product formulas making up the MPF. + * **symmetric** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – whether the individual product formulas making up the MPF are symmetric. For example, the Lie-Trotter formula is not symmetric, while Suzuki-Trotter is. + + **Returns** + + An [`LSE`](#qiskit_addon_mpf.static.LSE "qiskit_addon_mpf.static.LSE"). + + **Return type** + + [*LSE*](#qiskit_addon_mpf.static.LSE "qiskit_addon_mpf.static.lse.LSE") + ## Exact static MPF coefficients -| | | -| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`setup_exact_model`](static-setup-exact-model "qiskit_addon_mpf.static.setup_exact_model") | Construct a [`cvxpy.Problem`](https://www.cvxpy.org/api_reference/cvxpy.problems.html#cvxpy.Problem "(in CVXPY v1.5)") for finding exact static MPF coefficients. | +### setup\_exact\_model + + + Construct a [`cvxpy.Problem`](https://www.cvxpy.org/api_reference/cvxpy.problems.html#cvxpy.Problem "(in CVXPY v1.5)") for finding exact static MPF coefficients. + + + The coefficients found via this optimization problem will be identical to the analytical ones obtained from the [`LSE.solve()`](#qiskit_addon_mpf.static.LSE.solve "qiskit_addon_mpf.static.LSE.solve") method. This additional interface exists to highlight the parallel to the [`setup_approximate_model()`](#qiskit_addon_mpf.static.setup_approximate_model "qiskit_addon_mpf.static.setup_approximate_model") interface. It also serves educational purposes for how-to approach optimization problems targeting MPF coefficients. + + + The optimization problem constructed by this class is defined as follows: + + * the cost function minimizes the L1-norm ([`norm1`](https://www.cvxpy.org/api_reference/cvxpy.atoms.other_atoms.html#cvxpy.atoms.norm1.norm1 "(in CVXPY v1.5)")) of the variables ([`LSE.x`](#qiskit_addon_mpf.static.LSE.x "qiskit_addon_mpf.static.LSE.x")) + + * the constraints correspond to each equation of the [`LSE`](#qiskit_addon_mpf.static.LSE "qiskit_addon_mpf.static.LSE"): + +$$ +\sum_j A_{ij} x_j = b_i +$$ + + Here is an example: + + ```python + >>> from qiskit_addon_mpf.static import setup_lse, setup_exact_model + >>> lse = setup_lse([1,2,3], order=2, symmetric=True) + >>> problem, coeffs = setup_exact_model(lse) + >>> print(problem) + minimize norm1(x) + subject to Sum([1. 1. 1.] @ x, None, False) == 1.0 + Sum([1. 0.25 0.11111111] @ x, None, False) == 0.0 + Sum([1. 0.0625 0.01234568] @ x, None, False) == 0.0 + ``` + + You can then solve the problem and extract the expansion coefficients like so: + + ```python + >>> final_cost = problem.solve() + >>> print(coeffs.value) + [ 0.04166667 -1.06666667 2.025 ] + ``` + + **Parameters** + + **lse** ([*LSE*](#qiskit_addon_mpf.static.LSE "qiskit_addon_mpf.static.lse.LSE")) – the linear system of equations from which to build the model. + + **Returns** + + The optimization problem and coefficients variable. + + **Return type** + + [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*Problem*](https://www.cvxpy.org/api_reference/cvxpy.problems.html#cvxpy.Problem "(in CVXPY v1.5)"), [*Variable*](https://www.cvxpy.org/api_reference/cvxpy.expressions.html#cvxpy.expressions.variable.Variable "(in CVXPY v1.5)")] + + **References** + + **\[1]: A. Carrera Vazquez et al., Quantum 7, 1067 (2023).** + + [https://quantum-journal.org/papers/q-2023-07-25-1067/](https://quantum-journal.org/papers/q-2023-07-25-1067/) + ## Approximate static MPF coefficients -| | | -| ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`setup_approximate_model`](static-setup-approximate-model "qiskit_addon_mpf.static.setup_approximate_model") | Construct a [`cvxpy.Problem`](https://www.cvxpy.org/api_reference/cvxpy.problems.html#cvxpy.Problem "(in CVXPY v1.5)") for finding approximate static MPF coefficients. | +### setup\_approximate\_model + + + Construct a [`cvxpy.Problem`](https://www.cvxpy.org/api_reference/cvxpy.problems.html#cvxpy.Problem "(in CVXPY v1.5)") for finding approximate static MPF coefficients. + + The optimization problem constructed by this class is defined as follows: + + * the cost function minimizes the sum of squares ([`sum_squares()`](https://www.cvxpy.org/api_reference/cvxpy.atoms.other_atoms.html#cvxpy.atoms.sum_squares.sum_squares "(in CVXPY v1.5)")) of the distances to an exact solution for all equations of the [`LSE`](#qiskit_addon_mpf.static.LSE "qiskit_addon_mpf.static.LSE"): + +$$ +\sum_i \left( \sum_j A_{ij} x_j - b_i \right)^2 +$$ + + * two constraints are set: + + 1. the variables must sum to 1: $\sum_i x_i == 1$ + 2. the L1-norm ([`norm1`](https://www.cvxpy.org/api_reference/cvxpy.atoms.other_atoms.html#cvxpy.atoms.norm1.norm1 "(in CVXPY v1.5)")) of the variables is bounded by `max_l1_norm` + + Here is an example: + + ```python + >>> from qiskit_addon_mpf.static import setup_lse, setup_approximate_model + >>> lse = setup_lse([1,2,3], order=2, symmetric=True) + >>> problem, coeffs = setup_approximate_model(lse, max_l1_norm=3.0) + >>> print(problem) + minimize quad_over_lin(Vstack([1. 1. 1.] @ x + -1.0, + [1. 0.25 0.11111111] @ x + -0.0, + [1. 0.0625 0.01234568] @ x + -0.0), 1.0) + subject to Sum(x, None, False) == 1.0 + norm1(x) <= 3.0 + ``` + + You can then solve the problem and extract the expansion coefficients like so: + + ```python + >>> final_cost = problem.solve() + >>> print(coeffs.value) + [ 0.03513467 -1. 1.96486533] + ``` + + **Parameters** + + * **lse** ([*LSE*](#qiskit_addon_mpf.static.LSE "qiskit_addon_mpf.static.lse.LSE")) – the linear system of equations from which to build the model. + * **max\_l1\_norm** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – the upper limit to use for the constrain of the L1-norm of the variables. + + **Returns** + + The optimization problem and coefficients variable. + + **Return type** + + [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*Problem*](https://www.cvxpy.org/api_reference/cvxpy.problems.html#cvxpy.Problem "(in CVXPY v1.5)"), [*Variable*](https://www.cvxpy.org/api_reference/cvxpy.expressions.html#cvxpy.expressions.variable.Variable "(in CVXPY v1.5)")] + + **References** + + **\[1]: S. Zhuk et al., arXiv:2306.12569 (2023).** + + [https://arxiv.org/abs/2306.12569](https://arxiv.org/abs/2306.12569) + + diff --git a/docs/api/qiskit-addon-obp/_toc.json b/docs/api/qiskit-addon-obp/_toc.json index 6eee3efbef1..b436b22bad4 100644 --- a/docs/api/qiskit-addon-obp/_toc.json +++ b/docs/api/qiskit-addon-obp/_toc.json @@ -5,6 +5,43 @@ "title": "API index", "url": "/api/qiskit-addon-obp" }, + { + "title": "qiskit_addon_obp", + "url": "/api/qiskit-addon-obp/qiskit-addon-obp" + }, + { + "title": "qiskit_addon_obp.utils.metadata", + "children": [ + { + "title": "Module overview", + "url": "/api/qiskit-addon-obp/utils-metadata" + }, + { + "title": "OBPMetadata", + "url": "/api/qiskit-addon-obp/utils-metadata-obp-metadata" + }, + { + "title": "SliceMetadata", + "url": "/api/qiskit-addon-obp/utils-metadata-slice-metadata" + } + ] + }, + { + "title": "qiskit_addon_obp.utils.operations", + "url": "/api/qiskit-addon-obp/utils-operations" + }, + { + "title": "qiskit_addon_obp.utils.simplify", + "url": "/api/qiskit-addon-obp/utils-simplify" + }, + { + "title": "qiskit_addon_obp.utils.truncating", + "url": "/api/qiskit-addon-obp/utils-truncating" + }, + { + "title": "qiskit_addon_obp.utils.visualization", + "url": "/api/qiskit-addon-obp/utils-visualization" + }, { "title": "Release notes", "url": "/api/qiskit-addon-obp/release-notes" diff --git a/docs/api/qiskit-addon-obp/backpropagate.mdx b/docs/api/qiskit-addon-obp/backpropagate.mdx deleted file mode 100644 index 86e3ebdca75..00000000000 --- a/docs/api/qiskit-addon-obp/backpropagate.mdx +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: backpropagate -description: API reference for qiskit_addon_obp.backpropagate -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_obp.backpropagate ---- - -# 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. - - The stopping criteria are values which constrain how large the observable may grow during backpropagation. These may be specified via the `operator_budget` optional argument. Refer to the [`OperatorBudget`](utils-simplify-operator-budget "qiskit_addon_obp.utils.simplify.OperatorBudget") class for more details. - - During backpropagation, users may truncate low-weight terms from the output observables, potentially reducing the number of experiments needed to run on the QPU. Truncating observable terms results in expectation value error proportional to the weights of the truncated terms. Users may specify how aggressively to truncate by providing a [`TruncationErrorBudget`](utils-truncating-truncation-error-budget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget") to the `truncation_error_budget` argument. Refer to the [`setup_budget()`](utils-truncating-setup-budget "qiskit_addon_obp.utils.truncating.setup_budget") documentation for more details. - - - The `max_seconds` argument is not available on Windows! - - - **Parameters** - - * **observables** ([*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")*\[*[*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)")*]*) – The observable(s) onto which the circuit is backpropagated. - * **slices** ([*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")*\[*[*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")*]*) – 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`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)"). - * **truncation\_error\_budget** ([*TruncationErrorBudget*](utils-truncating-truncation-error-budget "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-operator-budget "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-operator-budget "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 "(in Python v3.13)") *| 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. - - **Returns** - - * The backpropagated observables. - * The slices which were not absorbed into the observable during backpropagation. - * A metadata container. - - **Raises** - - * [**RuntimeError**](https://docs.python.org/3/library/exceptions.html#RuntimeError "(in Python v3.13)") – If the `max_seconds` argument is attempted to be used on Windows. - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – All observables and slices must act on equivalent numbers of qubits. - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – An input observable is larger than the constraints specified by `operator_budget`. - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – `operator_budget.max_paulis` or `operator_budget.max_qwc_groups` is less than 1. - - **Return type** - - [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")\[[*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)")], [*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")\[[*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")], [*OBPMetadata*](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")] - - diff --git a/docs/api/qiskit-addon-obp/index.mdx b/docs/api/qiskit-addon-obp/index.mdx new file mode 100644 index 00000000000..22cb3b208c4 --- /dev/null +++ b/docs/api/qiskit-addon-obp/index.mdx @@ -0,0 +1,10 @@ + + +# `qiskit-addon-obp` API reference + +* [Operator backpropagation (`qiskit_addon_obp`)](qiskit-addon-obp) +* [Metadata utilities (`qiskit_addon_obp.utils.metadata`)](utils-metadata) +* [Operator utilities (`qiskit_addon_obp.utils.operations`)](utils-operations) +* [Pauli operator simplification (`qiskit_addon_obp.utils.simplify`)](utils-simplify) +* [Truncation utilities (`qiskit_addon_obp.utils.truncating`)](utils-truncating) +* [Visualization utilities (`qiskit_addon_obp.utils.visualization`)](utils-visualization) diff --git a/docs/api/qiskit-addon-obp/qiskit-addon-obp.mdx b/docs/api/qiskit-addon-obp/qiskit-addon-obp.mdx index 34d77d85800..2961e2c8cea 100644 --- a/docs/api/qiskit-addon-obp/qiskit-addon-obp.mdx +++ b/docs/api/qiskit-addon-obp/qiskit-addon-obp.mdx @@ -1,17 +1,59 @@ -# Qiskit addon: operator backpropagation (OBP) +--- +title: qiskit_addon_obp +description: API reference for qiskit_addon_obp +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_addon_obp +--- - + + +# Operator backpropagation + +`qiskit_addon_obp` Main operator backpropagation functionality. -| | | -| ----------------------------------------------------------------- | --------------------------------------------------------------------------------- | -| [`backpropagate`](backpropagate "qiskit_addon_obp.backpropagate") | Backpropagate slices of quantum circuit operations onto the provided observables. | +### 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. + + The stopping criteria are values which constrain how large the observable may grow during backpropagation. These may be specified via the `operator_budget` optional argument. Refer to the [`OperatorBudget`](utils-simplify#operatorbudget "qiskit_addon_obp.utils.simplify.OperatorBudget") class for more details. + + During backpropagation, users may truncate low-weight terms from the output observables, potentially reducing the number of experiments needed to run on the QPU. Truncating observable terms results in expectation value error proportional to the weights of the truncated terms. Users may specify how aggressively to truncate by providing a [`TruncationErrorBudget`](utils-truncating#truncationerrorbudget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget") to the `truncation_error_budget` argument. Refer to the [`setup_budget()`](utils-truncating#setup_budget "qiskit_addon_obp.utils.truncating.setup_budget") documentation for more details. + + + The `max_seconds` argument is not available on Windows! + + + **Parameters** + + * **observables** ([*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")*\[*[*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)")*]*) – The observable(s) onto which the circuit is backpropagated. + * **slices** ([*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")*\[*[*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")*]*) – 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`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)"). + * **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 "(in Python v3.13)") *| 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. + + **Returns** + + * The backpropagated observables. + * The slices which were not absorbed into the observable during backpropagation. + * A metadata container. + + **Raises** + + * [**RuntimeError**](https://docs.python.org/3/library/exceptions.html#RuntimeError "(in Python v3.13)") – If the `max_seconds` argument is attempted to be used on Windows. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – All observables and slices must act on equivalent numbers of qubits. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – An input observable is larger than the constraints specified by `operator_budget`. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – `operator_budget.max_paulis` or `operator_budget.max_qwc_groups` is less than 1. + + **Return type** -## Submodules + [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")\[[*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)")], [*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")\[[*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")], [*OBPMetadata*](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")] + -| | | -| ----------------------------------------------------------------------- | -------------------------------------------------------------- | -| [`utils`](utils#module-qiskit_addon_obp.utils "qiskit_addon_obp.utils") | Utility functionality for conducting operator backpropagation. | diff --git a/docs/api/qiskit-addon-obp/release-notes.mdx b/docs/api/qiskit-addon-obp/release-notes.mdx index 723a31414c9..1c3bca278e2 100644 --- a/docs/api/qiskit-addon-obp/release-notes.mdx +++ b/docs/api/qiskit-addon-obp/release-notes.mdx @@ -20,19 +20,19 @@ in_page_toc_max_heading_level: 2 ### New Features -* Added a [`OperatorBudget`](utils-simplify-operator-budget "qiskit_addon_obp.utils.simplify.OperatorBudget") class for specifying how large an operator may grow during back-propagation. +* Added a [`OperatorBudget`](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()`](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()`](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-truncation-error-budget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget"), for holding information about the observable truncation strategy. +* 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 function, [`setup_budget()`](utils-truncating-setup-budget "qiskit_addon_obp.utils.truncating.setup_budget"), which generates a [`TruncationErrorBudget`](utils-truncating-truncation-error-budget "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()`](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`). ### Upgrade Notes -* The [`backpropagate()`](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-operator-budget "qiskit_addon_obp.utils.simplify.OperatorBudget") instance. +* 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. To migrate, change this code @@ -58,7 +58,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()`](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()`](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()`](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. For example @@ -75,7 +75,7 @@ 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()`](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`. @@ -93,17 +93,17 @@ 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()`](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-truncation-error-budget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget") instance. +* 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 `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-truncation-error-budget "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. ### 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()`](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()`](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()`](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). 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 d7e2fae61b9..068cd65ac66 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 "(in Python v3.13)") A container for metadata generated during the `backpropagate()` method. @@ -53,12 +53,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-truncation-error-budget#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`](utils-truncating#TruncationErrorBudget.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. @@ -80,7 +80,7 @@ python_api_name: qiskit_addon_obp.utils.metadata.OBPMetadata ### from\_json - + Load a metadata from a json file. **Parameters** @@ -98,12 +98,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-truncation-error-budget#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`](utils-truncating#TruncationErrorBudget.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. @@ -129,7 +129,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 4d16a84d544..2b2ffb5ef4d 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 "(in Python v3.13)") A container for metadata generated during the backpropagation of a single slice. @@ -63,7 +63,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-truncation-error-budget#p_norm "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.p_norm")! + This sum is *not* affected by the value of [`p_norm`](utils-truncating#TruncationErrorBudget.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 e00af07a4ee..cf346a1e0e9 100644 --- a/docs/api/qiskit-addon-obp/utils-metadata.mdx +++ b/docs/api/qiskit-addon-obp/utils-metadata.mdx @@ -1,8 +1,18 @@ -# metadata +--- +title: metadata +description: API reference for qiskit_addon_obp.utils.metadata +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_addon_obp.utils.metadata +--- - + + +# Metadata utilities + +`qiskit_addon_obp.utils.metadata` Container classes for holding backpropagation metadata. @@ -10,3 +20,4 @@ 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. | + diff --git a/docs/api/qiskit-addon-obp/utils-operations-apply-op-to.mdx b/docs/api/qiskit-addon-obp/utils-operations-apply-op-to.mdx deleted file mode 100644 index 0d18de11372..00000000000 --- a/docs/api/qiskit-addon-obp/utils-operations-apply-op-to.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: apply_op_to -description: API reference for qiskit_addon_obp.utils.operations.apply_op_to -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_obp.utils.operations.apply_op_to ---- - - - -# 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)`. - - By default, this function applies `op1` to `op2` in the following way: - - > `op2 @ op1` - - By setting `apply_as_transform=True`, this function will apply `op1` to `op2` in the following way: - - > `op2.adjoint() @ op1 @ op2` - - **Parameters** - - * **op1** ([*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)")) – The operator on which `op2` will be applied. - * **op1\_qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit indices for `op1`. - * **op2** ([*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)")) – The operator to apply to `op1`. - * **op2\_qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit indices for `op2`. - * **apply\_as\_transform** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – Whether to apply `op2` to `op1` as a transformation. - - **Returns** - - The tuple `(op, qargs)` where `op` is the input `op1` with `op2` left-applied and `qargs` is a list of qubit indices for the new operator `op`. The qubit IDs in the output `op` correspond to the global qubit ID in the same index in `qargs`. - - For example, if the output `op` is a `SparsePauliOp("YX")` and `qargs` is \[3, 4], the X term on qubit 0 of the operator corresponds to global qubit ID 3. - - **Raises** - - [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The number of unique operator qargs must match the number of qubits in the corresponding operator. - - **Return type** - - [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)"), [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")]] - - diff --git a/docs/api/qiskit-addon-obp/utils-operations-reduce-op.mdx b/docs/api/qiskit-addon-obp/utils-operations-reduce-op.mdx deleted file mode 100644 index 5964aac6caf..00000000000 --- a/docs/api/qiskit-addon-obp/utils-operations-reduce-op.mdx +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: reduce_op -description: API reference for qiskit_addon_obp.utils.operations.reduce_op -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_obp.utils.operations.reduce_op ---- - - - -# 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. - - ## For example: - - ```python - >>> global_op = SparsePauliOp(["IXI", "IIZ"]) - >>> reduced_op, qargs = reduce_op(global_op) - >>> reduced_op - SparsePauliOp(['XI', 'IZ'], - coeffs=[1.+0.j, 1.+0.j]) - >>> qargs - [0, 1] - ``` - - **Parameters** - - **global\_op** ([*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)")) – The global operator for which to generate a lean representation - - **Returns** - - * A lean representation of the input operator with qubits associated solely with identity terms removed. - * A list of indices specifying the qubits on which the lean operator acts. - - **Raises** - - [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Input operator may not be the identity operator. - - **Return type** - - [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)"), [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")]] - - diff --git a/docs/api/qiskit-addon-obp/utils-operations-to-global-op.mdx b/docs/api/qiskit-addon-obp/utils-operations-to-global-op.mdx deleted file mode 100644 index e8af6f5a9e3..00000000000 --- a/docs/api/qiskit-addon-obp/utils-operations-to-global-op.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: to_global_op -description: API reference for qiskit_addon_obp.utils.operations.to_global_op -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_obp.utils.operations.to_global_op ---- - - - -# to\_global\_op - - - Convert a local operator to a global operator by inserting identities on qubits which aren’t used. - - **Parameters** - - * **op** ([*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)")) – Local operator to expand. - * **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – Qubit indices for local operator. - * **n\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – Number of qubits in the global system. - - **Returns** - - An operator on `n_qubits` qubits - - **Raises** - - [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Qubit ID out of range - - **Return type** - - [*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)") - - diff --git a/docs/api/qiskit-addon-obp/utils-operations.mdx b/docs/api/qiskit-addon-obp/utils-operations.mdx index c592a229b46..86c4c384644 100644 --- a/docs/api/qiskit-addon-obp/utils-operations.mdx +++ b/docs/api/qiskit-addon-obp/utils-operations.mdx @@ -1,13 +1,143 @@ -# operations +--- +title: operations +description: API reference for qiskit_addon_obp.utils.operations +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_addon_obp.utils.operations +--- - + + +# Operator utilities + +`qiskit_addon_obp.utils.operations` Utility functions for operator backpropagation. -| | | -| ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | -| [`apply_op_to`](utils-operations-apply-op-to "qiskit_addon_obp.utils.operations.apply_op_to") | Apply the operator `op2` to the operator `op1`. | -| [`to_global_op`](utils-operations-to-global-op "qiskit_addon_obp.utils.operations.to_global_op") | Convert a local operator to a global operator by inserting identities on qubits which aren't used. | -| [`reduce_op`](utils-operations-reduce-op "qiskit_addon_obp.utils.operations.reduce_op") | Create a lean representation of a global Pauli operator. | +### 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)`. + + By default, this function applies `op1` to `op2` in the following way: + + > `op2 @ op1` + + By setting `apply_as_transform=True`, this function will apply `op1` to `op2` in the following way: + + > `op2.adjoint() @ op1 @ op2` + + **Parameters** + + * **op1** ([*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)")) – The operator on which `op2` will be applied. + * **op1\_qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit indices for `op1`. + * **op2** ([*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)")) – The operator to apply to `op1`. + * **op2\_qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit indices for `op2`. + * **apply\_as\_transform** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – Whether to apply `op2` to `op1` as a transformation. + + **Returns** + + The tuple `(op, qargs)` where `op` is the input `op1` with `op2` left-applied and `qargs` is a list of qubit indices for the new operator `op`. The qubit IDs in the output `op` correspond to the global qubit ID in the same index in `qargs`. + + For example, if the output `op` is a `SparsePauliOp("YX")` and `qargs` is \[3, 4], the X term on qubit 0 of the operator corresponds to global qubit ID 3. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The number of unique operator qargs must match the number of qubits in the corresponding operator. + + **Return type** + + [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)"), [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")]] + + +### apply\_reset\_to + + + Apply a reset operation to a Pauli operator. + + This function applies a reset operation to `op` in the following way: + + > `<0|op|0>` + + Terms containing Pauli X or Y terms on qubit-`qubit_id` will have their weight reduced to `0.0`. Terms containing Pauli Z on `qubit_id` will have that Pauli Z replaced by an identity. + + **Parameters** + + * **op** ([*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)")) – The operator to which the reset will be applied. + * **qubit\_id** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The index of the qubit on which to apply the reset. + * **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – Whether to modify the operator in-place. + + **Returns** + + The transformed operator + + **Return type** + + [*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)") + + +### to\_global\_op + + + Convert a local operator to a global operator by inserting identities on qubits which aren’t used. + + **Parameters** + + * **op** ([*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)")) – Local operator to expand. + * **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – Qubit indices for local operator. + * **n\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – Number of qubits in the global system. + + **Returns** + + An operator on `n_qubits` qubits + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Qubit ID out of range + + **Return type** + + [*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)") + + +### 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. + + **For example:** + + ```python + >>> global_op = SparsePauliOp(["IXI", "IIZ"]) + >>> reduced_op, qargs = reduce_op(global_op) + >>> reduced_op + SparsePauliOp(['XI', 'IZ'], + coeffs=[1.+0.j, 1.+0.j]) + >>> qargs + [0, 1] + ``` + + **Parameters** + + **global\_op** ([*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)")) – The global operator for which to generate a lean representation + + **Returns** + + * A lean representation of the input operator with qubits associated solely with identity terms removed. + * A list of indices specifying the qubits on which the lean operator acts. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Input operator may not be the identity operator. + + **Return type** + + [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)"), [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")]] + + diff --git a/docs/api/qiskit-addon-obp/utils-simplify-operator-budget.mdx b/docs/api/qiskit-addon-obp/utils-simplify-operator-budget.mdx deleted file mode 100644 index 6decb16b4ed..00000000000 --- a/docs/api/qiskit-addon-obp/utils-simplify-operator-budget.mdx +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: OperatorBudget -description: API reference for qiskit_addon_obp.utils.simplify.OperatorBudget -in_page_toc_min_heading_level: 1 -python_api_type: class -python_api_name: qiskit_addon_obp.utils.simplify.OperatorBudget ---- - -# OperatorBudget - - - Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.13)") - - A class for storing the constants that determine how large an operator may grow. - - Backpropagation will stop if either of the following conditions is met: - - * The number of Pauli terms across all of the observables exceeds `max_paulis`. When `max_paulis = None`, the number of Pauli terms in the observables is not constrained. - * The number of qubit-wise commuting Pauli groups across all of the observables exceed `max_qwc_groups`. When `max_qwc_groups = None`, the number of qubit-wise commuting Pauli groups in the observables is not constrained. - - ## Attributes - - ### max\_paulis - - - The maximum number of Pauli terms the backpropagated operator may contain. - - - ### max\_qwc\_groups - - - The maximum number of qubit-wise commuting Pauli groups the backpropagated operator may contain. - - - ### simplify - - - A flag denoting whether to call [`simplify()`](utils-simplify-simplify "qiskit_addon_obp.utils.simplify.simplify") at every iteration. - - - ## Methods - - ### is\_active - - - Return whether `self` places any bounds on operator size. - - **Return type** - - [bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)") - - - diff --git a/docs/api/qiskit-addon-obp/utils-simplify-simplify-metadata.mdx b/docs/api/qiskit-addon-obp/utils-simplify-simplify-metadata.mdx deleted file mode 100644 index 55199ec2367..00000000000 --- a/docs/api/qiskit-addon-obp/utils-simplify-simplify-metadata.mdx +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: SimplifyMetadata -description: API reference for qiskit_addon_obp.utils.simplify.SimplifyMetadata -in_page_toc_min_heading_level: 1 -python_api_type: class -python_api_name: qiskit_addon_obp.utils.simplify.SimplifyMetadata ---- - -# SimplifyMetadata - - - Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.13)") - - A simple dataclass for returning the tracked attributes during operator simplification. - - ## Attributes - - ### num\_unique\_paulis - - - The number of unique Pauli terms. See also `num_unique_paulis`. - - - ### num\_duplicate\_paulis - - - The number of duplicate Pauli terms. See also `num_duplicate_paulis`. - - - ### num\_trimmed\_paulis - - - The number of trimmed Pauli terms. See also `num_trimmed_paulis`. - - - ### sum\_trimmed\_coeffs - - - The sum of the trimmed coefficients. See also `sum_trimmed_coeffs`. - - - diff --git a/docs/api/qiskit-addon-obp/utils-simplify-simplify.mdx b/docs/api/qiskit-addon-obp/utils-simplify-simplify.mdx deleted file mode 100644 index c7079dc364f..00000000000 --- a/docs/api/qiskit-addon-obp/utils-simplify-simplify.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: simplify -description: API reference for qiskit_addon_obp.utils.simplify.simplify -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_obp.utils.simplify.simplify ---- - -# simplify - - - Simplifies the provided Pauli operator. - - This is an adaption of `SparsePauliOp.simplify()` which tracks metadata of the simplified terms. - - **Parameters** - - * **operator** ([*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)")) – the `SparsePauliOp` to simplify. - * **atol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)") *| None*) – the absolute tolerance for checking if coefficients are zero. If `None`, this will fallback to using `SparsePauliOp.atol`. - * **rtol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)") *| None*) – the relative tolerance for checking if coefficients are zero. If `None`, this will fallback to using `SparsePauliOp.rtol`. - - **Returns** - - The simplified Pauli operator. - - **Return type** - - [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)"), [*SimplifyMetadata*](utils-simplify-simplify-metadata "qiskit_addon_obp.utils.simplify.SimplifyMetadata")] - - diff --git a/docs/api/qiskit-addon-obp/utils-simplify.mdx b/docs/api/qiskit-addon-obp/utils-simplify.mdx index d91f8975401..0da4407cd24 100644 --- a/docs/api/qiskit-addon-obp/utils-simplify.mdx +++ b/docs/api/qiskit-addon-obp/utils-simplify.mdx @@ -1,13 +1,109 @@ -# simplify +--- +title: simplify +description: API reference for qiskit_addon_obp.utils.simplify +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_addon_obp.utils.simplify +--- - + + +# Pauli operator simplification + +`qiskit_addon_obp.utils.simplify` Functions for simplifying Pauli operators. -| | | -| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | -| [`OperatorBudget`](utils-simplify-operator-budget "qiskit_addon_obp.utils.simplify.OperatorBudget") | A class for storing the constants that determine how large an operator may grow. | -| [`SimplifyMetadata`](utils-simplify-simplify-metadata "qiskit_addon_obp.utils.simplify.SimplifyMetadata") | A simple dataclass for returning the tracked attributes during operator simplification. | -| [`simplify`](utils-simplify-simplify "qiskit_addon_obp.utils.simplify.simplify") | Simplifies the provided Pauli operator. | +### OperatorBudget + + + A class for storing the constants that determine how large an operator may grow. + + Backpropagation will stop if either of the following conditions is met: + + * The number of Pauli terms across all of the observables exceeds `max_paulis`. When `max_paulis = None`, the number of Pauli terms in the observables is not constrained. + * The number of qubit-wise commuting Pauli groups across all of the observables exceed `max_qwc_groups`. When `max_qwc_groups = None`, the number of qubit-wise commuting Pauli groups in the observables is not constrained. + + #### max\_paulis + + + The maximum number of Pauli terms the backpropagated operator may contain. + + + #### max\_qwc\_groups + + + The maximum number of qubit-wise commuting Pauli groups the backpropagated operator may contain. + + + #### simplify + + + A flag denoting whether to call [`simplify()`](#qiskit_addon_obp.utils.simplify.simplify "qiskit_addon_obp.utils.simplify.simplify") at every iteration. + + + #### is\_active + + + Return whether `self` places any bounds on operator size. + + **Return type** + + [bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)") + + + +### SimplifyMetadata + + + A simple dataclass for returning the tracked attributes during operator simplification. + + #### num\_unique\_paulis + + + The number of unique Pauli terms. See also `num_unique_paulis`. + + + #### num\_duplicate\_paulis + + + The number of duplicate Pauli terms. See also `num_duplicate_paulis`. + + + #### num\_trimmed\_paulis + + + The number of trimmed Pauli terms. See also `num_trimmed_paulis`. + + + #### sum\_trimmed\_coeffs + + + The sum of the trimmed coefficients. See also `sum_trimmed_coeffs`. + + + +### simplify + + + Simplifies the provided Pauli operator. + + This is an adaption of `SparsePauliOp.simplify()` which tracks metadata of the simplified terms. + + **Parameters** + + * **operator** ([*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)")) – the `SparsePauliOp` to simplify. + * **atol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)") *| None*) – the absolute tolerance for checking if coefficients are zero. If `None`, this will fallback to using `SparsePauliOp.atol`. + * **rtol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)") *| None*) – the relative tolerance for checking if coefficients are zero. If `None`, this will fallback to using `SparsePauliOp.rtol`. + + **Returns** + + The simplified Pauli operator. + + **Return type** + + [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)"), [*SimplifyMetadata*](#qiskit_addon_obp.utils.simplify.SimplifyMetadata "qiskit_addon_obp.utils.simplify.SimplifyMetadata")] + + diff --git a/docs/api/qiskit-addon-obp/utils-truncating-setup-budget.mdx b/docs/api/qiskit-addon-obp/utils-truncating-setup-budget.mdx deleted file mode 100644 index 91270403ed2..00000000000 --- a/docs/api/qiskit-addon-obp/utils-truncating-setup-budget.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: setup_budget -description: API reference for qiskit_addon_obp.utils.truncating.setup_budget -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_obp.utils.truncating.setup_budget ---- - - - -# setup\_budget - - - Calculate the budget available to each slice for observable term truncation. - - This method makes the construction of a [`TruncationErrorBudget`](utils-truncating-truncation-error-budget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget") easier for an end-user. This error budget can be provided to the [`backpropagate()`](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. - - ## The construction logic is as follows: - - * if `max_error_per_slice` is provided its value is converted to a list and used immediately for [`TruncationErrorBudget.per_slice_budget`](utils-truncating-truncation-error-budget#per_slice_budget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.per_slice_budget") - * if the above is not the case, `max_error_total` has to be set - * if `num_slices` is **not** set,:attr:.TruncationErrorBudget.per\_slice\_budget gets set to `[max_error_total]` resulting in the entire budget being consumed **greedily** - * however, if `num_slices` is provided, then [`TruncationErrorBudget.per_slice_budget`](utils-truncating-truncation-error-budget#per_slice_budget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.per_slice_budget") assumes an even distribution of the maximum total error across the specified number of slices: `[max_error_total / num_slices]` - - Finally, if `max_error_total` is set, this puts a hard limit on the total maximum error to be accumulated throughout the entire backpropagation. Thus, setting `max_error_per_slice` and `max_error_total` can be of value. - - - Budget not spent during a previous iteration will carry over into subsequent iterations, meaning that the maximum budget for any slice during backpropagation may in fact exceed [`TruncationErrorBudget.per_slice_budget`](utils-truncating-truncation-error-budget#per_slice_budget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.per_slice_budget"). - - - **Parameters** - - * **max\_error\_per\_slice** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")*] | None*) – Specifies the maximum error per backpropagated slice. See above for more details. - * **max\_error\_total** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)") *| None*) – Specifies the total maximum error for the entire backpropagation. See above for more details. - * **num\_slices** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| None*) – The number of slices over which to distribute the budget. See above for more details. - * **p\_norm** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The Lp norm of the error. This affects the gradual distribution of `max_error_total` in the case of `num_slices` also being set (see above). Refer to the [how-to guide](https://qiskit.github.io/qiskit-addon-obp/how_tos/bound_error_using_p_norm.html) for a detailed conversation on bounding truncation error using higher Lp-norms. - - **Returns** - - The resulting [`TruncationErrorBudget`](utils-truncating-truncation-error-budget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget"). - - **Raises** - - [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – if `max_error_per_slice` and `max_error_total` are both `None`. - - **Return type** - - [*TruncationErrorBudget*](utils-truncating-truncation-error-budget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget") - - diff --git a/docs/api/qiskit-addon-obp/utils-truncating-truncate-binary-search.mdx b/docs/api/qiskit-addon-obp/utils-truncating-truncate-binary-search.mdx deleted file mode 100644 index 73f840816d3..00000000000 --- a/docs/api/qiskit-addon-obp/utils-truncating-truncate-binary-search.mdx +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: truncate_binary_search -description: API reference for qiskit_addon_obp.utils.truncating.truncate_binary_search -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_obp.utils.truncating.truncate_binary_search ---- - - - -# 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`. - - **Parameters** - - * **observable** ([*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)")) – the `SparsePauliOp` to truncate terms from. - * **budget** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – the maximum permissable truncation error. - * **p\_norm** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – an integer specifying what p-norm to use. - - **Returns** - - The truncated observable and a bound on the incurred truncation error. - - - The incurred truncation error bound, $E$, is calculated as the `p-norm` of the truncated terms’ coefficient magnitudes, $c$, such that $E = \|c\|_p$. - - - **Return type** - - [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)"), [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")] - - diff --git a/docs/api/qiskit-addon-obp/utils-truncating-truncation-error-budget.mdx b/docs/api/qiskit-addon-obp/utils-truncating-truncation-error-budget.mdx deleted file mode 100644 index 74e7425740c..00000000000 --- a/docs/api/qiskit-addon-obp/utils-truncating-truncation-error-budget.mdx +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: TruncationErrorBudget -description: API reference for qiskit_addon_obp.utils.truncating.TruncationErrorBudget -in_page_toc_min_heading_level: 1 -python_api_type: class -python_api_name: qiskit_addon_obp.utils.truncating.TruncationErrorBudget ---- - -# TruncationErrorBudget - - - Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.13)") - - A class for storing the constants that determine the truncation error budget. - - 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 operator terms during backpropagation and bounding the incurred error. - - ## Attributes - - ### max\_error\_total - - - The maximum total truncation error to allow for each observable during the entire backpropagation. This value may be [`numpy.inf`](https://numpy.org/doc/stable/reference/constants.html#numpy.inf "(in NumPy v2.1)"), for example when the maximum error was left unspecified during `setup_budget()`. - - - ### p\_norm - - - Indicates which Lp-norm is used for calculating truncation errors. - - Refer to the [how-to guide](https://qiskit.github.io/qiskit-addon-obp/how_tos/bound_error_using_p_norm.html) for a detailed conversation on bounding truncation error using higher Lp-norms. - - - ### per\_slice\_budget - - - The maximum amount of truncation error to allow per backpropagated slice. This list will be looped over during the backpropagation of the circuit slices. - - - ## Methods - - ### is\_active - - - Return whether the truncation is active, i.e. whether the budget is non-zero. - - **Return type** - - [bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)") - - - diff --git a/docs/api/qiskit-addon-obp/utils-truncating.mdx b/docs/api/qiskit-addon-obp/utils-truncating.mdx index 81829ecbb58..73b243f1122 100644 --- a/docs/api/qiskit-addon-obp/utils-truncating.mdx +++ b/docs/api/qiskit-addon-obp/utils-truncating.mdx @@ -1,13 +1,122 @@ -# truncating +--- +title: truncating +description: API reference for qiskit_addon_obp.utils.truncating +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_addon_obp.utils.truncating +--- - + + +# Truncation utilities + +`qiskit_addon_obp.utils.truncating` Functions for truncating Pauli operators within given error budgets. -| | | -| ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | -| [`TruncationErrorBudget`](utils-truncating-truncation-error-budget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget") | A class for storing the constants that determine the truncation error budget. | -| [`setup_budget`](utils-truncating-setup-budget "qiskit_addon_obp.utils.truncating.setup_budget") | Calculate the budget available to each slice for observable term truncation. | -| [`truncate_binary_search`](utils-truncating-truncate-binary-search "qiskit_addon_obp.utils.truncating.truncate_binary_search") | Perform binary search to find an optimal observable truncation threshold. | +### TruncationErrorBudget + + + A class for storing the constants that determine the truncation error budget. + + 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 operator terms during backpropagation and bounding the incurred error. + + #### per\_slice\_budget + + + The maximum amount of truncation error to allow per backpropagated slice. This list will be looped over during the backpropagation of the circuit slices. + + + #### max\_error\_total + + + The maximum total truncation error to allow for each observable during the entire backpropagation. This value may be [`numpy.inf`](https://numpy.org/doc/stable/reference/constants.html#numpy.inf "(in NumPy v2.1)"), for example when the maximum error was left unspecified during `setup_budget()`. + + + #### p\_norm + + + Indicates which Lp-norm is used for calculating truncation errors. + + Refer to the [how-to guide](https://qiskit.github.io/qiskit-addon-obp/how_tos/bound_error_using_p_norm.html) for a detailed conversation on bounding truncation error using higher Lp-norms. + + + #### is\_active + + + Return whether the truncation is active, i.e. whether the budget is non-zero. + + **Return type** + + [bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)") + + + +### 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. + + **The construction logic is as follows:** + + * if `max_error_per_slice` is provided its value is converted to a list and used immediately for [`TruncationErrorBudget.per_slice_budget`](#qiskit_addon_obp.utils.truncating.TruncationErrorBudget.per_slice_budget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.per_slice_budget") + * if the above is not the case, `max_error_total` has to be set + * if `num_slices` is **not** set,:attr:.TruncationErrorBudget.per\_slice\_budget gets set to `[max_error_total]` resulting in the entire budget being consumed **greedily** + * however, if `num_slices` is provided, then [`TruncationErrorBudget.per_slice_budget`](#qiskit_addon_obp.utils.truncating.TruncationErrorBudget.per_slice_budget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.per_slice_budget") assumes an even distribution of the maximum total error across the specified number of slices: `[max_error_total / num_slices]` + + Finally, if `max_error_total` is set, this puts a hard limit on the total maximum error to be accumulated throughout the entire backpropagation. Thus, setting `max_error_per_slice` and `max_error_total` can be of value. + + + Budget not spent during a previous iteration will carry over into subsequent iterations, meaning that the maximum budget for any slice during backpropagation may in fact exceed [`TruncationErrorBudget.per_slice_budget`](#qiskit_addon_obp.utils.truncating.TruncationErrorBudget.per_slice_budget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.per_slice_budget"). + + + **Parameters** + + * **max\_error\_per\_slice** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")*] | None*) – Specifies the maximum error per backpropagated slice. See above for more details. + * **max\_error\_total** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)") *| None*) – Specifies the total maximum error for the entire backpropagation. See above for more details. + * **num\_slices** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| None*) – The number of slices over which to distribute the budget. See above for more details. + * **p\_norm** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The Lp norm of the error. This affects the gradual distribution of `max_error_total` in the case of `num_slices` also being set (see above). Refer to the [how-to guide](https://qiskit.github.io/qiskit-addon-obp/how_tos/bound_error_using_p_norm.html) for a detailed conversation on bounding truncation error using higher Lp-norms. + + **Returns** + + The resulting [`TruncationErrorBudget`](#qiskit_addon_obp.utils.truncating.TruncationErrorBudget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget"). + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – if `max_error_per_slice` and `max_error_total` are both `None`. + + **Return type** + + [*TruncationErrorBudget*](#qiskit_addon_obp.utils.truncating.TruncationErrorBudget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget") + + +### 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`. + + **Parameters** + + * **observable** ([*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)")) – the `SparsePauliOp` to truncate terms from. + * **budget** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – the maximum permissable truncation error. + * **p\_norm** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – an integer specifying what p-norm to use. + + **Returns** + + The truncated observable and a bound on the incurred truncation error. + + + The incurred truncation error bound, $E$, is calculated as the `p-norm` of the truncated terms’ coefficient magnitudes, $c$, such that $E = \|c\|_p$. + + + **Return type** + + [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)"), [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")] + + diff --git a/docs/api/qiskit-addon-obp/utils-visualization-plot-accumulated-error.mdx b/docs/api/qiskit-addon-obp/utils-visualization-plot-accumulated-error.mdx deleted file mode 100644 index 15a306bb1a3..00000000000 --- a/docs/api/qiskit-addon-obp/utils-visualization-plot-accumulated-error.mdx +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: plot_accumulated_error -description: API reference for qiskit_addon_obp.utils.visualization.plot_accumulated_error -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_obp.utils.visualization.plot_accumulated_error ---- - - - -# 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. - - ```python - >>> from matplotlib import pyplot as plt - >>> from qiskit_addon_obp.utils.visualization import plot_accumulated_error - >>> fig, axes = plt.subplots(1, 1) - >>> plot_accumulated_error(metadata, axes) - ``` - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_accumulated\_error-2.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_accumulated_error-2.png) - - As you can see in the figure above, the number of backpropagated slices is displayed along the x-axis. You can think of this as the “time” of the backpropagation algorithm. The accumulated error due to truncated Pauli terms is displayed along the y-axis. If `OBPMetadata.truncation_error_budget.max_error_total` is not [`numpy.inf`](https://numpy.org/doc/stable/reference/constants.html#numpy.inf "(in NumPy v2.1)"), it is displayed as a red horizontal line. Each observable that was backpropagated, gets its own line. - - This data is related to the one visualized by [`plot_slice_errors()`](utils-visualization-plot-slice-errors "qiskit_addon_obp.utils.visualization.plot_slice_errors"). This method plots the cumulative sum of the slice errors along the x-axis. - - **Parameters** - - * **metadata** ([*OBPMetadata*](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. - * **axes** (*Axes*) – the matplotlib axes in which to plot. - - diff --git a/docs/api/qiskit-addon-obp/utils-visualization-plot-left-over-error-budget.mdx b/docs/api/qiskit-addon-obp/utils-visualization-plot-left-over-error-budget.mdx deleted file mode 100644 index 7471fe1d25c..00000000000 --- a/docs/api/qiskit-addon-obp/utils-visualization-plot-left-over-error-budget.mdx +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: plot_left_over_error_budget -description: API reference for qiskit_addon_obp.utils.visualization.plot_left_over_error_budget -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_obp.utils.visualization.plot_left_over_error_budget ---- - - - -# 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. - - ```python - >>> from matplotlib import pyplot as plt - >>> from qiskit_addon_obp.utils.visualization import plot_left_over_error_budget - >>> fig, axes = plt.subplots(1, 1) - >>> plot_left_over_error_budget(metadata, axes) - ``` - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_left\_over\_error\_budget-2\_00.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_left_over_error_budget-2_00.png) - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_left\_over\_error\_budget-2\_01.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_left_over_error_budget-2_01.png) - - As you can see in the figure above, the number of backpropagated slices is displayed along the x-axis. You can think of this as the “time” of the backpropagation algorithm. The left-over error budget available at each backpropagation step is displayed along the y-axis. Since each observable that was backpropagated has its own budget, they are plotted as separate lines. - - **Parameters** - - * **metadata** ([*OBPMetadata*](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. - * **axes** (*Axes*) – the matplotlib axes in which to plot. - - diff --git a/docs/api/qiskit-addon-obp/utils-visualization-plot-num-paulis.mdx b/docs/api/qiskit-addon-obp/utils-visualization-plot-num-paulis.mdx deleted file mode 100644 index 21de0f287de..00000000000 --- a/docs/api/qiskit-addon-obp/utils-visualization-plot-num-paulis.mdx +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: plot_num_paulis -description: API reference for qiskit_addon_obp.utils.visualization.plot_num_paulis -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_obp.utils.visualization.plot_num_paulis ---- - - - -# 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. - - ```python - >>> from matplotlib import pyplot as plt - >>> from qiskit_addon_obp.utils.visualization import plot_num_paulis - >>> fig, axes = plt.subplots(1, 1) - >>> plot_num_paulis(metadata, axes) - ``` - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_num\_paulis-2\_00.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_num_paulis-2_00.png) - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_num\_paulis-2\_01.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_num_paulis-2_01.png) - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_num\_paulis-2\_02.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_num_paulis-2_02.png) - - As you can see in the figure above, the number of backpropagated slices is displayed along the x-axis. You can think of this as the “time” of the backpropagation algorithm. The number of Pauli terms at each backpropagation step is displayed along the y-axis. Since each observable is treated individually, they are plotted separately. - - You can also find out the number of unique Pauli terms across all observables by using [`plot_sum_paulis()`](utils-visualization-plot-sum-paulis "qiskit_addon_obp.utils.visualization.plot_sum_paulis"). - - **Parameters** - - * **metadata** ([*OBPMetadata*](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. - * **axes** (*Axes*) – the matplotlib axes in which to plot. - - diff --git a/docs/api/qiskit-addon-obp/utils-visualization-plot-num-qwc-groups.mdx b/docs/api/qiskit-addon-obp/utils-visualization-plot-num-qwc-groups.mdx deleted file mode 100644 index 200f2951549..00000000000 --- a/docs/api/qiskit-addon-obp/utils-visualization-plot-num-qwc-groups.mdx +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: plot_num_qwc_groups -description: API reference for qiskit_addon_obp.utils.visualization.plot_num_qwc_groups -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_obp.utils.visualization.plot_num_qwc_groups ---- - - - -# 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. - - ```python - >>> from matplotlib import pyplot as plt - >>> from qiskit_addon_obp.utils.visualization import plot_num_qwc_groups - >>> fig, axes = plt.subplots(1, 1) - >>> plot_num_qwc_groups(metadata, axes) - ``` - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_num\_qwc\_groups-2\_00.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_num_qwc_groups-2_00.png) - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_num\_qwc\_groups-2\_01.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_num_qwc_groups-2_01.png) - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_num\_qwc\_groups-2\_02.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_num_qwc_groups-2_02.png) - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_num\_qwc\_groups-2\_03.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_num_qwc_groups-2_03.png) - - As you can see in the figure above, the number of backpropagated slices is displayed along the x-axis. You can think of this as the “time” of the backpropagation algorithm. The number of qubit-wise commuting Pauli groups at each backpropagation step is displayed along the y-axis. If `OBPMetadata.operator_budget.max_qwc_groups` is not None, it is displayed as a red horizontal line. - - **Parameters** - - * **metadata** ([*OBPMetadata*](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. - * **axes** (*Axes*) – the matplotlib axes in which to plot. - - diff --git a/docs/api/qiskit-addon-obp/utils-visualization-plot-num-truncated-paulis.mdx b/docs/api/qiskit-addon-obp/utils-visualization-plot-num-truncated-paulis.mdx deleted file mode 100644 index df5045c67a7..00000000000 --- a/docs/api/qiskit-addon-obp/utils-visualization-plot-num-truncated-paulis.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: plot_num_truncated_paulis -description: API reference for qiskit_addon_obp.utils.visualization.plot_num_truncated_paulis -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_obp.utils.visualization.plot_num_truncated_paulis ---- - - - -# 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. - - ```python - >>> from matplotlib import pyplot as plt - >>> from qiskit_addon_obp.utils.visualization import plot_num_truncated_paulis - >>> fig, axes = plt.subplots(1, 1) - >>> plot_num_truncated_paulis(metadata, axes) - ``` - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_num\_truncated\_paulis-2\_00.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_num_truncated_paulis-2_00.png) - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_num\_truncated\_paulis-2\_01.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_num_truncated_paulis-2_01.png) - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_num\_truncated\_paulis-2\_02.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_num_truncated_paulis-2_02.png) - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_num\_truncated\_paulis-2\_03.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_num_truncated_paulis-2_03.png) - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_num\_truncated\_paulis-2\_04.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_num_truncated_paulis-2_04.png) - - As you can see in the figure above, the number of backpropagated slices is displayed along the x-axis. You can think of this as the “time” of the backpropagation algorithm. The number of truncated Pauli terms at each backpropagation step is displayed along the y-axis. Since each observable is treated individually, they are plotted separately. - - This data can give you additional insight as to how the accumulated error is split across multiple Pauli terms (see also the output of [`plot_accumulated_error()`](utils-visualization-plot-accumulated-error "qiskit_addon_obp.utils.visualization.plot_accumulated_error")). - - **Parameters** - - * **metadata** ([*OBPMetadata*](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. - * **axes** (*Axes*) – the matplotlib axes in which to plot. - - diff --git a/docs/api/qiskit-addon-obp/utils-visualization-plot-slice-errors.mdx b/docs/api/qiskit-addon-obp/utils-visualization-plot-slice-errors.mdx deleted file mode 100644 index d43ced07c5c..00000000000 --- a/docs/api/qiskit-addon-obp/utils-visualization-plot-slice-errors.mdx +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: plot_slice_errors -description: API reference for qiskit_addon_obp.utils.visualization.plot_slice_errors -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_obp.utils.visualization.plot_slice_errors ---- - - - -# 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. - - ```python - >>> from matplotlib import pyplot as plt - >>> from qiskit_addon_obp.utils.visualization import plot_slice_errors - >>> fig, axes = plt.subplots(1, 1) - >>> plot_slice_errors(metadata, axes) - ``` - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_slice\_errors-2\_00.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_slice_errors-2_00.png) - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_slice\_errors-2\_01.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_slice_errors-2_01.png) - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_slice\_errors-2\_02.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_slice_errors-2_02.png) - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_slice\_errors-2\_03.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_slice_errors-2_03.png) - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_slice\_errors-2\_04.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_slice_errors-2_04.png) - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_slice\_errors-2\_05.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_slice_errors-2_05.png) - - As you can see in the figure above, the number of backpropagated slices is displayed along the x-axis. You can think of this as the “time” of the backpropagation algorithm. The truncation error incurred at each backpropagation step is displayed along the y-axis. Since each observable is treated individually, they are plotted separately. - - This data is related to the one visualized by [`plot_accumulated_error()`](utils-visualization-plot-accumulated-error "qiskit_addon_obp.utils.visualization.plot_accumulated_error"). That method will plot the cumulative sum of the slice errors along the x-axis. - - **Parameters** - - * **metadata** ([*OBPMetadata*](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. - * **axes** (*Axes*) – the matplotlib axes in which to plot. - - diff --git a/docs/api/qiskit-addon-obp/utils-visualization-plot-sum-paulis.mdx b/docs/api/qiskit-addon-obp/utils-visualization-plot-sum-paulis.mdx deleted file mode 100644 index 0240b35eb56..00000000000 --- a/docs/api/qiskit-addon-obp/utils-visualization-plot-sum-paulis.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: plot_sum_paulis -description: API reference for qiskit_addon_obp.utils.visualization.plot_sum_paulis -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_obp.utils.visualization.plot_sum_paulis ---- - - - -# 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. - - ```python - >>> from matplotlib import pyplot as plt - >>> from qiskit_addon_obp.utils.visualization import plot_sum_paulis - >>> fig, axes = plt.subplots(1, 1) - >>> plot_sum_paulis(metadata, axes) - ``` - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_sum\_paulis-2\_00.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_sum_paulis-2_00.png) - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_sum\_paulis-2\_01.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_sum_paulis-2_01.png) - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_sum\_paulis-2\_02.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_sum_paulis-2_02.png) - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_sum\_paulis-2\_03.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_sum_paulis-2_03.png) - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_sum\_paulis-2\_04.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_sum_paulis-2_04.png) - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_sum\_paulis-2\_05.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_sum_paulis-2_05.png) - - ![../\_images/qiskit\_addon\_obp-utils-visualization-plot\_sum\_paulis-2\_06.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-plot_sum_paulis-2_06.png) - - As you can see in the figure above, the number of backpropagated slices is displayed along the x-axis. You can think of this as the “time” of the backpropagation algorithm. The total number of all Pauli terms at each backpropagation step is displayed along the y-axis. If `OBPMetadata.operator_budget.max_paulis` is not None, it is displayed as a red horizontal line. - - This data can give you additional insight into how many unique Pauli terms are spread across all of the backpropagated observables. See also the output of [`plot_num_paulis()`](utils-visualization-plot-num-paulis "qiskit_addon_obp.utils.visualization.plot_num_paulis") for the number of Pauli terms in each observable individually. - - **Parameters** - - * **metadata** ([*OBPMetadata*](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. - * **axes** (*Axes*) – the matplotlib axes in which to plot. - - diff --git a/docs/api/qiskit-addon-obp/utils-visualization.mdx b/docs/api/qiskit-addon-obp/utils-visualization.mdx index a6e89a1aabe..2906430e85f 100644 --- a/docs/api/qiskit-addon-obp/utils-visualization.mdx +++ b/docs/api/qiskit-addon-obp/utils-visualization.mdx @@ -1,17 +1,238 @@ -# visualization +--- +title: visualization +description: API reference for qiskit_addon_obp.utils.visualization +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_addon_obp.utils.visualization +--- - + + +# Visualization utilities + +`qiskit_addon_obp.utils.visualization` Various visualization utilities. -| | | -| --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | -| [`plot_accumulated_error`](utils-visualization-plot-accumulated-error "qiskit_addon_obp.utils.visualization.plot_accumulated_error") | Plot the accumulated error. | -| [`plot_left_over_error_budget`](utils-visualization-plot-left-over-error-budget "qiskit_addon_obp.utils.visualization.plot_left_over_error_budget") | Plot the left-over error budget. | -| [`plot_slice_errors`](utils-visualization-plot-slice-errors "qiskit_addon_obp.utils.visualization.plot_slice_errors") | Plot the slice errors. | -| [`plot_num_paulis`](utils-visualization-plot-num-paulis "qiskit_addon_obp.utils.visualization.plot_num_paulis") | Plot the number of Pauli terms. | -| [`plot_num_truncated_paulis`](utils-visualization-plot-num-truncated-paulis "qiskit_addon_obp.utils.visualization.plot_num_truncated_paulis") | Plot the number of truncated Pauli terms. | -| [`plot_sum_paulis`](utils-visualization-plot-sum-paulis "qiskit_addon_obp.utils.visualization.plot_sum_paulis") | Plot the total number of all Pauli terms. | -| [`plot_num_qwc_groups`](utils-visualization-plot-num-qwc-groups "qiskit_addon_obp.utils.visualization.plot_num_qwc_groups") | Plot the number of qubit-wise commuting Pauli groups. | +### 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. + + ```python + >>> from matplotlib import pyplot as plt + >>> from qiskit_addon_obp.utils.visualization import plot_accumulated_error + >>> fig, axes = plt.subplots(1, 1) + >>> plot_accumulated_error(metadata, axes) + ``` + + ![../\_images/qiskit\_addon\_obp-utils-visualization-2.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-2.png) + + As you can see in the figure above, the number of backpropagated slices is displayed along the x-axis. You can think of this as the “time” of the backpropagation algorithm. The accumulated error due to truncated Pauli terms is displayed along the y-axis. If `OBPMetadata.truncation_error_budget.max_error_total` is not [`numpy.inf`](https://numpy.org/doc/stable/reference/constants.html#numpy.inf "(in NumPy v2.1)"), it is displayed as a red horizontal line. Each observable that was backpropagated, gets its own line. + + This data is related to the one visualized by [`plot_slice_errors()`](#qiskit_addon_obp.utils.visualization.plot_slice_errors "qiskit_addon_obp.utils.visualization.plot_slice_errors"). This method plots the cumulative sum of the slice errors along the x-axis. + + **Parameters** + + * **metadata** ([*OBPMetadata*](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. + * **axes** (*Axes*) – the matplotlib axes in which to plot. + + +### 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. + + ```python + >>> from matplotlib import pyplot as plt + >>> from qiskit_addon_obp.utils.visualization import plot_left_over_error_budget + >>> fig, axes = plt.subplots(1, 1) + >>> plot_left_over_error_budget(metadata, axes) + ``` + + ![../\_images/qiskit\_addon\_obp-utils-visualization-4\_00.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-4_00.png) + + ![../\_images/qiskit\_addon\_obp-utils-visualization-4\_01.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-4_01.png) + + As you can see in the figure above, the number of backpropagated slices is displayed along the x-axis. You can think of this as the “time” of the backpropagation algorithm. The left-over error budget available at each backpropagation step is displayed along the y-axis. Since each observable that was backpropagated has its own budget, they are plotted as separate lines. + + **Parameters** + + * **metadata** ([*OBPMetadata*](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. + * **axes** (*Axes*) – the matplotlib axes in which to plot. + + +### 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. + + ```python + >>> from matplotlib import pyplot as plt + >>> from qiskit_addon_obp.utils.visualization import plot_slice_errors + >>> fig, axes = plt.subplots(1, 1) + >>> plot_slice_errors(metadata, axes) + ``` + + ![../\_images/qiskit\_addon\_obp-utils-visualization-6\_00.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-6_00.png) + + ![../\_images/qiskit\_addon\_obp-utils-visualization-6\_01.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-6_01.png) + + ![../\_images/qiskit\_addon\_obp-utils-visualization-6\_02.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-6_02.png) + + As you can see in the figure above, the number of backpropagated slices is displayed along the x-axis. You can think of this as the “time” of the backpropagation algorithm. The truncation error incurred at each backpropagation step is displayed along the y-axis. Since each observable is treated individually, they are plotted separately. + + This data is related to the one visualized by [`plot_accumulated_error()`](#qiskit_addon_obp.utils.visualization.plot_accumulated_error "qiskit_addon_obp.utils.visualization.plot_accumulated_error"). That method will plot the cumulative sum of the slice errors along the x-axis. + + **Parameters** + + * **metadata** ([*OBPMetadata*](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. + * **axes** (*Axes*) – the matplotlib axes in which to plot. + + +### 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. + + ```python + >>> from matplotlib import pyplot as plt + >>> from qiskit_addon_obp.utils.visualization import plot_num_paulis + >>> fig, axes = plt.subplots(1, 1) + >>> plot_num_paulis(metadata, axes) + ``` + + ![../\_images/qiskit\_addon\_obp-utils-visualization-8\_00.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-8_00.png) + + ![../\_images/qiskit\_addon\_obp-utils-visualization-8\_01.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-8_01.png) + + ![../\_images/qiskit\_addon\_obp-utils-visualization-8\_02.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-8_02.png) + + ![../\_images/qiskit\_addon\_obp-utils-visualization-8\_03.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-8_03.png) + + As you can see in the figure above, the number of backpropagated slices is displayed along the x-axis. You can think of this as the “time” of the backpropagation algorithm. The number of Pauli terms at each backpropagation step is displayed along the y-axis. Since each observable is treated individually, they are plotted separately. + + You can also find out the number of unique Pauli terms across all observables by using [`plot_sum_paulis()`](#qiskit_addon_obp.utils.visualization.plot_sum_paulis "qiskit_addon_obp.utils.visualization.plot_sum_paulis"). + + **Parameters** + + * **metadata** ([*OBPMetadata*](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. + * **axes** (*Axes*) – the matplotlib axes in which to plot. + + +### 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. + + ```python + >>> from matplotlib import pyplot as plt + >>> from qiskit_addon_obp.utils.visualization import plot_num_truncated_paulis + >>> fig, axes = plt.subplots(1, 1) + >>> plot_num_truncated_paulis(metadata, axes) + ``` + + ![../\_images/qiskit\_addon\_obp-utils-visualization-10\_00.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-10_00.png) + + ![../\_images/qiskit\_addon\_obp-utils-visualization-10\_01.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-10_01.png) + + ![../\_images/qiskit\_addon\_obp-utils-visualization-10\_02.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-10_02.png) + + ![../\_images/qiskit\_addon\_obp-utils-visualization-10\_03.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-10_03.png) + + ![../\_images/qiskit\_addon\_obp-utils-visualization-10\_04.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-10_04.png) + + As you can see in the figure above, the number of backpropagated slices is displayed along the x-axis. You can think of this as the “time” of the backpropagation algorithm. The number of truncated Pauli terms at each backpropagation step is displayed along the y-axis. Since each observable is treated individually, they are plotted separately. + + This data can give you additional insight as to how the accumulated error is split across multiple Pauli terms (see also the output of [`plot_accumulated_error()`](#qiskit_addon_obp.utils.visualization.plot_accumulated_error "qiskit_addon_obp.utils.visualization.plot_accumulated_error")). + + **Parameters** + + * **metadata** ([*OBPMetadata*](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. + * **axes** (*Axes*) – the matplotlib axes in which to plot. + + +### 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. + + ```python + >>> from matplotlib import pyplot as plt + >>> from qiskit_addon_obp.utils.visualization import plot_sum_paulis + >>> fig, axes = plt.subplots(1, 1) + >>> plot_sum_paulis(metadata, axes) + ``` + + ![../\_images/qiskit\_addon\_obp-utils-visualization-12\_00.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-12_00.png) + + ![../\_images/qiskit\_addon\_obp-utils-visualization-12\_01.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-12_01.png) + + ![../\_images/qiskit\_addon\_obp-utils-visualization-12\_02.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-12_02.png) + + ![../\_images/qiskit\_addon\_obp-utils-visualization-12\_03.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-12_03.png) + + ![../\_images/qiskit\_addon\_obp-utils-visualization-12\_04.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-12_04.png) + + ![../\_images/qiskit\_addon\_obp-utils-visualization-12\_05.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-12_05.png) + + As you can see in the figure above, the number of backpropagated slices is displayed along the x-axis. You can think of this as the “time” of the backpropagation algorithm. The total number of all Pauli terms at each backpropagation step is displayed along the y-axis. If `OBPMetadata.operator_budget.max_paulis` is not None, it is displayed as a red horizontal line. + + This data can give you additional insight into how many unique Pauli terms are spread across all of the backpropagated observables. See also the output of [`plot_num_paulis()`](#qiskit_addon_obp.utils.visualization.plot_num_paulis "qiskit_addon_obp.utils.visualization.plot_num_paulis") for the number of Pauli terms in each observable individually. + + **Parameters** + + * **metadata** ([*OBPMetadata*](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. + * **axes** (*Axes*) – the matplotlib axes in which to plot. + + +### 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. + + ```python + >>> from matplotlib import pyplot as plt + >>> from qiskit_addon_obp.utils.visualization import plot_num_qwc_groups + >>> fig, axes = plt.subplots(1, 1) + >>> plot_num_qwc_groups(metadata, axes) + ``` + + ![../\_images/qiskit\_addon\_obp-utils-visualization-14\_00.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-14_00.png) + + ![../\_images/qiskit\_addon\_obp-utils-visualization-14\_01.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-14_01.png) + + ![../\_images/qiskit\_addon\_obp-utils-visualization-14\_02.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-14_02.png) + + ![../\_images/qiskit\_addon\_obp-utils-visualization-14\_03.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-14_03.png) + + ![../\_images/qiskit\_addon\_obp-utils-visualization-14\_04.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-14_04.png) + + ![../\_images/qiskit\_addon\_obp-utils-visualization-14\_05.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-14_05.png) + + ![../\_images/qiskit\_addon\_obp-utils-visualization-14\_06.png](/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-14_06.png) + + As you can see in the figure above, the number of backpropagated slices is displayed along the x-axis. You can think of this as the “time” of the backpropagation algorithm. The number of qubit-wise commuting Pauli groups at each backpropagation step is displayed along the y-axis. If `OBPMetadata.operator_budget.max_qwc_groups` is not None, it is displayed as a red horizontal line. + + **Parameters** + + * **metadata** ([*OBPMetadata*](utils-metadata-obp-metadata "qiskit_addon_obp.utils.metadata.OBPMetadata")) – the metadata to be visualized. + * **axes** (*Axes*) – the matplotlib axes in which to plot. + + diff --git a/docs/api/qiskit-addon-obp/utils.mdx b/docs/api/qiskit-addon-obp/utils.mdx deleted file mode 100644 index ad96ef5db0b..00000000000 --- a/docs/api/qiskit-addon-obp/utils.mdx +++ /dev/null @@ -1,15 +0,0 @@ -# utils - - - - - -Utility functionality for conducting operator backpropagation. - -| | | -| ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | -| [`metadata`](utils-metadata#module-qiskit_addon_obp.utils.metadata "qiskit_addon_obp.utils.metadata") | Container classes for holding backpropagation metadata. | -| [`operations`](utils-operations#module-qiskit_addon_obp.utils.operations "qiskit_addon_obp.utils.operations") | Utility functions for operator backpropagation. | -| [`simplify`](utils-simplify#module-qiskit_addon_obp.utils.simplify "qiskit_addon_obp.utils.simplify") | Functions for simplifying Pauli operators. | -| [`truncating`](utils-truncating#module-qiskit_addon_obp.utils.truncating "qiskit_addon_obp.utils.truncating") | Functions for truncating Pauli operators within given error budgets. | -| [`visualization`](utils-visualization#module-qiskit_addon_obp.utils.visualization "qiskit_addon_obp.utils.visualization") | Various visualization utilities. | diff --git a/docs/api/qiskit-addon-sqd/_toc.json b/docs/api/qiskit-addon-sqd/_toc.json index 7cb14070e12..be35315d11d 100644 --- a/docs/api/qiskit-addon-sqd/_toc.json +++ b/docs/api/qiskit-addon-sqd/_toc.json @@ -5,6 +5,26 @@ "title": "API index", "url": "/api/qiskit-addon-sqd" }, + { + "title": "qiskit_addon_sqd.configuration_recovery", + "url": "/api/qiskit-addon-sqd/configuration-recovery" + }, + { + "title": "qiskit_addon_sqd.counts", + "url": "/api/qiskit-addon-sqd/counts" + }, + { + "title": "qiskit_addon_sqd.fermion", + "url": "/api/qiskit-addon-sqd/fermion" + }, + { + "title": "qiskit_addon_sqd.qubit", + "url": "/api/qiskit-addon-sqd/qubit" + }, + { + "title": "qiskit_addon_sqd.subsampling", + "url": "/api/qiskit-addon-sqd/subsampling" + }, { "title": "Release notes", "url": "/api/qiskit-addon-sqd/release-notes" diff --git a/docs/api/qiskit-addon-sqd/configuration-recovery-post-select-by-hamming-weight.mdx b/docs/api/qiskit-addon-sqd/configuration-recovery-post-select-by-hamming-weight.mdx deleted file mode 100644 index 1b10b9c8bb6..00000000000 --- a/docs/api/qiskit-addon-sqd/configuration-recovery-post-select-by-hamming-weight.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: post_select_by_hamming_weight -description: API reference for qiskit_addon_sqd.configuration_recovery.post_select_by_hamming_weight -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_sqd.configuration_recovery.post_select_by_hamming_weight ---- - - - -# qiskit\_addon\_sqd.configuration\_recovery.post\_select\_by\_hamming\_weight - - - Post-select bitstrings based on the hamming weight of each half. - - **Parameters** - - * **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring - * **hamming\_right** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The target hamming weight of the right half of bitstrings - * **hamming\_left** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The target hamming weight of the left half of bitstrings - - **Returns** - - A mask signifying which samples (rows) were selected from the input matrix. - - **Return type** - - [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)") - - diff --git a/docs/api/qiskit-addon-sqd/configuration-recovery-recover-configurations.mdx b/docs/api/qiskit-addon-sqd/configuration-recovery-recover-configurations.mdx deleted file mode 100644 index 9b8ed6916bc..00000000000 --- a/docs/api/qiskit-addon-sqd/configuration-recovery-recover-configurations.mdx +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: recover_configurations -description: API reference for qiskit_addon_sqd.configuration_recovery.recover_configurations -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_sqd.configuration_recovery.recover_configurations ---- - - - -# qiskit\_addon\_sqd.configuration\_recovery.recover\_configurations - - - Refine bitstrings based on average orbital occupancy and a target hamming weight. - - This function refines each bit in isolation in an attempt to transform the Hilbert space represented by the input `bitstring_matrix` into a space closer to that which supports the ground state. - - - This function makes the assumption that bit `i` represents the spin-down orbital corresponding to the spin-up orbital in bit `i + N` where `N` is the number of spatial orbitals and `i < N`. - - - - The output configurations may not necessarily have correct hamming weight, as each bit is flipped in isolation from the other bits in the bitstring. - - - **Parameters** - - * **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring - * **probabilities** ([*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")*]*) – A 1D array specifying a probability distribution over the bitstrings - * **avg\_occupancies** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 1D array containing the mean occupancy of each orbital. It is assumed that `avg_occupancies[i]` corresponds to the orbital represented by column `i` in `bitstring_matrix`. - * **num\_elec\_a** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of spin-up electrons in the system. - * **num\_elec\_b** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of spin-down electrons in the system. - * **rand\_seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| None*) – A seed to control random behavior - - **Returns** - - A refined bitstring matrix and an updated probability array. - - **Return type** - - [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)"), [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")] - - **References** - - ## \[1]: J. Robledo-Moreno, et al., [Chemistry Beyond Exact Solutions on a Quantum-Centric Supercomputer](https://arxiv.org/abs/2405.05068), - - arXiv:2405.05068 \[quant-ph]. - - diff --git a/docs/api/qiskit-addon-sqd/configuration-recovery.mdx b/docs/api/qiskit-addon-sqd/configuration-recovery.mdx index 3cda3199b18..acad2eaa119 100644 --- a/docs/api/qiskit-addon-sqd/configuration-recovery.mdx +++ b/docs/api/qiskit-addon-sqd/configuration-recovery.mdx @@ -1,12 +1,77 @@ -# Configuration Recovery +--- +title: configuration_recovery +description: API reference for qiskit_addon_sqd.configuration_recovery +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_addon_sqd.configuration_recovery +--- - + + +# Configuration recovery + +`qiskit_addon_sqd.configuration_recovery` Functions for performing self-consistent configuration recovery. -| | | -| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | -| [`post_select_by_hamming_weight`](configuration-recovery-post-select-by-hamming-weight "qiskit_addon_sqd.configuration_recovery.post_select_by_hamming_weight") | Post-select bitstrings based on the hamming weight of each half. | -| [`recover_configurations`](configuration-recovery-recover-configurations "qiskit_addon_sqd.configuration_recovery.recover_configurations") | Refine bitstrings based on average orbital occupancy and a target hamming weight. | +### post\_select\_by\_hamming\_weight + + + Post-select bitstrings based on the hamming weight of each half. + + **Parameters** + + * **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring + * **hamming\_right** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The target hamming weight of the right half of bitstrings + * **hamming\_left** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The target hamming weight of the left half of bitstrings + + **Returns** + + A mask signifying which samples (rows) were selected from the input matrix. + + **Return type** + + [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)") + + +### recover\_configurations + + + Refine bitstrings based on average orbital occupancy and a target hamming weight. + + This function refines each bit in isolation in an attempt to transform the Hilbert space represented by the input `bitstring_matrix` into a space closer to that which supports the ground state. + + + This function makes the assumption that bit `i` represents the spin-down orbital corresponding to the spin-up orbital in bit `i + N` where `N` is the number of spatial orbitals and `i < N`. + + + + The output configurations may not necessarily have correct hamming weight, as each bit is flipped in isolation from the other bits in the bitstring. + + + **Parameters** + + * **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring + * **probabilities** ([*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")*]*) – A 1D array specifying a probability distribution over the bitstrings + * **avg\_occupancies** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 1D array containing the mean occupancy of each orbital. It is assumed that `avg_occupancies[i]` corresponds to the orbital represented by column `i` in `bitstring_matrix`. + * **num\_elec\_a** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of spin-up electrons in the system. + * **num\_elec\_b** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of spin-down electrons in the system. + * **rand\_seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| None*) – A seed to control random behavior + + **Returns** + + A refined bitstring matrix and an updated probability array. + + **Return type** + + [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)"), [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")] + + **References** + + **\[1]: J. Robledo-Moreno, et al., [Chemistry Beyond Exact Solutions on a Quantum-Centric Supercomputer](https://arxiv.org/abs/2405.05068),** + + arXiv:2405.05068 \[quant-ph]. + + diff --git a/docs/api/qiskit-addon-sqd/counts-counts-to-arrays.mdx b/docs/api/qiskit-addon-sqd/counts-counts-to-arrays.mdx deleted file mode 100644 index 9778e4e21f0..00000000000 --- a/docs/api/qiskit-addon-sqd/counts-counts-to-arrays.mdx +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: counts_to_arrays -description: API reference for qiskit_addon_sqd.counts.counts_to_arrays -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_sqd.counts.counts_to_arrays ---- - - - -# qiskit\_addon\_sqd.counts.counts\_to\_arrays - - - Convert a counts dictionary into a bitstring matrix and a probability array. - - **Parameters** - - **counts** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The counts dictionary to convert - - **Returns** - - * A 2D array representing the sampled bitstrings. Each row represents a bitstring, and each element is a `bool` representation of the bit’s value - * A 1D array containing the probability with which each bitstring was sampled - - **Return type** - - A tuple containing - - diff --git a/docs/api/qiskit-addon-sqd/counts-generate-counts-bipartite-hamming.mdx b/docs/api/qiskit-addon-sqd/counts-generate-counts-bipartite-hamming.mdx deleted file mode 100644 index a649f184431..00000000000 --- a/docs/api/qiskit-addon-sqd/counts-generate-counts-bipartite-hamming.mdx +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: generate_counts_bipartite_hamming -description: API reference for qiskit_addon_sqd.counts.generate_counts_bipartite_hamming -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_sqd.counts.generate_counts_bipartite_hamming ---- - - - -# qiskit\_addon\_sqd.counts.generate\_counts\_bipartite\_hamming - - - Generate a bitstring counts dictionary with specified bipartite hamming weight. - - **Parameters** - - * **num\_samples** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of samples to draw - * **num\_bits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of bits in the bitstrings - * **hamming\_right** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The hamming weight on the right half of each bitstring - * **hamming\_left** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The hamming weight on the left half of each bitstring - * **rand\_seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| None*) – A seed for controlling randomness - - **Returns** - - A dictionary mapping bitstrings to the number of times they were sampled. Each half of each bitstring in the output dictionary will have a hamming weight as specified by the inputs. - - **Raises** - - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – `num_bits` and `num_samples` must be positive integers. - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Hamming weights must be specified as non-negative integers. - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – `num_bits` must be even. - - **Return type** - - [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)"), [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")] - - diff --git a/docs/api/qiskit-addon-sqd/counts-generate-counts-uniform.mdx b/docs/api/qiskit-addon-sqd/counts-generate-counts-uniform.mdx deleted file mode 100644 index deae2e97bea..00000000000 --- a/docs/api/qiskit-addon-sqd/counts-generate-counts-uniform.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: generate_counts_uniform -description: API reference for qiskit_addon_sqd.counts.generate_counts_uniform -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_sqd.counts.generate_counts_uniform ---- - - - -# qiskit\_addon\_sqd.counts.generate\_counts\_uniform - - - Generate a bitstring counts dictionary of samples drawn from the uniform distribution. - - **Parameters** - - * **num\_samples** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of samples to draw - * **num\_bits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of bits in the bitstrings - * **rand\_seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| None*) – A seed for controlling randomness - - **Returns** - - A dictionary mapping bitstrings of length `num_bits` to the number of times they were sampled. - - **Raises** - - [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – `num_samples` and `num_bits` must be positive integers. - - **Return type** - - [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)"), [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")] - - diff --git a/docs/api/qiskit-addon-sqd/counts-normalize-counts-dict.mdx b/docs/api/qiskit-addon-sqd/counts-normalize-counts-dict.mdx deleted file mode 100644 index a91f814a99e..00000000000 --- a/docs/api/qiskit-addon-sqd/counts-normalize-counts-dict.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: normalize_counts_dict -description: API reference for qiskit_addon_sqd.counts.normalize_counts_dict -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_sqd.counts.normalize_counts_dict ---- - - - -# qiskit\_addon\_sqd.counts.normalize\_counts\_dict - - - Convert a counts dictionary into a probability dictionary. - - **Return type** - - [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)"), [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")] - - diff --git a/docs/api/qiskit-addon-sqd/counts.mdx b/docs/api/qiskit-addon-sqd/counts.mdx index 390d4c46298..7b27b214d4d 100644 --- a/docs/api/qiskit-addon-sqd/counts.mdx +++ b/docs/api/qiskit-addon-sqd/counts.mdx @@ -1,14 +1,99 @@ -# Counts +--- +title: counts +description: API reference for qiskit_addon_sqd.counts +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_addon_sqd.counts +--- - + + +# Counts + +`qiskit_addon_sqd.counts` Functions for transforming counts dictionaries. -| | | -| ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -| [`counts_to_arrays`](counts-counts-to-arrays "qiskit_addon_sqd.counts.counts_to_arrays") | Convert a counts dictionary into a bitstring matrix and a probability array. | -| [`generate_counts_uniform`](counts-generate-counts-uniform "qiskit_addon_sqd.counts.generate_counts_uniform") | Generate a bitstring counts dictionary of samples drawn from the uniform distribution. | -| [`generate_counts_bipartite_hamming`](counts-generate-counts-bipartite-hamming "qiskit_addon_sqd.counts.generate_counts_bipartite_hamming") | Generate a bitstring counts dictionary with specified bipartite hamming weight. | -| [`normalize_counts_dict`](counts-normalize-counts-dict "qiskit_addon_sqd.counts.normalize_counts_dict") | Convert a counts dictionary into a probability dictionary. | +### counts\_to\_arrays + + + Convert a counts dictionary into a bitstring matrix and a probability array. + + **Parameters** + + **counts** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The counts dictionary to convert + + **Returns** + + * A 2D array representing the sampled bitstrings. Each row represents a bitstring, and each element is a `bool` representation of the bit’s value + * A 1D array containing the probability with which each bitstring was sampled + + **Return type** + + [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)"), [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")] + + +### generate\_counts\_uniform + + + Generate a bitstring counts dictionary of samples drawn from the uniform distribution. + + **Parameters** + + * **num\_samples** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of samples to draw + * **num\_bits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of bits in the bitstrings + * **rand\_seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| None*) – A seed for controlling randomness + + **Returns** + + A dictionary mapping bitstrings of length `num_bits` to the number of times they were sampled. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – `num_samples` and `num_bits` must be positive integers. + + **Return type** + + [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)"), [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")] + + +### generate\_counts\_bipartite\_hamming + + + Generate a bitstring counts dictionary with specified bipartite hamming weight. + + **Parameters** + + * **num\_samples** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of samples to draw + * **num\_bits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of bits in the bitstrings + * **hamming\_right** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The hamming weight on the right half of each bitstring + * **hamming\_left** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The hamming weight on the left half of each bitstring + * **rand\_seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| None*) – A seed for controlling randomness + + **Returns** + + A dictionary mapping bitstrings to the number of times they were sampled. Each half of each bitstring in the output dictionary will have a hamming weight as specified by the inputs. + + **Raises** + + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – `num_bits` and `num_samples` must be positive integers. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Hamming weights must be specified as non-negative integers. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – `num_bits` must be even. + + **Return type** + + [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)"), [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")] + + +### normalize\_counts\_dict + + + Convert a counts dictionary into a probability dictionary. + + **Return type** + + [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)"), [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")] + + diff --git a/docs/api/qiskit-addon-sqd/fermion-bitstring-matrix-to-ci-strs.mdx b/docs/api/qiskit-addon-sqd/fermion-bitstring-matrix-to-ci-strs.mdx deleted file mode 100644 index e5f2c0d9e8f..00000000000 --- a/docs/api/qiskit-addon-sqd/fermion-bitstring-matrix-to-ci-strs.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: bitstring_matrix_to_ci_strs -description: API reference for qiskit_addon_sqd.fermion.bitstring_matrix_to_ci_strs -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_sqd.fermion.bitstring_matrix_to_ci_strs ---- - - - -# qiskit\_addon\_sqd.fermion.bitstring\_matrix\_to\_ci\_strs - - - Convert bitstrings (rows) in a `bitstring_matrix` into integer representations of determinants. - - This function separates each bitstring in `bitstring_matrix` in half, flips the bits and translates them into integer representations, and finally appends them to their respective (spin-up or spin-down) lists. Those lists are sorted and output from this function. - - **Parameters** - - * **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring - * **open\_shell** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – A flag specifying whether unique configurations from the left and right halves of the bitstrings should be kept separate. If `False`, configurations from the left and right halves of the bitstrings are combined into a single set of unique configurations. That combined set will be returned for both the left and right bitstrings. - - **Returns** - - A length-2 tuple of determinant lists representing the right (spin-up) and left (spin-down) halves of the bitstrings, respectively. - - **Return type** - - [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)"), [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")] - - diff --git a/docs/api/qiskit-addon-sqd/fermion-bitstring-matrix-to-sorted-addresses.mdx b/docs/api/qiskit-addon-sqd/fermion-bitstring-matrix-to-sorted-addresses.mdx deleted file mode 100644 index 66044827adc..00000000000 --- a/docs/api/qiskit-addon-sqd/fermion-bitstring-matrix-to-sorted-addresses.mdx +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: bitstring_matrix_to_sorted_addresses -description: API reference for qiskit_addon_sqd.fermion.bitstring_matrix_to_sorted_addresses -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_sqd.fermion.bitstring_matrix_to_sorted_addresses ---- - - - -# qiskit\_addon\_sqd.fermion.bitstring\_matrix\_to\_sorted\_addresses - - - Convert a bitstring matrix into a sorted array of unique, unsigned integers. - - This function separates each bitstring in `bitstring_matrix` in half, flips the bits and translates them into integer representations, and finally appends them to their respective (spin-up or spin-down) lists. Those lists are sorted and output from this function. - - - The function `qiskit_addon_sqd.fermion.bitstring_matrix_to_sorted_addresses()` is deprecated as of qiskit-addon-sqd 0.6.0. It will be removed no sooner than qiskit-addon-sqd 0.8.0. Use the bitstring\_matrix\_to\_ci\_strs function. - - - **Parameters** - - * **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring - * **open\_shell** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – A flag specifying whether unique addresses from the left and right halves of the bitstrings should be kept separate. If `False`, addresses from the left and right halves of the bitstrings are combined into a single set of unique addresses. That combined set will be returned for both the left and right bitstrings. - - **Returns** - - A length-2 tuple of sorted, unique determinants representing the left (spin-down) and right (spin-up) halves of the bitstrings, respectively. - - **Return type** - - [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)"), [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")] - - diff --git a/docs/api/qiskit-addon-sqd/fermion-enlarge-batch-from-transitions.mdx b/docs/api/qiskit-addon-sqd/fermion-enlarge-batch-from-transitions.mdx deleted file mode 100644 index be0cb193f35..00000000000 --- a/docs/api/qiskit-addon-sqd/fermion-enlarge-batch-from-transitions.mdx +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: enlarge_batch_from_transitions -description: API reference for qiskit_addon_sqd.fermion.enlarge_batch_from_transitions -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_sqd.fermion.enlarge_batch_from_transitions ---- - - - -# qiskit\_addon\_sqd.fermion.enlarge\_batch\_from\_transitions - - - Apply the set of transition operators to the configurations represented in `bitstring_matrix`. - - **Parameters** - - * **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring. - * **transition\_operators** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 1D or 2D array `I`, `+`, `-`, and `n` strings representing the action of the identity, creation, annihilation, or number operators. Each row represents a transition operator. - - **Returns** - - Bitstring matrix representing the augmented set of electronic configurations after applying the excitation operators. - - **Return type** - - [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)") - - diff --git a/docs/api/qiskit-addon-sqd/fermion-flip-orbital-occupancies.mdx b/docs/api/qiskit-addon-sqd/fermion-flip-orbital-occupancies.mdx deleted file mode 100644 index e4f73565ea0..00000000000 --- a/docs/api/qiskit-addon-sqd/fermion-flip-orbital-occupancies.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: flip_orbital_occupancies -description: API reference for qiskit_addon_sqd.fermion.flip_orbital_occupancies -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_sqd.fermion.flip_orbital_occupancies ---- - - - -# qiskit\_addon\_sqd.fermion.flip\_orbital\_occupancies - - - Flip an orbital occupancy array to match the indexing of a bitstring. - - This function reformats a 1D array of spin-orbital occupancies formatted like: - - > `[occ_a_1, occ_a_2, ..., occ_a_N, occ_b_1, ..., occ_b_N]` - - To an array formatted like: - - > `[occ_a_N, ..., occ_a_1, occ_b_N, ..., occ_b_1]` - - where `N` is the number of spatial orbitals. - - **Return type** - - [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)") - - diff --git a/docs/api/qiskit-addon-sqd/fermion-optimize-orbitals.mdx b/docs/api/qiskit-addon-sqd/fermion-optimize-orbitals.mdx deleted file mode 100644 index 4805a573b54..00000000000 --- a/docs/api/qiskit-addon-sqd/fermion-optimize-orbitals.mdx +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: optimize_orbitals -description: API reference for qiskit_addon_sqd.fermion.optimize_orbitals -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_sqd.fermion.optimize_orbitals ---- - - - -# qiskit\_addon\_sqd.fermion.optimize\_orbitals - - - Optimize orbitals to produce a minimal ground state. - - The process involves iterating over 3 steps: - - ## For `num_iters` iterations: - - * Rotate the integrals with respect to the parameters, `k_flat` - * Diagonalize and approximate the groundstate energy and wavefunction amplitudes - * Optimize `k_flat` using gradient descent and the wavefunction amplitudes found in Step 2 - - Refer to [Sec. II A 4](https://arxiv.org/pdf/2405.05068) for more detailed discussion on this orbital optimization technique. - - **Parameters** - - * **bitstring\_matrix** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")*\[*[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")*,* [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")*] |* [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – - - A set of configurations defining the subspace onto which the Hamiltonian will be projected and diagonalized. This is a 2D array of `bool` representations of bit values such that each row represents a single bitstring. The spin-up configurations should be specified by column indices in range `(N, N/2]`, and the spin-down configurations should be specified by column indices in range `(N/2, 0]`, where `N` is the number of qubits. - - (DEPRECATED) The configurations may also be specified by a length-2 tuple of sorted 1D arrays containing unsigned integer representations of the determinants. The two lists should represent the spin-up and spin-down orbitals, respectively. - - * **hcore** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – Core Hamiltonian matrix representing single-electron integrals - - * **eri** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – Electronic repulsion integrals representing two-electron integrals - - * **k\_flat** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – 1D array defining the orbital transform. This array will be reshaped to be of shape (# orbitals, # orbitals) before being used as a similarity transform operator on the orbitals. Thus `len(k_flat)=# orbitals**2`. - - * **open\_shell** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – A flag specifying whether configurations from the left and right halves of the bitstrings should be kept separate. If `False`, CI strings from the left and right halves of the bitstrings are combined into a single set of unique configurations and used for both the alpha and beta subspaces. - - * **spin\_sq** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – Target value for the total spin squared for the ground state - - * **num\_iters** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of iterations of orbital optimization to perform - - * **max\_davidson** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The maximum number of cycles of Davidson’s algorithm to perform during diagonalization. - - * **num\_steps\_grad** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of steps of gradient descent to perform during each optimization iteration - - * **learning\_rate** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – The learning rate to use during gradient descent - - **Returns** - - * The groundstate energy found during the last optimization iteration - * An optimized 1D array defining the orbital transform - * Average orbital occupancy - - **Return type** - - A tuple containing - - diff --git a/docs/api/qiskit-addon-sqd/fermion-rotate-integrals.mdx b/docs/api/qiskit-addon-sqd/fermion-rotate-integrals.mdx deleted file mode 100644 index 6efead9b19d..00000000000 --- a/docs/api/qiskit-addon-sqd/fermion-rotate-integrals.mdx +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: rotate_integrals -description: API reference for qiskit_addon_sqd.fermion.rotate_integrals -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_sqd.fermion.rotate_integrals ---- - - - -# qiskit\_addon\_sqd.fermion.rotate\_integrals - - - Perform a similarity transform on the integrals. - - The transformation is described as: - -$$ -\hat{\widetilde{H}} = \hat{U^{\dagger}}(k)\hat{H}\hat{U}(k) -$$ - - For more information on how $\hat{U}$ and $\hat{U^{\dagger}}$ are generated from `k_flat` and applied to the one- and two-body integrals, refer to [Sec. II A 4](https://arxiv.org/pdf/2405.05068). - - **Parameters** - - * **hcore** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – Core Hamiltonian matrix representing single-electron integrals - - * **eri** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – Electronic repulsion integrals representing two-electron integrals - - * **k\_flat** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – - - 1D array defining the orbital transform. Refer to [Sec. II A 4](https://arxiv.org/pdf/2405.05068) for more information on how these values are used to generate the transform operator. - - **Returns** - - * The rotated core Hamiltonian matrix - * The rotated ERI matrix - - **Return type** - - [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)"), [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")] - - diff --git a/docs/api/qiskit-addon-sqd/fermion-solve-fermion.mdx b/docs/api/qiskit-addon-sqd/fermion-solve-fermion.mdx deleted file mode 100644 index 860cc432b26..00000000000 --- a/docs/api/qiskit-addon-sqd/fermion-solve-fermion.mdx +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: solve_fermion -description: API reference for qiskit_addon_sqd.fermion.solve_fermion -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_sqd.fermion.solve_fermion ---- - - - -# qiskit\_addon\_sqd.fermion.solve\_fermion - - - Approximate the ground state given molecular integrals and a set of electronic configurations. - - **Parameters** - - * **bitstring\_matrix** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")*\[*[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")*,* [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")*] |* [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – - - A set of configurations defining the subspace onto which the Hamiltonian will be projected and diagonalized. This is a 2D array of `bool` representations of bit values such that each row represents a single bitstring. The spin-up configurations should be specified by column indices in range `(N, N/2]`, and the spin-down configurations should be specified by column indices in range `(N/2, 0]`, where `N` is the number of qubits. - - (DEPRECATED) The configurations may also be specified by a length-2 tuple of sorted 1D arrays containing unsigned integer representations of the determinants. The two lists should represent the spin-up and spin-down orbitals, respectively. - - * **hcore** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – Core Hamiltonian matrix representing single-electron integrals - - * **eri** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – Electronic repulsion integrals representing two-electron integrals - - * **open\_shell** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – A flag specifying whether configurations from the left and right halves of the bitstrings should be kept separate. If `False`, CI strings from the left and right halves of the bitstrings are combined into a single set of unique configurations and used for both the alpha and beta subspaces. - - * **spin\_sq** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| None*) – Target value for the total spin squared for the ground state. If `None`, no spin will be imposed. - - * **max\_davidson** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The maximum number of cycles of Davidson’s algorithm - - * **verbose** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| None*) – A verbosity level between 0 and 10 - - **Returns** - - * Minimum energy from SCI calculation - * SCI coefficients - * Average orbital occupancy - * Expectation value of spin-squared - - **Return type** - - A tuple containing - - diff --git a/docs/api/qiskit-addon-sqd/fermion.mdx b/docs/api/qiskit-addon-sqd/fermion.mdx index c20e2b230b1..a87ec3c9552 100644 --- a/docs/api/qiskit-addon-sqd/fermion.mdx +++ b/docs/api/qiskit-addon-sqd/fermion.mdx @@ -1,17 +1,225 @@ -# Fermion +--- +title: fermion +description: API reference for qiskit_addon_sqd.fermion +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_addon_sqd.fermion +--- - + + +# Fermion + +`qiskit_addon_sqd.fermion` Functions for the study of fermionic systems. -| | | -| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | -| [`bitstring_matrix_to_ci_strs`](fermion-bitstring-matrix-to-ci-strs "qiskit_addon_sqd.fermion.bitstring_matrix_to_ci_strs") | Convert bitstrings (rows) in a `bitstring_matrix` into integer representations of determinants. | -| [`enlarge_batch_from_transitions`](fermion-enlarge-batch-from-transitions "qiskit_addon_sqd.fermion.enlarge_batch_from_transitions") | Apply the set of transition operators to the configurations represented in `bitstring_matrix`. | -| [`flip_orbital_occupancies`](fermion-flip-orbital-occupancies "qiskit_addon_sqd.fermion.flip_orbital_occupancies") | Flip an orbital occupancy array to match the indexing of a bitstring. | -| [`solve_fermion`](fermion-solve-fermion "qiskit_addon_sqd.fermion.solve_fermion") | Approximate the ground state given molecular integrals and a set of electronic configurations. | -| [`optimize_orbitals`](fermion-optimize-orbitals "qiskit_addon_sqd.fermion.optimize_orbitals") | Optimize orbitals to produce a minimal ground state. | -| [`rotate_integrals`](fermion-rotate-integrals "qiskit_addon_sqd.fermion.rotate_integrals") | Perform a similarity transform on the integrals. | -| [`bitstring_matrix_to_sorted_addresses`](fermion-bitstring-matrix-to-sorted-addresses "qiskit_addon_sqd.fermion.bitstring_matrix_to_sorted_addresses") | Convert a bitstring matrix into a sorted array of unique, unsigned integers. | +### bitstring\_matrix\_to\_ci\_strs + + + Convert bitstrings (rows) in a `bitstring_matrix` into integer representations of determinants. + + This function separates each bitstring in `bitstring_matrix` in half, flips the bits and translates them into integer representations, and finally appends them to their respective (spin-up or spin-down) lists. Those lists are sorted and output from this function. + + **Parameters** + + * **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring + * **open\_shell** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – A flag specifying whether unique configurations from the left and right halves of the bitstrings should be kept separate. If `False`, configurations from the left and right halves of the bitstrings are combined into a single set of unique configurations. That combined set will be returned for both the left and right bitstrings. + + **Returns** + + A length-2 tuple of determinant lists representing the right (spin-up) and left (spin-down) halves of the bitstrings, respectively. + + **Return type** + + [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)"), [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")] + + +### enlarge\_batch\_from\_transitions + + + Apply the set of transition operators to the configurations represented in `bitstring_matrix`. + + **Parameters** + + * **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring. + * **transition\_operators** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 1D or 2D array `I`, `+`, `-`, and `n` strings representing the action of the identity, creation, annihilation, or number operators. Each row represents a transition operator. + + **Returns** + + Bitstring matrix representing the augmented set of electronic configurations after applying the excitation operators. + + **Return type** + + [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)") + + +### flip\_orbital\_occupancies + + + Flip an orbital occupancy array to match the indexing of a bitstring. + + This function reformats a 1D array of spin-orbital occupancies formatted like: + + > `[occ_a_1, occ_a_2, ..., occ_a_N, occ_b_1, ..., occ_b_N]` + + To an array formatted like: + + > `[occ_a_N, ..., occ_a_1, occ_b_N, ..., occ_b_1]` + + where `N` is the number of spatial orbitals. + + **Return type** + + [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)") + + +### solve\_fermion + + + Approximate the ground state given molecular integrals and a set of electronic configurations. + + **Parameters** + + * **bitstring\_matrix** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")*\[*[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")*,* [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")*] |* [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – + + A set of configurations defining the subspace onto which the Hamiltonian will be projected and diagonalized. This is a 2D array of `bool` representations of bit values such that each row represents a single bitstring. The spin-up configurations should be specified by column indices in range `(N, N/2]`, and the spin-down configurations should be specified by column indices in range `(N/2, 0]`, where `N` is the number of qubits. + + (DEPRECATED) The configurations may also be specified by a length-2 tuple of sorted 1D arrays containing unsigned integer representations of the determinants. The two lists should represent the spin-up and spin-down orbitals, respectively. + + * **hcore** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – Core Hamiltonian matrix representing single-electron integrals + + * **eri** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – Electronic repulsion integrals representing two-electron integrals + + * **open\_shell** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – A flag specifying whether configurations from the left and right halves of the bitstrings should be kept separate. If `False`, CI strings from the left and right halves of the bitstrings are combined into a single set of unique configurations and used for both the alpha and beta subspaces. + + * **spin\_sq** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| None*) – Target value for the total spin squared for the ground state. If `None`, no spin will be imposed. + + * **max\_davidson** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The maximum number of cycles of Davidson’s algorithm + + * **verbose** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| None*) – A verbosity level between 0 and 10 + + **Returns** + + * Minimum energy from SCI calculation + * SCI coefficients + * Average orbital occupancy + * Expectation value of spin-squared + + **Return type** + + [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)"), [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)"), [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")], [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")] + + +### optimize\_orbitals + + + Optimize orbitals to produce a minimal ground state. + + The process involves iterating over 3 steps: + + **For `num_iters` iterations:** + + * Rotate the integrals with respect to the parameters, `k_flat` + * Diagonalize and approximate the groundstate energy and wavefunction amplitudes + * Optimize `k_flat` using gradient descent and the wavefunction amplitudes found in Step 2 + + Refer to [Sec. II A 4](https://arxiv.org/pdf/2405.05068) for more detailed discussion on this orbital optimization technique. + + **Parameters** + + * **bitstring\_matrix** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")*\[*[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")*,* [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")*] |* [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – + + A set of configurations defining the subspace onto which the Hamiltonian will be projected and diagonalized. This is a 2D array of `bool` representations of bit values such that each row represents a single bitstring. The spin-up configurations should be specified by column indices in range `(N, N/2]`, and the spin-down configurations should be specified by column indices in range `(N/2, 0]`, where `N` is the number of qubits. + + (DEPRECATED) The configurations may also be specified by a length-2 tuple of sorted 1D arrays containing unsigned integer representations of the determinants. The two lists should represent the spin-up and spin-down orbitals, respectively. + + * **hcore** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – Core Hamiltonian matrix representing single-electron integrals + + * **eri** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – Electronic repulsion integrals representing two-electron integrals + + * **k\_flat** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – 1D array defining the orbital transform. This array will be reshaped to be of shape (# orbitals, # orbitals) before being used as a similarity transform operator on the orbitals. Thus `len(k_flat)=# orbitals**2`. + + * **open\_shell** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – A flag specifying whether configurations from the left and right halves of the bitstrings should be kept separate. If `False`, CI strings from the left and right halves of the bitstrings are combined into a single set of unique configurations and used for both the alpha and beta subspaces. + + * **spin\_sq** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – Target value for the total spin squared for the ground state + + * **num\_iters** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of iterations of orbital optimization to perform + + * **max\_davidson** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The maximum number of cycles of Davidson’s algorithm to perform during diagonalization. + + * **num\_steps\_grad** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of steps of gradient descent to perform during each optimization iteration + + * **learning\_rate** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – The learning rate to use during gradient descent + + **Returns** + + * The groundstate energy found during the last optimization iteration + * An optimized 1D array defining the orbital transform + * Average orbital occupancy + + **Return type** + + [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)"), [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)"), [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")]] + + +### rotate\_integrals + + + Perform a similarity transform on the integrals. + + The transformation is described as: + +$$ +\hat{\widetilde{H}} = \hat{U^{\dagger}}(k)\hat{H}\hat{U}(k) +$$ + + For more information on how $\hat{U}$ and $\hat{U^{\dagger}}$ are generated from `k_flat` and applied to the one- and two-body integrals, refer to [Sec. II A 4](https://arxiv.org/pdf/2405.05068). + + **Parameters** + + * **hcore** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – Core Hamiltonian matrix representing single-electron integrals + + * **eri** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – Electronic repulsion integrals representing two-electron integrals + + * **k\_flat** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – + + 1D array defining the orbital transform. Refer to [Sec. II A 4](https://arxiv.org/pdf/2405.05068) for more information on how these values are used to generate the transform operator. + + **Returns** + + * The rotated core Hamiltonian matrix + * The rotated ERI matrix + + **Return type** + + [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)"), [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")] + + +### bitstring\_matrix\_to\_sorted\_addresses + + + Convert a bitstring matrix into a sorted array of unique, unsigned integers. + + This function separates each bitstring in `bitstring_matrix` in half, flips the bits and translates them into integer representations, and finally appends them to their respective (spin-up or spin-down) lists. Those lists are sorted and output from this function. + + + The function `qiskit_addon_sqd.fermion.bitstring_matrix_to_sorted_addresses()` is deprecated as of qiskit-addon-sqd 0.6.0. It will be removed no sooner than qiskit-addon-sqd 0.8.0. Use the bitstring\_matrix\_to\_ci\_strs function. + + + **Parameters** + + * **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring + * **open\_shell** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – A flag specifying whether unique addresses from the left and right halves of the bitstrings should be kept separate. If `False`, addresses from the left and right halves of the bitstrings are combined into a single set of unique addresses. That combined set will be returned for both the left and right bitstrings. + + **Returns** + + A length-2 tuple of sorted, unique determinants representing the left (spin-down) and right (spin-up) halves of the bitstrings, respectively. + + **Return type** + + [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)"), [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")] + + diff --git a/docs/api/qiskit-addon-sqd/index.mdx b/docs/api/qiskit-addon-sqd/index.mdx new file mode 100644 index 00000000000..b4ca2f7208f --- /dev/null +++ b/docs/api/qiskit-addon-sqd/index.mdx @@ -0,0 +1,9 @@ + + +# `qiskit-addon-sqd` API reference + +* [Configuration recovery (`qiskit_addon_sqd.configuration_recovery`)](configuration-recovery) +* [Counts (`qiskit_addon_sqd.counts`)](counts) +* [Fermion (`qiskit_addon_sqd.fermion`)](fermion) +* [Qubit (`qiskit_addon_sqd.qubit`)](qubit) +* [Subsampling (`qiskit_addon_sqd.subsampling`)](subsampling) diff --git a/docs/api/qiskit-addon-sqd/qiskit-addon-sqd.mdx b/docs/api/qiskit-addon-sqd/qiskit-addon-sqd.mdx deleted file mode 100644 index 0a1debfb874..00000000000 --- a/docs/api/qiskit-addon-sqd/qiskit-addon-sqd.mdx +++ /dev/null @@ -1,20 +0,0 @@ -# Sample-based Quantum Diagonalization - - - - - -Primary SQD functionality. - -| | -| - | - -## Modules - -| | | -| ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | -| [`configuration_recovery`](configuration-recovery#module-qiskit_addon_sqd.configuration_recovery "qiskit_addon_sqd.configuration_recovery") | Functions for performing self-consistent configuration recovery. | -| [`subsampling`](subsampling#module-qiskit_addon_sqd.subsampling "qiskit_addon_sqd.subsampling") | Functions for creating batches of samples from a bitstring matrix. | -| [`counts`](counts#module-qiskit_addon_sqd.counts "qiskit_addon_sqd.counts") | Functions for transforming counts dictionaries. | -| [`fermion`](fermion#module-qiskit_addon_sqd.fermion "qiskit_addon_sqd.fermion") | Functions for the study of fermionic systems. | -| [`qubit`](qubit#module-qiskit_addon_sqd.qubit "qiskit_addon_sqd.qubit") | Functions for handling quantum samples. | diff --git a/docs/api/qiskit-addon-sqd/qubit-matrix-elements-from-pauli.mdx b/docs/api/qiskit-addon-sqd/qubit-matrix-elements-from-pauli.mdx deleted file mode 100644 index e8fa7a09b4f..00000000000 --- a/docs/api/qiskit-addon-sqd/qubit-matrix-elements-from-pauli.mdx +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: matrix_elements_from_pauli -description: API reference for qiskit_addon_sqd.qubit.matrix_elements_from_pauli -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_sqd.qubit.matrix_elements_from_pauli ---- - - - -# qiskit\_addon\_sqd.qubit.matrix\_elements\_from\_pauli - - - Find the sparse matrix elements of a Pauli operator in the subspace defined by the bitstrings. - - The sparse matrix, `A`, defined by the outputs represents an `NxN` matrix s.t. `N` is the number of rows in `bitstring_matrix`. The rows of `A` represent the input configurations, and the columns represent the connected component associated with the configuration in the corresponding row. The output arrays define the sparse matrix, `A`, as follows: - - `A[rows[k], cols[k]] = amplutides[k]`. - - - The bitstrings in the `bitstring_matrix` must be unique and sorted in ascending order according to their unsigned integer representation. Otherwise the projection will return wrong results. This function does not explicitly check for uniqueness and order because this can be rather time consuming. See [`qiskit_addon_sqd.qubit.sort_and_remove_duplicates()`](qubit-sort-and-remove-duplicates "qiskit_addon_sqd.qubit.sort_and_remove_duplicates") for a simple way to ensure your bitstring matrix is well-formatted. - - - - This function relies on `jax` to efficiently perform some calculations. `jax` converts the bit arrays to `int64_t`, which means the bit arrays in `bitstring_matrix` may not have length greater than `63`. - - - **Parameters** - - * **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring. The bitstrings in the matrix must be sorted according to their unsigned integer representations. Otherwise the projection will return wrong results. - * **pauli** ([*Pauli*](/api/qiskit/qiskit.quantum_info.Pauli "(in Qiskit v1.2)")) – A Pauli operator for which to find connected elements - - **Returns** - - * The complex amplitudes corresponding to the nonzero matrix elements - * The row indices corresponding to non-zero matrix elements - * The column indices corresponding to non-zero matrix elements - - **Raises** - - [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Bitstrings (rows) in `bitstring_matrix` must have length \< `64`. - - **Return type** - - [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)"), [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)"), [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")] - - diff --git a/docs/api/qiskit-addon-sqd/qubit-project-operator-to-subspace.mdx b/docs/api/qiskit-addon-sqd/qubit-project-operator-to-subspace.mdx deleted file mode 100644 index 21a5fdd3002..00000000000 --- a/docs/api/qiskit-addon-sqd/qubit-project-operator-to-subspace.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: project_operator_to_subspace -description: API reference for qiskit_addon_sqd.qubit.project_operator_to_subspace -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_sqd.qubit.project_operator_to_subspace ---- - - - -# qiskit\_addon\_sqd.qubit.project\_operator\_to\_subspace - - - Project a Pauli operator onto a Hilbert subspace defined by the computational basis states (rows) in `bitstring_matrix`. - - The output sparse matrix, `A`, represents an `NxN` matrix s.t. `N` is the number of rows in `bitstring_matrix`. The rows of `A` represent the input configurations, and the columns represent the connected component associated with the configuration in the corresponding row. The non-zero elements of the matrix represent the complex amplitudes associated with the connected components. - - - The bitstrings in the `bitstring_matrix` must be unique and sorted in ascending order according to their unsigned integer representation. Otherwise the projection will return wrong results. This function does not explicitly check for uniqueness and order because this can be rather time consuming. See [`qiskit_addon_sqd.qubit.sort_and_remove_duplicates()`](qubit-sort-and-remove-duplicates "qiskit_addon_sqd.qubit.sort_and_remove_duplicates") for a simple way to ensure your bitstring matrix is well-formatted. - - - - This function relies on `jax` to efficiently perform some calculations. `jax` converts the bit arrays to `int64_t`, which means the bit arrays in `bitstring_matrix` may not have length greater than `63`. - - - **Parameters** - - * **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring. This set of bitstrings specifies the subspace into which the `hamiltonian` will be projected and diagonalized. - * **hamiltonian** ([*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)")) – A Pauli operator to project onto a Hilbert subspace defined by `bitstring_matrix`. - * **verbose** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – Whether to print the stage of the subroutine. - - **Returns** - - A [scipy.sparse.coo\_matrix](https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.coo_matrix.html#coo-matrix) representing the operator projected in the subspace. The rows represent the input configurations, and the columns represent the connected component associated with the configuration in the corresponding row. The non-zero elements of the matrix represent the complex amplitudes associated with the pairs of connected components. - - **Raises** - - [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Bitstrings (rows) in `bitstring_matrix` must have length \< `64`. - - **Return type** - - *spmatrix* - - diff --git a/docs/api/qiskit-addon-sqd/qubit-solve-qubit.mdx b/docs/api/qiskit-addon-sqd/qubit-solve-qubit.mdx deleted file mode 100644 index 49ee43597dc..00000000000 --- a/docs/api/qiskit-addon-sqd/qubit-solve-qubit.mdx +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: solve_qubit -description: API reference for qiskit_addon_sqd.qubit.solve_qubit -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_sqd.qubit.solve_qubit ---- - - - -# qiskit\_addon\_sqd.qubit.solve\_qubit - - - Find the energies and eigenstates of a Hamiltonian projected into a subspace. - - The subspace is defined by a collection of computational basis states which are specified by the bitstrings (rows) in the `bitstring_matrix`. - - This function calls [scipy.sparse.linalg.eigsh](https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.eigsh.html#eigsh) for the diagonalization. - - **Parameters** - - * **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring. This set of bitstrings specifies the subspace into which the `hamiltonian` will be projected and diagonalized. - - * **hamiltonian** ([*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)")) – A Hamiltonian specified as a Pauli operator. - - * **verbose** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – Whether to print the stage of the subroutine. - - * **\*\*scipy\_kwargs** – - - Keyword arguments to be passed to [scipy.sparse.linalg.eigsh](https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.eigsh.html#eigsh). - - **Returns** - - * 1D array with the eigenvalues - * 2D array with the eigenvectors. Each column represents an eigenvector. - - **Raises** - - [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Bitstrings (rows) in `bitstring_matrix` must have length \< `64`. - - **Return type** - - [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)"), [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")] - - diff --git a/docs/api/qiskit-addon-sqd/qubit-sort-and-remove-duplicates.mdx b/docs/api/qiskit-addon-sqd/qubit-sort-and-remove-duplicates.mdx deleted file mode 100644 index c17ce6907d1..00000000000 --- a/docs/api/qiskit-addon-sqd/qubit-sort-and-remove-duplicates.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: sort_and_remove_duplicates -description: API reference for qiskit_addon_sqd.qubit.sort_and_remove_duplicates -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_sqd.qubit.sort_and_remove_duplicates ---- - - - -# qiskit\_addon\_sqd.qubit.sort\_and\_remove\_duplicates - - - Sort a bitstring matrix and remove duplicate entries. - - The lowest bitstring values will be placed in the lowest-indexed rows. - - **Parameters** - - **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring. - - **Returns** - - Sorted version of `bitstring_matrix` without repeated rows. - - **Return type** - - [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)") - - diff --git a/docs/api/qiskit-addon-sqd/qubit.mdx b/docs/api/qiskit-addon-sqd/qubit.mdx index 2f23f637950..827c05dcbc7 100644 --- a/docs/api/qiskit-addon-sqd/qubit.mdx +++ b/docs/api/qiskit-addon-sqd/qubit.mdx @@ -1,15 +1,144 @@ -# Qubit +--- +title: qubit +description: API reference for qiskit_addon_sqd.qubit +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_addon_sqd.qubit +--- - + + +# Qubit + +`qiskit_addon_sqd.qubit` Functions for handling quantum samples. -| | | -| -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -| [`solve_qubit`](qubit-solve-qubit "qiskit_addon_sqd.qubit.solve_qubit") | Find the energies and eigenstates of a Hamiltonian projected into a subspace. | -| [`project_operator_to_subspace`](qubit-project-operator-to-subspace "qiskit_addon_sqd.qubit.project_operator_to_subspace") | Project a Pauli operator onto a Hilbert subspace defined by the computational basis states (rows) in `bitstring_matrix`. | -| [`sort_and_remove_duplicates`](qubit-sort-and-remove-duplicates "qiskit_addon_sqd.qubit.sort_and_remove_duplicates") | Sort a bitstring matrix and remove duplicate entries. | -| [`matrix_elements_from_pauli`](qubit-matrix-elements-from-pauli "qiskit_addon_sqd.qubit.matrix_elements_from_pauli") | Find the sparse matrix elements of a Pauli operator in the subspace defined by the bitstrings. | -| [`sort_and_remove_duplicates`](qubit-sort-and-remove-duplicates "qiskit_addon_sqd.qubit.sort_and_remove_duplicates") | Sort a bitstring matrix and remove duplicate entries. | +### solve\_qubit + + + Find the energies and eigenstates of a Hamiltonian projected into a subspace. + + The subspace is defined by a collection of computational basis states which are specified by the bitstrings (rows) in the `bitstring_matrix`. + + This function calls [scipy.sparse.linalg.eigsh](https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.eigsh.html#eigsh) for the diagonalization. + + **Parameters** + + * **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring. This set of bitstrings specifies the subspace into which the `hamiltonian` will be projected and diagonalized. + + * **hamiltonian** ([*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)")) – A Hamiltonian specified as a Pauli operator. + + * **verbose** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – Whether to print the stage of the subroutine. + + * **\*\*scipy\_kwargs** – + + Keyword arguments to be passed to [scipy.sparse.linalg.eigsh](https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.eigsh.html#eigsh). + + **Returns** + + * 1D array with the eigenvalues + * 2D array with the eigenvectors. Each column represents an eigenvector. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Bitstrings (rows) in `bitstring_matrix` must have length \< `64`. + + **Return type** + + [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)"), [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")] + + +### project\_operator\_to\_subspace + + + Project a Pauli operator onto a Hilbert subspace defined by the computational basis states (rows) in `bitstring_matrix`. + + The output sparse matrix, `A`, represents an `NxN` matrix s.t. `N` is the number of rows in `bitstring_matrix`. The rows of `A` represent the input configurations, and the columns represent the connected component associated with the configuration in the corresponding row. The non-zero elements of the matrix represent the complex amplitudes associated with the connected components. + + + The bitstrings in the `bitstring_matrix` must be unique and sorted in ascending order according to their unsigned integer representation. Otherwise the projection will return wrong results. This function does not explicitly check for uniqueness and order because this can be rather time consuming. See [`qiskit_addon_sqd.qubit.sort_and_remove_duplicates()`](#qiskit_addon_sqd.qubit.sort_and_remove_duplicates "qiskit_addon_sqd.qubit.sort_and_remove_duplicates") for a simple way to ensure your bitstring matrix is well-formatted. + + + + This function relies on `jax` to efficiently perform some calculations. `jax` converts the bit arrays to `int64_t`, which means the bit arrays in `bitstring_matrix` may not have length greater than `63`. + + + **Parameters** + + * **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring. This set of bitstrings specifies the subspace into which the `hamiltonian` will be projected and diagonalized. + * **hamiltonian** ([*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)")) – A Pauli operator to project onto a Hilbert subspace defined by `bitstring_matrix`. + * **verbose** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – Whether to print the stage of the subroutine. + + **Returns** + + A [scipy.sparse.coo\_matrix](https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.coo_matrix.html#coo-matrix) representing the operator projected in the subspace. The rows represent the input configurations, and the columns represent the connected component associated with the configuration in the corresponding row. The non-zero elements of the matrix represent the complex amplitudes associated with the pairs of connected components. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Bitstrings (rows) in `bitstring_matrix` must have length \< `64`. + + **Return type** + + *spmatrix* + + +### sort\_and\_remove\_duplicates + + + Sort a bitstring matrix and remove duplicate entries. + + The lowest bitstring values will be placed in the lowest-indexed rows. + + **Parameters** + + **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring. + + **Returns** + + Sorted version of `bitstring_matrix` without repeated rows. + + **Return type** + + [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)") + + +### matrix\_elements\_from\_pauli + + + Find the sparse matrix elements of a Pauli operator in the subspace defined by the bitstrings. + + The sparse matrix, `A`, defined by the outputs represents an `NxN` matrix s.t. `N` is the number of rows in `bitstring_matrix`. The rows of `A` represent the input configurations, and the columns represent the connected component associated with the configuration in the corresponding row. The output arrays define the sparse matrix, `A`, as follows: + + `A[rows[k], cols[k]] = amplutides[k]`. + + + The bitstrings in the `bitstring_matrix` must be unique and sorted in ascending order according to their unsigned integer representation. Otherwise the projection will return wrong results. This function does not explicitly check for uniqueness and order because this can be rather time consuming. See [`qiskit_addon_sqd.qubit.sort_and_remove_duplicates()`](#qiskit_addon_sqd.qubit.sort_and_remove_duplicates "qiskit_addon_sqd.qubit.sort_and_remove_duplicates") for a simple way to ensure your bitstring matrix is well-formatted. + + + + This function relies on `jax` to efficiently perform some calculations. `jax` converts the bit arrays to `int64_t`, which means the bit arrays in `bitstring_matrix` may not have length greater than `63`. + + + **Parameters** + + * **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring. The bitstrings in the matrix must be sorted according to their unsigned integer representations. Otherwise the projection will return wrong results. + * **pauli** ([*Pauli*](/api/qiskit/qiskit.quantum_info.Pauli "(in Qiskit v1.2)")) – A Pauli operator for which to find connected elements + + **Returns** + + * The complex amplitudes corresponding to the nonzero matrix elements + * The row indices corresponding to non-zero matrix elements + * The column indices corresponding to non-zero matrix elements + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Bitstrings (rows) in `bitstring_matrix` must have length \< `64`. + + **Return type** + + [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)"), [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)"), [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")] + + diff --git a/docs/api/qiskit-addon-sqd/release-notes.mdx b/docs/api/qiskit-addon-sqd/release-notes.mdx index ad59fd7e9a8..bba21bb0d66 100644 --- a/docs/api/qiskit-addon-sqd/release-notes.mdx +++ b/docs/api/qiskit-addon-sqd/release-notes.mdx @@ -20,9 +20,9 @@ in_page_toc_max_heading_level: 2 ### Bug Fixes -* Fixed a bug in [`qiskit_addon_sqd.fermion.solve_fermion()`](fermion-solve-fermion "qiskit_addon_sqd.fermion.solve_fermion") and [`qiskit_addon_sqd.fermion.optimize_orbitals()`](fermion-optimize-orbitals "qiskit_addon_sqd.fermion.optimize_orbitals") which causes the determinants for spin-up and spin-down to be incorrectly flipped before solving. +* Fixed a bug in [`qiskit_addon_sqd.fermion.solve_fermion()`](fermion#solve_fermion "qiskit_addon_sqd.fermion.solve_fermion") and [`qiskit_addon_sqd.fermion.optimize_orbitals()`](fermion#optimize_orbitals "qiskit_addon_sqd.fermion.optimize_orbitals") which causes the determinants for spin-up and spin-down to be incorrectly flipped before solving. -* Fixed a bug in open-shell workflows which would cause [`qiskit_addon_sqd.fermion.optimize_orbitals()`](fermion-optimize-orbitals "qiskit_addon_sqd.fermion.optimize_orbitals") to crash with a `malloc` error. +* Fixed a bug in open-shell workflows which would cause [`qiskit_addon_sqd.fermion.optimize_orbitals()`](fermion#optimize_orbitals "qiskit_addon_sqd.fermion.optimize_orbitals") to crash with a `malloc` error. @@ -34,7 +34,7 @@ in_page_toc_max_heading_level: 2 ### Upgrade Notes -* Specifying `addresses` as a keyword argument to [`qiskit_addon_sqd.fermion.solve_fermion()`](fermion-solve-fermion "qiskit_addon_sqd.fermion.solve_fermion") and [`qiskit_addon_sqd.fermion.optimize_orbitals()`](fermion-optimize-orbitals "qiskit_addon_sqd.fermion.optimize_orbitals") is no longer supported. Users may still pass `addresses` as the first positional argument; however, this usage is deprecated. Users are encouraged to pass the bitstring matrix defining the subspace as the first positional arguments to these functions, as shown below. +* Specifying `addresses` as a keyword argument to [`qiskit_addon_sqd.fermion.solve_fermion()`](fermion#solve_fermion "qiskit_addon_sqd.fermion.solve_fermion") and [`qiskit_addon_sqd.fermion.optimize_orbitals()`](fermion#optimize_orbitals "qiskit_addon_sqd.fermion.optimize_orbitals") is no longer supported. Users may still pass `addresses` as the first positional argument; however, this usage is deprecated. Users are encouraged to pass the bitstring matrix defining the subspace as the first positional arguments to these functions, as shown below. To upgrade, change this code @@ -83,7 +83,7 @@ in_page_toc_max_heading_level: 2 ### Deprecation Notes -* The [`qiskit_addon_sqd.fermion.bitstring_matrix_to_sorted_addresses()`](fermion-bitstring-matrix-to-sorted-addresses "qiskit_addon_sqd.fermion.bitstring_matrix_to_sorted_addresses") function has been deprecated in favor of [`qiskit_addon_sqd.fermion.bitstring_matrix_to_ci_strs()`](fermion-bitstring-matrix-to-ci-strs "qiskit_addon_sqd.fermion.bitstring_matrix_to_ci_strs"). These two functions behave the same with one key exception – [`qiskit_addon_sqd.fermion.bitstring_matrix_to_sorted_addresses()`](fermion-bitstring-matrix-to-sorted-addresses "qiskit_addon_sqd.fermion.bitstring_matrix_to_sorted_addresses") returns the configurations as `tuple(spin_dn, spin_up)`; whereas, [`qiskit_addon_sqd.fermion.bitstring_matrix_to_ci_strs()`](fermion-bitstring-matrix-to-ci-strs "qiskit_addon_sqd.fermion.bitstring_matrix_to_ci_strs") returns the configurations as `tuple(spin_up, spin_dn)`. +* The [`qiskit_addon_sqd.fermion.bitstring_matrix_to_sorted_addresses()`](fermion#bitstring_matrix_to_sorted_addresses "qiskit_addon_sqd.fermion.bitstring_matrix_to_sorted_addresses") function has been deprecated in favor of [`qiskit_addon_sqd.fermion.bitstring_matrix_to_ci_strs()`](fermion#bitstring_matrix_to_ci_strs "qiskit_addon_sqd.fermion.bitstring_matrix_to_ci_strs"). These two functions behave the same with one key exception – [`qiskit_addon_sqd.fermion.bitstring_matrix_to_sorted_addresses()`](fermion#bitstring_matrix_to_sorted_addresses "qiskit_addon_sqd.fermion.bitstring_matrix_to_sorted_addresses") returns the configurations as `tuple(spin_dn, spin_up)`; whereas, [`qiskit_addon_sqd.fermion.bitstring_matrix_to_ci_strs()`](fermion#bitstring_matrix_to_ci_strs "qiskit_addon_sqd.fermion.bitstring_matrix_to_ci_strs") returns the configurations as `tuple(spin_up, spin_dn)`. To migrate @@ -104,7 +104,7 @@ in_page_toc_max_heading_level: 2 ci_strs_up, ci_strs_dn = bitstring_matrix_to_ci_strs(bs_matrix, open_shell=True) ``` -* The `addresses` argument to [`qiskit_addon_sqd.fermion.solve_fermion()`](fermion-solve-fermion "qiskit_addon_sqd.fermion.solve_fermion") and [`qiskit_addon_sqd.fermion.optimize_orbitals()`](fermion-optimize-orbitals "qiskit_addon_sqd.fermion.optimize_orbitals") has been deprecated in favor of `bitstring_matrix`. Users are no longer required to convert their configurations to integers; instead, they should now pass in the bitstring matrix specifying the subspace onto which to project and diagonalize the Hamiltonian. The conversion to the integer representation of determinants will be done internally. +* The `addresses` argument to [`qiskit_addon_sqd.fermion.solve_fermion()`](fermion#solve_fermion "qiskit_addon_sqd.fermion.solve_fermion") and [`qiskit_addon_sqd.fermion.optimize_orbitals()`](fermion#optimize_orbitals "qiskit_addon_sqd.fermion.optimize_orbitals") has been deprecated in favor of `bitstring_matrix`. Users are no longer required to convert their configurations to integers; instead, they should now pass in the bitstring matrix specifying the subspace onto which to project and diagonalize the Hamiltonian. The conversion to the integer representation of determinants will be done internally. @@ -112,7 +112,7 @@ in_page_toc_max_heading_level: 2 ### Bug Fixes -* Fixed a bug in [`qiskit_addon_sqd.configuration_recovery.recover_configurations()`](configuration-recovery-recover-configurations "qiskit_addon_sqd.configuration_recovery.recover_configurations") which would sometimes cause a divide-by-zero error when calculating individual bit-flip probability. +* Fixed a bug in [`qiskit_addon_sqd.configuration_recovery.recover_configurations()`](configuration-recovery#recover_configurations "qiskit_addon_sqd.configuration_recovery.recover_configurations") which would sometimes cause a divide-by-zero error when calculating individual bit-flip probability. * Fixes a bug that caused configuration recovery to fail on bitstrings of length greater than 72. @@ -128,7 +128,7 @@ in_page_toc_max_heading_level: 2 ### Upgrade Notes -* The [`qiskit_addon_sqd.counts.generate_counts_bipartite_hamming()`](counts-generate-counts-bipartite-hamming "qiskit_addon_sqd.counts.generate_counts_bipartite_hamming"), [`qiskit_addon_sqd.subsampling.postselect_and_subsample()`](subsampling-postselect-and-subsample "qiskit_addon_sqd.subsampling.postselect_and_subsample"), and [`qiskit_addon_sqd.configuration_recovery.post_select_by_hamming_weight()`](configuration-recovery-post-select-by-hamming-weight "qiskit_addon_sqd.configuration_recovery.post_select_by_hamming_weight") now require the `hamming_right` and `hamming_left` arguments to be specified as keyword arguments. Additionally, the `samples_per_batch` and `n_batches` arguments to [`qiskit_addon_sqd.subsampling.postselect_and_subsample()`](subsampling-postselect-and-subsample "qiskit_addon_sqd.subsampling.postselect_and_subsample") should now be passed as keyword arguments. +* The [`qiskit_addon_sqd.counts.generate_counts_bipartite_hamming()`](counts#generate_counts_bipartite_hamming "qiskit_addon_sqd.counts.generate_counts_bipartite_hamming"), [`qiskit_addon_sqd.subsampling.postselect_and_subsample()`](subsampling#postselect_and_subsample "qiskit_addon_sqd.subsampling.postselect_and_subsample"), and [`qiskit_addon_sqd.configuration_recovery.post_select_by_hamming_weight()`](configuration-recovery#post_select_by_hamming_weight "qiskit_addon_sqd.configuration_recovery.post_select_by_hamming_weight") now require the `hamming_right` and `hamming_left` arguments to be specified as keyword arguments. Additionally, the `samples_per_batch` and `n_batches` arguments to [`qiskit_addon_sqd.subsampling.postselect_and_subsample()`](subsampling#postselect_and_subsample "qiskit_addon_sqd.subsampling.postselect_and_subsample") should now be passed as keyword arguments. To upgrade @@ -198,7 +198,7 @@ This is a minor release which introduces a couple of small, but important, break ### Upgrade Notes -* The [`qiskit_addon_sqd.counts.generate_counts_bipartite_hamming()`](counts-generate-counts-bipartite-hamming "qiskit_addon_sqd.counts.generate_counts_bipartite_hamming"), [`qiskit_addon_sqd.subsampling.postselect_and_subsample()`](subsampling-postselect-and-subsample "qiskit_addon_sqd.subsampling.postselect_and_subsample"), and [`qiskit_addon_sqd.configuration_recovery.post_select_by_hamming_weight()`](configuration-recovery-post-select-by-hamming-weight "qiskit_addon_sqd.configuration_recovery.post_select_by_hamming_weight") now take the `hamming_right` positional argument before the `hamming_left` argument to better match the rest of the workflow. +* The [`qiskit_addon_sqd.counts.generate_counts_bipartite_hamming()`](counts#generate_counts_bipartite_hamming "qiskit_addon_sqd.counts.generate_counts_bipartite_hamming"), [`qiskit_addon_sqd.subsampling.postselect_and_subsample()`](subsampling#postselect_and_subsample "qiskit_addon_sqd.subsampling.postselect_and_subsample"), and [`qiskit_addon_sqd.configuration_recovery.post_select_by_hamming_weight()`](configuration-recovery#post_select_by_hamming_weight "qiskit_addon_sqd.configuration_recovery.post_select_by_hamming_weight") now take the `hamming_right` positional argument before the `hamming_left` argument to better match the rest of the workflow. To upgrade diff --git a/docs/api/qiskit-addon-sqd/subsampling-postselect-and-subsample.mdx b/docs/api/qiskit-addon-sqd/subsampling-postselect-and-subsample.mdx deleted file mode 100644 index 8f8e8514df0..00000000000 --- a/docs/api/qiskit-addon-sqd/subsampling-postselect-and-subsample.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: postselect_and_subsample -description: API reference for qiskit_addon_sqd.subsampling.postselect_and_subsample -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_sqd.subsampling.postselect_and_subsample ---- - - - -# qiskit\_addon\_sqd.subsampling.postselect\_and\_subsample - - - Subsample batches of bit arrays with correct hamming weight from an input `bitstring_matrix`. - - Bitstring samples with incorrect hamming weight on either their left or right half will not be sampled. - - Each individual batch will be sampled without replacement from the input `bitstring_matrix`. Samples will be replaced after creation of each batch, so different batches may contain identical samples. - - **Parameters** - - * **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring. - * **probabilities** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 1D array specifying a probability distribution over the bitstrings - * **hamming\_right** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The target hamming weight for the right half of sampled bitstrings - * **hamming\_left** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The target hamming weight for the left half of sampled bitstrings - * **samples\_per\_batch** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of samples to draw for each batch - * **num\_batches** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of batches to generate - * **rand\_seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| None*) – A seed to control random behavior - - **Returns** - - A list of bitstring matrices with correct hamming weight subsampled from the input bitstring matrix - - **Raises** - - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The number of elements in `probabilities` must equal the number of rows in `bitstring_matrix`. - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Hamming weights must be non-negative integers. - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Samples per batch and number of batches must be positive integers. - - **Return type** - - [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")] - - diff --git a/docs/api/qiskit-addon-sqd/subsampling-subsample.mdx b/docs/api/qiskit-addon-sqd/subsampling-subsample.mdx deleted file mode 100644 index 16ff2a9166c..00000000000 --- a/docs/api/qiskit-addon-sqd/subsampling-subsample.mdx +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: subsample -description: API reference for qiskit_addon_sqd.subsampling.subsample -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_sqd.subsampling.subsample ---- - - - -# qiskit\_addon\_sqd.subsampling.subsample - - - Subsample batches of bit arrays from an input `bitstring_matrix`. - - Each individual batch will be sampled without replacement from the input `bitstring_matrix`. Samples will be replaced after creation of each batch, so different batches may contain identical samples. - - **Parameters** - - * **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring. - * **probabilities** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 1D array specifying a probability distribution over the bitstrings - * **samples\_per\_batch** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of samples to draw for each batch - * **num\_batches** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of batches to generate - * **rand\_seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| None*) – A seed to control random behavior - - **Returns** - - A list of bitstring matrices subsampled from the input bitstring matrix. - - **Raises** - - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The number of elements in `probabilities` must equal the number of rows in `bitstring_matrix`. - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Samples per batch and number of batches must be positive integers. - - **Return type** - - [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")] - - diff --git a/docs/api/qiskit-addon-sqd/subsampling.mdx b/docs/api/qiskit-addon-sqd/subsampling.mdx index aa5208856ca..8a66512bb95 100644 --- a/docs/api/qiskit-addon-sqd/subsampling.mdx +++ b/docs/api/qiskit-addon-sqd/subsampling.mdx @@ -1,12 +1,81 @@ -# Subsampling +--- +title: subsampling +description: API reference for qiskit_addon_sqd.subsampling +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_addon_sqd.subsampling +--- - + + +# Subsampling + +`qiskit_addon_sqd.subsampling` Functions for creating batches of samples from a bitstring matrix. -| | | -| -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | -| [`subsample`](subsampling-subsample "qiskit_addon_sqd.subsampling.subsample") | Subsample batches of bit arrays from an input `bitstring_matrix`. | -| [`postselect_and_subsample`](subsampling-postselect-and-subsample "qiskit_addon_sqd.subsampling.postselect_and_subsample") | Subsample batches of bit arrays with correct hamming weight from an input `bitstring_matrix`. | +### subsample + + + Subsample batches of bit arrays from an input `bitstring_matrix`. + + Each individual batch will be sampled without replacement from the input `bitstring_matrix`. Samples will be replaced after creation of each batch, so different batches may contain identical samples. + + **Parameters** + + * **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring. + * **probabilities** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 1D array specifying a probability distribution over the bitstrings + * **samples\_per\_batch** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of samples to draw for each batch + * **num\_batches** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of batches to generate + * **rand\_seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| None*) – A seed to control random behavior + + **Returns** + + A list of bitstring matrices subsampled from the input bitstring matrix. + + **Raises** + + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The number of elements in `probabilities` must equal the number of rows in `bitstring_matrix`. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Samples per batch and number of batches must be positive integers. + + **Return type** + + [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")] + + +### postselect\_and\_subsample + + + Subsample batches of bit arrays with correct hamming weight from an input `bitstring_matrix`. + + Bitstring samples with incorrect hamming weight on either their left or right half will not be sampled. + + Each individual batch will be sampled without replacement from the input `bitstring_matrix`. Samples will be replaced after creation of each batch, so different batches may contain identical samples. + + **Parameters** + + * **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring. + * **probabilities** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 1D array specifying a probability distribution over the bitstrings + * **hamming\_right** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The target hamming weight for the right half of sampled bitstrings + * **hamming\_left** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The target hamming weight for the left half of sampled bitstrings + * **samples\_per\_batch** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of samples to draw for each batch + * **num\_batches** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of batches to generate + * **rand\_seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| None*) – A seed to control random behavior + + **Returns** + + A list of bitstring matrices with correct hamming weight subsampled from the input bitstring matrix + + **Raises** + + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The number of elements in `probabilities` must equal the number of rows in `bitstring_matrix`. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Hamming weights must be non-negative integers. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Samples per batch and number of batches must be positive integers. + + **Return type** + + [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")] + + diff --git a/docs/api/qiskit-addon-utils/_toc.json b/docs/api/qiskit-addon-utils/_toc.json index 2e8456196c5..4a35002425a 100644 --- a/docs/api/qiskit-addon-utils/_toc.json +++ b/docs/api/qiskit-addon-utils/_toc.json @@ -5,6 +5,39 @@ "title": "API index", "url": "/api/qiskit-addon-utils" }, + { + "title": "qiskit_addon_utils.coloring", + "url": "/api/qiskit-addon-utils/coloring" + }, + { + "title": "qiskit_addon_utils.problem_generators", + "url": "/api/qiskit-addon-utils/problem-generators" + }, + { + "title": "qiskit_addon_utils.slicing", + "url": "/api/qiskit-addon-utils/slicing" + }, + { + "title": "qiskit_addon_utils.slicing.transpiler.passes", + "children": [ + { + "title": "Module overview", + "url": "/api/qiskit-addon-utils/slicing-transpiler-passes" + }, + { + "title": "CollectOpColor", + "url": "/api/qiskit-addon-utils/slicing-transpiler-passes-collect-op-color" + }, + { + "title": "CollectOpSize", + "url": "/api/qiskit-addon-utils/slicing-transpiler-passes-collect-op-size" + }, + { + "title": "CollectOpType", + "url": "/api/qiskit-addon-utils/slicing-transpiler-passes-collect-op-type" + } + ] + }, { "title": "Release notes", "url": "/api/qiskit-addon-utils/release-notes" diff --git a/docs/api/qiskit-addon-utils/coloring-auto-color-edges.mdx b/docs/api/qiskit-addon-utils/coloring-auto-color-edges.mdx deleted file mode 100644 index 6fca5ba39b5..00000000000 --- a/docs/api/qiskit-addon-utils/coloring-auto-color-edges.mdx +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: auto_color_edges -description: API reference for qiskit_addon_utils.coloring.auto_color_edges -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_utils.coloring.auto_color_edges ---- - - - -# auto\_color\_edges - - - Color the input edges of an undirected graph such that no two incident edges share a color. - - **Parameters** - - **edges** ([*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]]*) – The edges describing an undirected graph. - - **Returns** - - A dictionary mapping each edge to an integer representation of a color. - - **Return type** - - [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")\[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)"), [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")], [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")] - - diff --git a/docs/api/qiskit-addon-utils/coloring-is-valid-edge-coloring.mdx b/docs/api/qiskit-addon-utils/coloring-is-valid-edge-coloring.mdx deleted file mode 100644 index 63e6d2c44de..00000000000 --- a/docs/api/qiskit-addon-utils/coloring-is-valid-edge-coloring.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: is_valid_edge_coloring -description: API reference for qiskit_addon_utils.coloring.is_valid_edge_coloring -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_utils.coloring.is_valid_edge_coloring ---- - - - -# is\_valid\_edge\_coloring - - - Check whether an edge coloring scheme is valid. - - An edge coloring is valid if no two edges of the same color share a node. - - **Parameters** - - **coloring** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*],* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – A mapping from edges to integer representations of colors. - - **Returns** - - A boolean indicating whether the input coloring is valid. - - **Return type** - - [bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)") - - diff --git a/docs/api/qiskit-addon-utils/coloring.mdx b/docs/api/qiskit-addon-utils/coloring.mdx index 0b7e2668157..59e77834e79 100644 --- a/docs/api/qiskit-addon-utils/coloring.mdx +++ b/docs/api/qiskit-addon-utils/coloring.mdx @@ -1,12 +1,56 @@ -# coloring +--- +title: coloring +description: API reference for qiskit_addon_utils.coloring +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_addon_utils.coloring +--- - + + +# coloring + +`qiskit_addon_utils.coloring` Utility methods for coloring. -| | | -| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -| [`auto_color_edges`](coloring-auto-color-edges "qiskit_addon_utils.coloring.auto_color_edges") | Color the input edges of an undirected graph such that no two incident edges share a color. | -| [`is_valid_edge_coloring`](coloring-is-valid-edge-coloring "qiskit_addon_utils.coloring.is_valid_edge_coloring") | Check whether an edge coloring scheme is valid. | +### auto\_color\_edges + + + Color the input edges of an undirected graph such that no two incident edges share a color. + + **Parameters** + + **edges** ([*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]]*) – The edges describing an undirected graph. + + **Returns** + + A dictionary mapping each edge to an integer representation of a color. + + **Return type** + + [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")\[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)"), [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")], [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")] + + +### is\_valid\_edge\_coloring + + + Check whether an edge coloring scheme is valid. + + An edge coloring is valid if no two edges of the same color share a node. + + **Parameters** + + **coloring** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*],* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – A mapping from edges to integer representations of colors. + + **Returns** + + A boolean indicating whether the input coloring is valid. + + **Return type** + + [bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)") + + diff --git a/docs/api/qiskit-addon-utils/index.mdx b/docs/api/qiskit-addon-utils/index.mdx new file mode 100644 index 00000000000..4375028c58e --- /dev/null +++ b/docs/api/qiskit-addon-utils/index.mdx @@ -0,0 +1,10 @@ + + +# `qiskit-addon-utils` API reference + +This package contains functionality which is meant to supplement workflows involving one or more Qiskit addons. For example, this package contains functions for creating Hamiltonians, generating Trotter time evolution circuits, and slicing and combining quantum circuits in time-wise partitions. + +* [coloring (`qiskit_addon_utils.coloring`)](coloring) +* [problem\_generators (`qiskit_addon_utils.problem_generators`)](problem-generators) +* [slicing (`qiskit_addon_utils.slicing`)](slicing) +* [passes (`qiskit_addon_utils.slicing.transpiler.passes`)](slicing-transpiler-passes) diff --git a/docs/api/qiskit-addon-utils/problem-generators-generate-time-evolution-circuit.mdx b/docs/api/qiskit-addon-utils/problem-generators-generate-time-evolution-circuit.mdx deleted file mode 100644 index 74a01ce0bce..00000000000 --- a/docs/api/qiskit-addon-utils/problem-generators-generate-time-evolution-circuit.mdx +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: generate_time_evolution_circuit -description: API reference for qiskit_addon_utils.problem_generators.generate_time_evolution_circuit -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_utils.problem_generators.generate_time_evolution_circuit ---- - - - -# generate\_time\_evolution\_circuit - - - Model the time evolution of an operator. - - ```python - >>> from qiskit.quantum_info import SparsePauliOp - >>> from qiskit.synthesis import SuzukiTrotter - >>> from qiskit.transpiler import CouplingMap - >>> from qiskit_addon_utils.problem_generators import ( - ... PauliOrderStrategy, - ... generate_xyz_hamiltonian, - ... generate_time_evolution_circuit, - ... ) - ``` - - ```python - >>> coupling_map = CouplingMap.from_line(6) - >>> hamiltonian = generate_xyz_hamiltonian( - ... coupling_map, - ... coupling_constants=(0.4, 0.4, 0.0), - ... ext_magnetic_field=(0.0, 0.0, 0.6), - ... pauli_order_strategy=PauliOrderStrategy.InteractionThenColorZigZag, - ... ) - ``` - - ```python - >>> circ = generate_time_evolution_circuit( - ... hamiltonian, synthesis=SuzukiTrotter(order=2, reps=2), time=2.0 - ... ) - >>> _ = circ.draw("mpl", fold=-1) - ``` - - ![../\_images/qiskit\_addon\_utils-problem\_generators-generate\_time\_evolution\_circuit-1.png](/images/api/qiskit-addon-utils/qiskit_addon_utils-problem_generators-generate_time_evolution_circuit-1.png) - - **Parameters** - - * **operator** ([*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)")) – The operator for which to model the time evolution. - * **synthesis** ([*EvolutionSynthesis*](/api/qiskit/qiskit.synthesis.EvolutionSynthesis "(in Qiskit v1.2)") *| None*) – A synthesis strategy. If `None`, the default synthesis is the Lie-Trotter product formula with a single repetition. - * **time** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – The evolution time. - - **Returns** - - A [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)") implementing a time-evolved operator. - - **Return type** - - [*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)") - - diff --git a/docs/api/qiskit-addon-utils/problem-generators-generate-xyz-hamiltonian.mdx b/docs/api/qiskit-addon-utils/problem-generators-generate-xyz-hamiltonian.mdx deleted file mode 100644 index 794bd9a22d6..00000000000 --- a/docs/api/qiskit-addon-utils/problem-generators-generate-xyz-hamiltonian.mdx +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: generate_xyz_hamiltonian -description: API reference for qiskit_addon_utils.problem_generators.generate_xyz_hamiltonian -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_utils.problem_generators.generate_xyz_hamiltonian ---- - - - -# generate\_xyz\_hamiltonian - - - Generate a connectivity-aware qubit operator representing a quantum XYZ-type model. - - This function implements the following Hamiltonian: - -$$ -\hat{H} = \sum_{(j,k)\in E} (J_{x} \sigma_j^{x} \sigma_{k}^{x} + -J_{y} \sigma_j^{y} \sigma_{k}^{y} + J_{z} \sigma_j^{z} \sigma_{k}^{z}) + -\sum_{j\in V} (h_{x} \sigma_j^{x} + h_{y} \sigma_j^{y} + h_{z} \sigma_j^{z}) -$$ - - Where G(V,E) is the graph of the provided `coupling` map. - - - There is often a $-\frac{1}{2}$ factor included outside the summation of this equation. This factor is not applied internally, so it should be accounted for in the `coupling_constants` and `ext_magnetic_field` inputs. - - - ```python - >>> from qiskit.transpiler import CouplingMap - >>> from qiskit_addon_utils.problem_generators import generate_xyz_hamiltonian - - >>> coupling_map = CouplingMap.from_line(10) - >>> hamiltonian = generate_xyz_hamiltonian( - ... coupling_map, - ... coupling_constants=(0.4, 0.4, 0.0), - ... ext_magnetic_field=(0.0, 0.0, 0.6), - ... ) - >>> print(hamiltonian) - SparsePauliOp(['IIIIIIIXXI', 'IIIIIIIYYI', 'IIIIIXXIII', 'IIIIIYYIII', - 'IIIXXIIIII', 'IIIYYIIIII', 'IXXIIIIIII', 'IYYIIIIIII', - 'IIIIIIIIXX', 'IIIIIIIIYY', 'IIIIIIXXII', 'IIIIIIYYII', - 'IIIIXXIIII', 'IIIIYYIIII', 'IIXXIIIIII', 'IIYYIIIIII', - 'XXIIIIIIII', 'YYIIIIIIII', 'IIIIIIIIIZ', 'IIIIIIIIZI', - 'IIIIIIIZII', 'IIIIIIZIII', 'IIIIIZIIII', 'IIIIZIIIII', - 'IIIZIIIIII', 'IIZIIIIIII', 'IZIIIIIIII', 'ZIIIIIIIII'], - coeffs=[0.4+0.j, 0.4+0.j, 0.4+0.j, 0.4+0.j, 0.4+0.j, 0.4+0.j, 0.4+0.j, 0.4+0.j, - 0.4+0.j, 0.4+0.j, 0.4+0.j, 0.4+0.j, 0.4+0.j, 0.4+0.j, 0.4+0.j, 0.4+0.j, - 0.4+0.j, 0.4+0.j, 0.6+0.j, 0.6+0.j, 0.6+0.j, 0.6+0.j, 0.6+0.j, 0.6+0.j, - 0.6+0.j, 0.6+0.j, 0.6+0.j, 0.6+0.j]) - ``` - - **Parameters** - - * **coupling** ([*CouplingMap*](/api/qiskit/qiskit.transpiler.CouplingMap "(in Qiskit v1.2)") *|*[*PyGraph*](https://www.rustworkx.org/apiref/rustworkx.PyGraph.html#rustworkx.PyGraph "(in rustworkx v0.15)") *|*[*PyDiGraph*](https://www.rustworkx.org/apiref/rustworkx.PyDiGraph.html#rustworkx.PyDiGraph "(in rustworkx v0.15)")) – The qubit subgraph on which to map the Hamiltonian. Directionality of graph edges will be ignored, and parallel edges will be treated as a single edge during generation of the operator. - * **coupling\_constants** ([*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")*]*) – The real-valued coupling constants, $J_i$, in each Cartesian axis. - * **ext\_magnetic\_field** ([*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")*]*) – The coefficients, $h_i$, representing a magnetic field along each Cartesian axis. - * **pauli\_order\_strategy** ([*PauliOrderStrategy*](problem-generators-pauli-order-strategy "qiskit_addon_utils.problem_generators.generate_xyz_hamiltonian.PauliOrderStrategy")) – Indicates the iteration strategy in which the Pauli terms will be generated. See [`PauliOrderStrategy`](problem-generators-pauli-order-strategy "qiskit_addon_utils.problem_generators.PauliOrderStrategy") for more details. - * **coloring** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*],* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*] | None*) – An optional dictionary encoding the graph coloring that is used to sort the Hamiltonian terms. This dictionary maps edge labels (in the form of integer pairs) to color values (simple integers). Hamiltonian interaction terms will be added by increasing color value. Within each color, edges are sorted which does not change anything physically but results in easier to read results. - - **Returns** - - A qubit operator describing a quantum XYZ-type model. The `i`-th qubit in the operator corresponds to the node in index `i` on the coupling map. - - **Raises** - - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The coupling constants must be specified by a length-3 sequence of floating point values. - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The external magnetic field must be specified by a length-3 sequence of floating point values. - - **Return type** - - [*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)") - - diff --git a/docs/api/qiskit-addon-utils/problem-generators-pauli-order-strategy.mdx b/docs/api/qiskit-addon-utils/problem-generators-pauli-order-strategy.mdx deleted file mode 100644 index 39917c0ed85..00000000000 --- a/docs/api/qiskit-addon-utils/problem-generators-pauli-order-strategy.mdx +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: PauliOrderStrategy -description: API reference for qiskit_addon_utils.problem_generators.PauliOrderStrategy -in_page_toc_min_heading_level: 1 -python_api_type: class -python_api_name: qiskit_addon_utils.problem_generators.PauliOrderStrategy ---- - -# PauliOrderStrategy - - - Bases: [`Enum`](https://docs.python.org/3/library/enum.html#enum.Enum "(in Python v3.13)") - - Enumeration of different Pauli-orderings. - - When constructing a Hamiltonian on a colored set of edges, the generated Pauli terms can be ordered in different ways. This order of terms in the Hamiltonian is preserved during its time evolution and, thus, directly impacts the resulting quantum circuit. - - ## Attributes - - ### ColorThenInteraction - - - This strategy first iterates all edges (sorted by their color value) and then the interactions (sorted as `X`, `Y`, `Z`). - - - ### InteractionThenColor - - - This strategy is the inverse to `ColorThenInteraction`. It first iterates the interactions (sorted as `X`, `Y`, `Z`) and then all edges (sorted by their color value). - - - ### InteractionThenColorZigZag - - - This strategy is similar to the `InteractionThenColor` one. However, it alternates between iterating the edges by incrementing and decrementing color values as it jumps from one interaction to the next. For example, if only `X` and `Y` interactions are included and three color values are used (`{1, 2, 3}`), this will result in the following order: `["X on 1", "X on 2", "X on 3", "Y on 3", "Y on 2", "Y on 1"]`. - - - diff --git a/docs/api/qiskit-addon-utils/problem-generators.mdx b/docs/api/qiskit-addon-utils/problem-generators.mdx index 3e4a57cf1b7..1c9561c7884 100644 --- a/docs/api/qiskit-addon-utils/problem-generators.mdx +++ b/docs/api/qiskit-addon-utils/problem-generators.mdx @@ -1,15 +1,159 @@ - - -# problem\_generators +--- +title: problem_generators +description: API reference for qiskit_addon_utils.problem_generators +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_addon_utils.problem_generators +--- - + + +# problem\_generators + +`qiskit_addon_utils.problem_generators` Utility methods for problem generation. -| | | -| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -| [`generate_xyz_hamiltonian`](problem-generators-generate-xyz-hamiltonian "qiskit_addon_utils.problem_generators.generate_xyz_hamiltonian") | Generate a connectivity-aware qubit operator representing a quantum XYZ-type model. | -| [`PauliOrderStrategy`](problem-generators-pauli-order-strategy "qiskit_addon_utils.problem_generators.PauliOrderStrategy") | Enumeration of different Pauli-orderings. | -| [`generate_time_evolution_circuit`](problem-generators-generate-time-evolution-circuit "qiskit_addon_utils.problem_generators.generate_time_evolution_circuit") | Model the time evolution of an operator. | +### generate\_xyz\_hamiltonian + + + Generate a connectivity-aware qubit operator representing a quantum XYZ-type model. + + This function implements the following Hamiltonian: + +$$ +\hat{H} = \sum_{(j,k)\in E} (J_{x} \sigma_j^{x} \sigma_{k}^{x} + +J_{y} \sigma_j^{y} \sigma_{k}^{y} + J_{z} \sigma_j^{z} \sigma_{k}^{z}) + +\sum_{j\in V} (h_{x} \sigma_j^{x} + h_{y} \sigma_j^{y} + h_{z} \sigma_j^{z}) +$$ + + Where G(V,E) is the graph of the provided `coupling` map. + + + There is often a $-\frac{1}{2}$ factor included outside the summation of this equation. This factor is not applied internally, so it should be accounted for in the `coupling_constants` and `ext_magnetic_field` inputs. + + + ```python + >>> from qiskit.transpiler import CouplingMap + >>> from qiskit_addon_utils.problem_generators import generate_xyz_hamiltonian + + >>> coupling_map = CouplingMap.from_line(10) + >>> hamiltonian = generate_xyz_hamiltonian( + ... coupling_map, + ... coupling_constants=(0.4, 0.4, 0.0), + ... ext_magnetic_field=(0.0, 0.0, 0.6), + ... ) + >>> print(hamiltonian) + SparsePauliOp(['IIIIIIIXXI', 'IIIIIIIYYI', 'IIIIIXXIII', 'IIIIIYYIII', + 'IIIXXIIIII', 'IIIYYIIIII', 'IXXIIIIIII', 'IYYIIIIIII', + 'IIIIIIIIXX', 'IIIIIIIIYY', 'IIIIIIXXII', 'IIIIIIYYII', + 'IIIIXXIIII', 'IIIIYYIIII', 'IIXXIIIIII', 'IIYYIIIIII', + 'XXIIIIIIII', 'YYIIIIIIII', 'IIIIIIIIIZ', 'IIIIIIIIZI', + 'IIIIIIIZII', 'IIIIIIZIII', 'IIIIIZIIII', 'IIIIZIIIII', + 'IIIZIIIIII', 'IIZIIIIIII', 'IZIIIIIIII', 'ZIIIIIIIII'], + coeffs=[0.4+0.j, 0.4+0.j, 0.4+0.j, 0.4+0.j, 0.4+0.j, 0.4+0.j, 0.4+0.j, 0.4+0.j, + 0.4+0.j, 0.4+0.j, 0.4+0.j, 0.4+0.j, 0.4+0.j, 0.4+0.j, 0.4+0.j, 0.4+0.j, + 0.4+0.j, 0.4+0.j, 0.6+0.j, 0.6+0.j, 0.6+0.j, 0.6+0.j, 0.6+0.j, 0.6+0.j, + 0.6+0.j, 0.6+0.j, 0.6+0.j, 0.6+0.j]) + ``` + + **Parameters** + + * **coupling** ([*CouplingMap*](/api/qiskit/qiskit.transpiler.CouplingMap "(in Qiskit v1.2)") *|*[*PyGraph*](https://www.rustworkx.org/apiref/rustworkx.PyGraph.html#rustworkx.PyGraph "(in rustworkx v0.15)") *|*[*PyDiGraph*](https://www.rustworkx.org/apiref/rustworkx.PyDiGraph.html#rustworkx.PyDiGraph "(in rustworkx v0.15)")) – The qubit subgraph on which to map the Hamiltonian. Directionality of graph edges will be ignored, and parallel edges will be treated as a single edge during generation of the operator. + * **coupling\_constants** ([*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")*]*) – The real-valued coupling constants, $J_i$, in each Cartesian axis. + * **ext\_magnetic\_field** ([*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")*]*) – The coefficients, $h_i$, representing a magnetic field along each Cartesian axis. + * **pauli\_order\_strategy** ([*PauliOrderStrategy*](#qiskit_addon_utils.problem_generators.PauliOrderStrategy "qiskit_addon_utils.problem_generators.generate_xyz_hamiltonian.PauliOrderStrategy")) – Indicates the iteration strategy in which the Pauli terms will be generated. See [`PauliOrderStrategy`](#qiskit_addon_utils.problem_generators.PauliOrderStrategy "qiskit_addon_utils.problem_generators.PauliOrderStrategy") for more details. + * **coloring** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*],* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*] | None*) – An optional dictionary encoding the graph coloring that is used to sort the Hamiltonian terms. This dictionary maps edge labels (in the form of integer pairs) to color values (simple integers). Hamiltonian interaction terms will be added by increasing color value. Within each color, edges are sorted which does not change anything physically but results in easier to read results. + + **Returns** + + A qubit operator describing a quantum XYZ-type model. The `i`-th qubit in the operator corresponds to the node in index `i` on the coupling map. + + **Raises** + + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The coupling constants must be specified by a length-3 sequence of floating point values. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The external magnetic field must be specified by a length-3 sequence of floating point values. + + **Return type** + + [*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)") + + +### generate\_time\_evolution\_circuit + + + Model the time evolution of an operator. + + ```python + >>> from qiskit.quantum_info import SparsePauliOp + >>> from qiskit.synthesis import SuzukiTrotter + >>> from qiskit.transpiler import CouplingMap + >>> from qiskit_addon_utils.problem_generators import ( + ... PauliOrderStrategy, + ... generate_xyz_hamiltonian, + ... generate_time_evolution_circuit, + ... ) + ``` + + ```python + >>> coupling_map = CouplingMap.from_line(6) + >>> hamiltonian = generate_xyz_hamiltonian( + ... coupling_map, + ... coupling_constants=(0.4, 0.4, 0.0), + ... ext_magnetic_field=(0.0, 0.0, 0.6), + ... pauli_order_strategy=PauliOrderStrategy.InteractionThenColorZigZag, + ... ) + ``` + + ```python + >>> circ = generate_time_evolution_circuit( + ... hamiltonian, synthesis=SuzukiTrotter(order=2, reps=2), time=2.0 + ... ) + >>> _ = circ.draw("mpl", fold=-1) + ``` + + ![../\_images/qiskit\_addon\_utils-problem\_generators-1.png](/images/api/qiskit-addon-utils/qiskit_addon_utils-problem_generators-1.png) + + **Parameters** + + * **operator** ([*SparsePauliOp*](/api/qiskit/qiskit.quantum_info.SparsePauliOp "(in Qiskit v1.2)")) – The operator for which to model the time evolution. + * **synthesis** ([*EvolutionSynthesis*](/api/qiskit/qiskit.synthesis.EvolutionSynthesis "(in Qiskit v1.2)") *| None*) – A synthesis strategy. If `None`, the default synthesis is the Lie-Trotter product formula with a single repetition. + * **time** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – The evolution time. + + **Returns** + + A [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)") implementing a time-evolved operator. + + **Return type** + + [*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)") + + +### PauliOrderStrategy + + + Enumeration of different Pauli-orderings. + + When constructing a Hamiltonian on a colored set of edges, the generated Pauli terms can be ordered in different ways. This order of terms in the Hamiltonian is preserved during its time evolution and, thus, directly impacts the resulting quantum circuit. + + #### ColorThenInteraction + + + This strategy first iterates all edges (sorted by their color value) and then the interactions (sorted as `X`, `Y`, `Z`). + + + #### InteractionThenColor + + + This strategy is the inverse to `ColorThenInteraction`. It first iterates the interactions (sorted as `X`, `Y`, `Z`) and then all edges (sorted by their color value). + + + #### InteractionThenColorZigZag + + + This strategy is similar to the `InteractionThenColor` one. However, it alternates between iterating the edges by incrementing and decrementing color values as it jumps from one interaction to the next. For example, if only `X` and `Y` interactions are included and three color values are used (`{1, 2, 3}`), this will result in the following order: `["X on 1", "X on 2", "X on 3", "Y on 3", "Y on 2", "Y on 1"]`. + + + diff --git a/docs/api/qiskit-addon-utils/qiskit-addon-utils.mdx b/docs/api/qiskit-addon-utils/qiskit-addon-utils.mdx deleted file mode 100644 index 5900cf3e92f..00000000000 --- a/docs/api/qiskit-addon-utils/qiskit-addon-utils.mdx +++ /dev/null @@ -1,17 +0,0 @@ -# Qiskit addon utilities - - - - - -Utilities for Qiskit addons. - -This package contains functionality which is meant to supplement workflows involving one or more Qiskit addons. For example, this package contains functions for creating Hamiltonians, generating Trotter time evolution circuits, and slicing and combining quantum circuits in time-wise partitions. - -## Submodules - -| | | -| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -| [`coloring`](coloring#module-qiskit_addon_utils.coloring "qiskit_addon_utils.coloring") | Utility methods for coloring. | -| [`problem_generators`](problem-generators#module-qiskit_addon_utils.problem_generators "qiskit_addon_utils.problem_generators") | Utility methods for problem generation. | -| [`slicing`](slicing#module-qiskit_addon_utils.slicing "qiskit_addon_utils.slicing") | Utility methods for circuit slicing. | diff --git a/docs/api/qiskit-addon-utils/release-notes.mdx b/docs/api/qiskit-addon-utils/release-notes.mdx index a30ac515f17..5cb87419930 100644 --- a/docs/api/qiskit-addon-utils/release-notes.mdx +++ b/docs/api/qiskit-addon-utils/release-notes.mdx @@ -20,5 +20,5 @@ in_page_toc_max_heading_level: 2 ### Upgrade Notes -* The keyword argument `include_slice_barriers` of [`combine_slices()`](slicing-combine-slices "qiskit_addon_utils.slicing.combine_slices") has been renamed to `include_barriers`. +* The keyword argument `include_slice_barriers` of [`combine_slices()`](slicing#combine_slices "qiskit_addon_utils.slicing.combine_slices") has been renamed to `include_barriers`. diff --git a/docs/api/qiskit-addon-utils/slicing-combine-slices.mdx b/docs/api/qiskit-addon-utils/slicing-combine-slices.mdx deleted file mode 100644 index e72b6c9af46..00000000000 --- a/docs/api/qiskit-addon-utils/slicing-combine-slices.mdx +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: combine_slices -description: API reference for qiskit_addon_utils.slicing.combine_slices -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_utils.slicing.combine_slices ---- - - - -# combine\_slices - - - Combine N-qubit slices of a circuit into a single circuit. - - **Parameters** - - * **slices** ([*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")*\[*[*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")*]*) – The N-qubit circuit slices. - * **include\_barriers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – If `True`, place barriers between each slice. - - **Returns** - - A [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)") with the slices appended in sequential order. - - **Raises** - - [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Two input slices were defined on different numbers of qubits. - - **Return type** - - [*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)") | None - - diff --git a/docs/api/qiskit-addon-utils/slicing-slice-by-barriers.mdx b/docs/api/qiskit-addon-utils/slicing-slice-by-barriers.mdx deleted file mode 100644 index 69288f076bb..00000000000 --- a/docs/api/qiskit-addon-utils/slicing-slice-by-barriers.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: slice_by_barriers -description: API reference for qiskit_addon_utils.slicing.slice_by_barriers -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_utils.slicing.slice_by_barriers ---- - - - -# slice\_by\_barriers - - - Split a `QuantumCircuit` into slices around full-circuit barriers. - - Barriers which do not act on all circuit qubits will be treated as normal operations and included in the slices. Barriers which act on all qubits will be interpreted as slice locations and will not be included in the output slices. - - **Parameters** - - **circuit** ([*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")) – The circuit to be split. - - **Returns** - - A sequence of [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)") objects, one for each slice. - - **Return type** - - [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")\[[*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")] - - diff --git a/docs/api/qiskit-addon-utils/slicing-slice-by-coloring.mdx b/docs/api/qiskit-addon-utils/slicing-slice-by-coloring.mdx deleted file mode 100644 index bd739c82d43..00000000000 --- a/docs/api/qiskit-addon-utils/slicing-slice-by-coloring.mdx +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: slice_by_coloring -description: API reference for qiskit_addon_utils.slicing.slice_by_coloring -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_utils.slicing.slice_by_coloring ---- - - - -# slice\_by\_coloring - - - Split a `QuantumCircuit` into slices using the provided edge coloring. - - Two-qubit gates acting on identically colored qubit connections (edges) will be grouped greedily into slices using [`CollectOpColor`](slicing-transpiler-passes-collect-op-color "qiskit_addon_utils.slicing.transpiler.passes.CollectOpColor"). This will be done in order of increasing color value (the integer values which each edge is mapped to). - - - Note, that this does *not* mean that low valued color slices are guaranteed to be left-most in your circuit. Below is an example to emphasize this. - - - ```python - >>> from qiskit import QuantumCircuit - - >>> circuit = QuantumCircuit(5) - >>> _ = circuit.cx(0, 1) - >>> _ = circuit.cx(3, 4) - >>> _ = circuit.cx(2, 3) - - >>> circuit.draw() - q_0: ──■─────── - ┌─┴─┐ - q_1: ┤ X ├───── - └───┘ - q_2: ───────■── - ┌─┴─┐ - q_3: ──■──┤ X ├ - ┌─┴─┐└───┘ - q_4: ┤ X ├───── - └───┘ - - >>> coloring = {(0, 1): 0, (2, 3): 0, (3, 4): 1} - - >>> from qiskit_addon_utils.slicing import combine_slices, slice_by_coloring - - >>> slices = slice_by_coloring(circuit, coloring) - - # for illustration purposes, we are recombining the slices with barriers - >>> recombined = combine_slices(slices, include_barriers=True) - >>> recombined.draw() - ░ - q_0: ──────░───■── - ░ ┌─┴─┐ - q_1: ──────░─┤ X ├ - ░ └───┘ - q_2: ──────░───■── - ░ ┌─┴─┐ - q_3: ──■───░─┤ X ├ - ┌─┴─┐ ░ └───┘ - q_4: ┤ X ├─░────── - └───┘ ░ - ``` - - Single-qubit gates will be collected into a single slice using [`CollectOpSize`](slicing-transpiler-passes-collect-op-size "qiskit_addon_utils.slicing.transpiler.passes.CollectOpSize"). - - **Parameters** - - * **circuit** ([*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")) – The circuit to be split. - * **coloring** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*],* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – A dictionary mapping edges (pairs of integers) to color values. - - **Returns** - - A sequence of [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)") objects, one for each slice. - - **Raises** - - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The input edge coloring is invalid. - * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Could not assign a color to circuit instruction. - - **Return type** - - [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")\[[*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")] - - diff --git a/docs/api/qiskit-addon-utils/slicing-slice-by-depth.mdx b/docs/api/qiskit-addon-utils/slicing-slice-by-depth.mdx deleted file mode 100644 index 09cebc0d366..00000000000 --- a/docs/api/qiskit-addon-utils/slicing-slice-by-depth.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: slice_by_depth -description: API reference for qiskit_addon_utils.slicing.slice_by_depth -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_utils.slicing.slice_by_depth ---- - - - -# slice\_by\_depth - - - Split a `QuantumCircuit` into slices based on depth. - - This function transforms the input circuit into a [`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v1.2)") and batches the sequence of depth-1 layers output from [`layers()`](/api/qiskit/qiskit.dagcircuit.DAGCircuit#layers "(in Qiskit v1.2)") into slices of depth not exceeding `max_slice_depth`. This is achieved by composing layers into slices until the max slice depth is reached and then starting a new slice with the next layer. The final slice may be composed of fewer than `max_slice_depth` layers. - - **Parameters** - - * **circuit** ([*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")) – The circuit to be split. - * **max\_slice\_depth** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The maximum depth of a given slice. - - **Returns** - - A sequence of [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)") objects, one for each slice. - - **Return type** - - [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")\[[*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")] - - diff --git a/docs/api/qiskit-addon-utils/slicing-slice-by-gate-types.mdx b/docs/api/qiskit-addon-utils/slicing-slice-by-gate-types.mdx deleted file mode 100644 index 04e33d9bcff..00000000000 --- a/docs/api/qiskit-addon-utils/slicing-slice-by-gate-types.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: slice_by_gate_types -description: API reference for qiskit_addon_utils.slicing.slice_by_gate_types -in_page_toc_min_heading_level: 1 -python_api_type: function -python_api_name: qiskit_addon_utils.slicing.slice_by_gate_types ---- - - - -# slice\_by\_gate\_types - - - Split a `QuantumCircuit` into depth-1 slices of operations of the same type. - - - Note: Adjacent slices sharing no qubits in common may be ordered arbitrarily. - - - **Parameters** - - **circuit** ([*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")) – The circuit to be split. - - **Returns** - - A sequence of [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)") objects, one for each slice. - - **Return type** - - [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")\[[*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")] - - diff --git a/docs/api/qiskit-addon-utils/slicing-transpiler-passes.mdx b/docs/api/qiskit-addon-utils/slicing-transpiler-passes.mdx index e071db7010a..f064bfd6ec4 100644 --- a/docs/api/qiskit-addon-utils/slicing-transpiler-passes.mdx +++ b/docs/api/qiskit-addon-utils/slicing-transpiler-passes.mdx @@ -1,8 +1,18 @@ -# passes +--- +title: passes +description: API reference for qiskit_addon_utils.slicing.transpiler.passes +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_addon_utils.slicing.transpiler.passes +--- - + + +# passes + +`qiskit_addon_utils.slicing.transpiler.passes` A submodule with transpilation passes for slicing. @@ -11,3 +21,4 @@ A submodule with transpilation passes for slicing. | [`CollectOpColor`](slicing-transpiler-passes-collect-op-color "qiskit_addon_utils.slicing.transpiler.passes.CollectOpColor") | Collects blocks of operations which act on the provided edges. | | [`CollectOpSize`](slicing-transpiler-passes-collect-op-size "qiskit_addon_utils.slicing.transpiler.passes.CollectOpSize") | Collects blocks of the specified size and replaces them by a single block instruction. | | [`CollectOpType`](slicing-transpiler-passes-collect-op-type "qiskit_addon_utils.slicing.transpiler.passes.CollectOpType") | Collects blocks of the specified operation and replaces them by a single block instruction. | + diff --git a/docs/api/qiskit-addon-utils/slicing-transpiler.mdx b/docs/api/qiskit-addon-utils/slicing-transpiler.mdx deleted file mode 100644 index 42a5e5544ef..00000000000 --- a/docs/api/qiskit-addon-utils/slicing-transpiler.mdx +++ /dev/null @@ -1,13 +0,0 @@ -# transpiler - - - - - -A submodule with transpiler utilities for slicing. - -## Submodules - -| | | -| ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | -| [`passes`](slicing-transpiler-passes#module-qiskit_addon_utils.slicing.transpiler.passes "qiskit_addon_utils.slicing.transpiler.passes") | A submodule with transpilation passes for slicing. | diff --git a/docs/api/qiskit-addon-utils/slicing.mdx b/docs/api/qiskit-addon-utils/slicing.mdx index bc6d7257df9..736fd167601 100644 --- a/docs/api/qiskit-addon-utils/slicing.mdx +++ b/docs/api/qiskit-addon-utils/slicing.mdx @@ -1,23 +1,180 @@ -# slicing +--- +title: slicing +description: API reference for qiskit_addon_utils.slicing +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_addon_utils.slicing +--- - + + +# slicing + +`qiskit_addon_utils.slicing` Utility methods for circuit slicing. For more information, check out the [how-to guide](https://qiskit.github.io/qiskit-addon-utils/how_tos/create_circuit_slices.html) which discusses this submodule. -| | | -| ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -| [`combine_slices`](slicing-combine-slices "qiskit_addon_utils.slicing.combine_slices") | Combine N-qubit slices of a circuit into a single circuit. | -| [`slice_by_barriers`](slicing-slice-by-barriers "qiskit_addon_utils.slicing.slice_by_barriers") | Split a `QuantumCircuit` into slices around full-circuit barriers. | -| [`slice_by_coloring`](slicing-slice-by-coloring "qiskit_addon_utils.slicing.slice_by_coloring") | Split a `QuantumCircuit` into slices using the provided edge coloring. | -| [`slice_by_depth`](slicing-slice-by-depth "qiskit_addon_utils.slicing.slice_by_depth") | Split a `QuantumCircuit` into slices based on depth. | -| [`slice_by_gate_types`](slicing-slice-by-gate-types "qiskit_addon_utils.slicing.slice_by_gate_types") | Split a `QuantumCircuit` into depth-1 slices of operations of the same type. | +### combine\_slices + + + Combine N-qubit slices of a circuit into a single circuit. + + **Parameters** + + * **slices** ([*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")*\[*[*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")*]*) – The N-qubit circuit slices. + * **include\_barriers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – If `True`, place barriers between each slice. + + **Returns** + + A [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)") with the slices appended in sequential order. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Two input slices were defined on different numbers of qubits. + + **Return type** + + [*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)") | None + + +### slice\_by\_barriers + + + Split a `QuantumCircuit` into slices around full-circuit barriers. + + Barriers which do not act on all circuit qubits will be treated as normal operations and included in the slices. Barriers which act on all qubits will be interpreted as slice locations and will not be included in the output slices. + + **Parameters** + + **circuit** ([*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")) – The circuit to be split. + + **Returns** + + A sequence of [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)") objects, one for each slice. + + **Return type** + + [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")\[[*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")] + + +### slice\_by\_coloring + + + Split a `QuantumCircuit` into slices using the provided edge coloring. + + Two-qubit gates acting on identically colored qubit connections (edges) will be grouped greedily into slices using [`CollectOpColor`](slicing-transpiler-passes-collect-op-color "qiskit_addon_utils.slicing.transpiler.passes.CollectOpColor"). This will be done in order of increasing color value (the integer values which each edge is mapped to). + + + Note, that this does *not* mean that low valued color slices are guaranteed to be left-most in your circuit. Below is an example to emphasize this. + + + ```python + >>> from qiskit import QuantumCircuit + + >>> circuit = QuantumCircuit(5) + >>> _ = circuit.cx(0, 1) + >>> _ = circuit.cx(3, 4) + >>> _ = circuit.cx(2, 3) + + >>> circuit.draw() + q_0: ──■─────── + ┌─┴─┐ + q_1: ┤ X ├───── + └───┘ + q_2: ───────■── + ┌─┴─┐ + q_3: ──■──┤ X ├ + ┌─┴─┐└───┘ + q_4: ┤ X ├───── + └───┘ + + >>> coloring = {(0, 1): 0, (2, 3): 0, (3, 4): 1} + + >>> from qiskit_addon_utils.slicing import combine_slices, slice_by_coloring + + >>> slices = slice_by_coloring(circuit, coloring) + + # for illustration purposes, we are recombining the slices with barriers + >>> recombined = combine_slices(slices, include_barriers=True) + >>> recombined.draw() + ░ + q_0: ──────░───■── + ░ ┌─┴─┐ + q_1: ──────░─┤ X ├ + ░ └───┘ + q_2: ──────░───■── + ░ ┌─┴─┐ + q_3: ──■───░─┤ X ├ + ┌─┴─┐ ░ └───┘ + q_4: ┤ X ├─░────── + └───┘ ░ + ``` + + Single-qubit gates will be collected into a single slice using [`CollectOpSize`](slicing-transpiler-passes-collect-op-size "qiskit_addon_utils.slicing.transpiler.passes.CollectOpSize"). + + **Parameters** + + * **circuit** ([*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")) – The circuit to be split. + * **coloring** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*],* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – A dictionary mapping edges (pairs of integers) to color values. + + **Returns** + + A sequence of [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)") objects, one for each slice. + + **Raises** + + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – The input edge coloring is invalid. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Could not assign a color to circuit instruction. + + **Return type** + + [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")\[[*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")] + + +### slice\_by\_depth + + + Split a `QuantumCircuit` into slices based on depth. + + This function transforms the input circuit into a [`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v1.2)") and batches the sequence of depth-1 layers output from [`layers()`](/api/qiskit/qiskit.dagcircuit.DAGCircuit#layers "(in Qiskit v1.2)") into slices of depth not exceeding `max_slice_depth`. This is achieved by composing layers into slices until the max slice depth is reached and then starting a new slice with the next layer. The final slice may be composed of fewer than `max_slice_depth` layers. + + **Parameters** + + * **circuit** ([*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")) – The circuit to be split. + * **max\_slice\_depth** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The maximum depth of a given slice. + + **Returns** + + A sequence of [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)") objects, one for each slice. + + **Return type** + + [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")\[[*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")] + + +### slice\_by\_gate\_types + + + Split a `QuantumCircuit` into depth-1 slices of operations of the same type. + + + Note: Adjacent slices sharing no qubits in common may be ordered arbitrarily. + + + **Parameters** + + **circuit** ([*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")) – The circuit to be split. + + **Returns** + + A sequence of [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)") objects, one for each slice. + + **Return type** -## Submodules + [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")\[[*QuantumCircuit*](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)")] + -| | | -| ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | -| [`transpiler`](slicing-transpiler#module-qiskit_addon_utils.slicing.transpiler "qiskit_addon_utils.slicing.transpiler") | A submodule with transpiler utilities for slicing. | diff --git a/public/api/qiskit-addon-cutting/objects.inv b/public/api/qiskit-addon-cutting/objects.inv index 7a6b13a06ba6e7a8c43cea3c888f9b84ed932c98..6b5e6e78728a428652a063e5dc74f81a8ff3b08b 100644 GIT binary patch delta 2863 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 Njnwfj^e;OTAs59$o~{4@ delta 3783 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 qFCVrdBWS|P)h{pujJ1J6%32h&;r delta 1576 zcmV+@2G{wb46O~2n18ie%W~T`6y4`5FvBj|1?(nE?>vs3X2zMSRkGGVBxoT92^bGs z>eqJ&fD|YKAZRHoo4Dtmd+>f-y%70K)CN@*Yc~zA0YBU{tkM*NKf#MJLSuvtuM2B| zzXAB+<;3wyDx^p`^0!49URRIn`_8kZNJ{Y0IYKIN+UM%F^M68039{7+k35Up8Q*Qf zcRS--GTkauSFCod8arEKnt-$w-p2^6F-;&DeZ?^XYfKaD6V*=zrxK653ugA0#7grG z;#{yjX^_I3hELkpgx$9q(&d13?0r0i;ypt6;|Mx0cvl-Cn3 zAr+9Sx}j*>1%LZEnN{E)QvgiC4QMn~1aiSDT`EvB(P)Y!`2E}J;g58fV$AIGz@Enh zOv=e-xtMIJw|0q;Gs-;RdiXa%?z(Z(18%8W+dtn{4|yboKOEf{Xm|}vhU=P?1h-0t z0%iH#9x=VXZ>tC3WAa4Wp}j<2+T*^no+pWt79#=WL4PXTKvqNiqER=OB-Dyfq6iKv z%W`})AYeg&)nEXD0hFin*aTrYzI`-!@SaoD+Mw5F^_~v8DF)noMKO}XFP>u@gA?=( zuQyVmZPz@9E5Z-$Ho@JEi2)6Mv=tUop|&FJ6Hq%dUY(8Ap%w{5D^QE*;Xl$oLAAqB zV5zB+xqliW-nV_JQRPZAv`DN}$JOmPP?CmIx7~E>*_PraTh~0(+9H7F00D~tZo9IG z9KEDlTuq=?BnZm|=M#~r+6t$iUhr-cdY*na1I_#_qP0+;3>4>_ZxJcOtMsL#hDurfs>T2|@?x60Z> zj3dBj|I6ngtyGB8D9yahA6jQMHIA(<8>PDTxTxVWEA;;xN#9GMFYQ$yZHo1j(#!|~vk zN^j#2YF(Zn^73jfN#{C4|_-T}+6z&SnKKAtc@!>6Vyng-8}Kx>Upx zff1fF!WT;umrLX>Tl|t%_j0o{-R-AmC%*3rR^+FR^JHc7y-#kS9dcw9 z7i+)N_I*rz57qM@o-d2YskCU5D738b|HNk`9N zE+rXH=|owUrwUUq<9?V+WnRWl*nt3{x9ypWe~9MYPtOx!i|_CKb!)^icLQU5_;pL- z%9Fg{IEqi{`^(H-B{-3Cf33pnz|VQ0H&sqk`ls$a7Jf)CAl)yZCLvRAxYxXE^A7MW a-G&$LG|`CZ{UdW}jk1px(EkBeK`y`%whO)h diff --git a/public/api/qiskit-addon-obp/objects.inv b/public/api/qiskit-addon-obp/objects.inv index 78d5dbd4de56cad9d0f4cdae959fc1f5ac9ffb14..68def90a132d7d5e3c45dcc2bfcf5c999dd5f53a 100644 GIT binary patch delta 2595 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 N{4pr}{|{l_GRalJbb$Z> delta 3539 zcmV;^4J`7w7uOt+rhnC4OOvEF62ALaD54y(y9bTeWBby#bx+vi2ye`cd%Rad1*$IX z0HP()HRWHwp$8y90tu+cUb?zK`Q?|XMCh6ILiiUV5|m}MO!!L%s`EoZvpUD%pWsE^ zgz6^bFWFAtf!_l7&C5XWO-joHd9E1}gq8`zDSgH4+{5b?fqzYr1*mT-%0C2S%E1@xM0H?G!n3tfLcOUW=f!vh*ZQW6F8HF8Ri_vXw;&x6P-|v%N((1 zoa~WEkI8}2A`uLgoVcE%MyU~kN(f3JXbVlKJLIHFD1X}%f%1f=Xdk9jypnEnYv@o*1a=~dawjsQDg@gG`wmqk zqbdI`_|?q?;39j-(H`dj`d-uE(Y_4+FqaqU+kbgf1kl)R$48JRU{2L;?)8)qyyD*@!{y~o%JgMM^ zd&F@DKGmocbphTH^h`_HM^P~`t-w6_d|FXk>ficv29sN~;ESdOvp%gEg+UN2&9_^d zk$^_#DKpZhprRbsGV)2#ScYT_cT1itJu_6cQVK{Eu z!sf-wSNm#@%k)?v_CC?PbtbVc>44Xq(@v3F4!5IDEo5A>4}3A5l8Tj zq!{SpLF#v0V#@9iY%yVr2_5gQ(Z(sCa(Xj3 z@4qQHlt|DZwPDJ^M_qjI(%?WA2k&+9_8H>q2=CG(PQO5LL;~)qI6@+OrGIjw!t^xG z1n1_FMunU=q-LgV3sYBUf0U9yN&+bf29iKY>edDo7<7^={dFLW3s_)rq}c;3Y55ms zbTr2!Cksd^qmaMZ#8JP*t5qVvhyWu3jQbi9fXWOsA}d{UB+p08V2)pLKB&n}d@zOo z-nuu4g_TxCKD=8Pde7}e_kT9U2U3#FD%XYk)bUpeTNlJnlOZBfsR-~b;E((k0~_i9pFa>42}hVM@I zG3lY#dwPg7!w2%S>WtDukLE)#wVn^+2=zoC^_M64C0IGhzK_%?C4ZhOoRY&C?9bpR zYYPFn(j~j*>?|EoV8m;t+6X{vk zpXfsbhaaOk{0Khm1%DzX$Z$#ulmmtd~cMO*OG+J}%T2SDQh*mpqt$ZH4awTi|8-9jga(gAYIfGpfOV6qSH zHR>9S?y1_X7el0@I>8U}-?#>l>!wU^^e8ikVAqsMFI!C+Y=4@vNP>%0T(pU8*Tx`% zy2&vs=JWu$8n>Tl?8`9>bKAyFG>yKBZ)?+qTv9$sRS4Zw3MP5s-G}C zkvxY@BPShP&>W|7&p_k^f3K|fs_J9N>x@P)z)Pvwa6ds)-nXM zx+u#@RZi_~4Mh1=R#r!iZRkc>wk%7GO59fZ-;V zzdwC?_YVtpr`Ft>-EI9C$tgg6r3tnNB>If^~1Yd~IWR9qxHoG$>gXtZT4y8Bt5&J9Dk+Wb(g?Lb*TqS)7mq^ZV-C~-r3)5 zoY4%MmX??Qzz585sb-BW0XcrobFbds{okxFHb_oVTypG^Z*KjrKW(Z0R;z$*R%)l2 zL&q|pEuIj5<^mUL#HsuL{k;YZztn`8#Tf_j81W}nRt;PAfS|ue!7ghvbg$n-xdj3X zwST_Ea4K?V6bH+GcJ2cJa?=DBperbesR(klTIxnG#MBovuHik|URXk66?39a6c5y= zM`G}MXfB$K-{*?B6;71@Q0e`{4~=dh?}3l!kH0x}zU^ahTC)^SYIRE(y>AD4pVZyH z=89oB)i7vnqf#FkhW#dji+UfvFM0AbRe$I%>6rsnn{e6Ou-$OmDO_aSYWHl!Ka z$cV+}uhe^2&Rd#?=3ZlGI+Kk*?0;vH*(}tz0bPHv%}`!o=3-qpcTapyqkD=1Up^#% zxO!6}MeA5a&L1#df>Guyz`uzDVsc#Fx;{slvHVdsPL36hx{Qav!pB^~D90dP$-1C) zW!JBeVRkcrT#OQ&1!FEE;jh9Gks!JecvmqjB-7lr>!FvI&L0W=)O2BJ@qfDg71q~3 zPcanf!j{Y?0=&Gl=kot~vTjYK0F2hLirly=X9-4`vjG1l4v5L=c-#7%$^_{Px5;FX z3-qj{=nINTnvrHL(s46a#O3?EeGOZALVYo3rwW}%iPPt+TwCWfr4WP*v7Su2dU;3s za~(&wJ{tQ5~7DT8fUUsB+Od39~*Yv%%|9^%}=F}uwSmGc$nPdq<*>y3Y=0#3Zj=6=N?@YsS| ztM}IyJlp78D3iaC;D4K?b^-Z++`u^~bU_4V$e-$)0r(AT&)2%nQhsZnzuoX)(|ot( zDuQ4o?QmMSg~r8j!>ur}do)~hR!nWVh};w4(!XMjKW1^- zrFzkN^TGwq(U5)Hg~`P$U1MIGuUCaG#Ehv#uCFYdz<250a3X%iOs;3HX6xD5m}x{G NrP!Il{{bcuB_laZ-J1Xa diff --git a/public/api/qiskit-addon-utils/objects.inv b/public/api/qiskit-addon-utils/objects.inv index d32801947935418e41852dc175c233b52b70c7d6..f2490ecc0967996ef90e6e00bb11cbdc25b83262 100644 GIT binary patch delta 1877 zcmV-b2denL62=dZhJQhC<0urq&#$nQJ+uch+d1~Onvr%Ztu$S=dzp(xY?`2T3GDh@OuY3YY%2Vnm54nF1_jz4q=}+}oM(473sfo) zsla=Ma9iuI(*Nfjsvl~B7;K|O5BE?AhBu8sb`riw5zGcK5>>&6F|#5iX7&Sbf52@z zejT1K%kC%21%KY79KDgMk#Ko|S{3N|m=gyOepWIELk|q7#+3 z%6L%TD%&x6t4v4cts)VXw;fncX!{8=IgJMAoPS3TSjeGhY8C*_I1Lz3kWrl)(7>`0 z?K7mfBnAJB>k|E1GcGbN%KHj#P$jX{>8vFR6j7jvW`8_BWDLC^hUx-YU{XQrjz1CC0;A#O@#FURusg~R&BMrdo$rM3 za({d$cgxzA@dTQSR+(k7`o;_WHh_)efwSbIbS1Gfl>Sx%-D}T5z{`7xurj>7fEjZqUM{^bqK58jh`WLjU zY)3NQXes!abuTMLQ)~%lQlj=b>2$$u31(8FZF$bkvX${hOUiFh=yQ`C2rk3*qHBJt zPYo^R7kSqGxmkjL8%}F}V6l`%{agux4s?GOiRjK|rSt+DH3ejxu@a^tmla#!%T5C=)xBwNm6Idu?DXntj$y z&UpaKRl{2zpf@J@w8ntgb(8>k0i7|>8w>U?!eolbFeG!WyU@KAoOetq^c+C-{cwa(`YuEe4P9a$<2$yPW++eu8I`{n_9Waf|M1M}EqO zW2*!lNF%`!u5+RBALUG@oXMm!SYSexYT5E>XBSS!c4u835HVfx9T~&k7wm{@R`!dTydT}Wco0Wbll-wBRJX|C6 zgQFhN5p)G^A4~h8_qEqg(Ajql;V_y5LgQiprR+Mql1SMa6(ZtggG=8Lc@42sT@|5` zQp&MCnAZ>m+20Ww1gRU@2zm`6(7Q`QgQ24&Yf+60kZLsvo6e{X6MwBsB@LC8b|#S6 z2;>|z!_`BB9o`&yahD@zFj`k}d|UJ7Ly=(iVsC9u*l>LnQA#s&aWz^eZw0@6+yZAU zr~dEA*7M6pAZ*5RY(kIge!sl?v9lFRBYdi^{J7w#p470pifTpG+F8?3S!rhiiH$(c zK{H%EG}z${;TLx~Vt=lp?WBm`%5nKnB$%t%w{s-iWO5ZzN;6k+Z7xZ^{pIp;3!JN* z_Pj)Hx4C=-!saT+jW=;SelG8R>|DjN`6ty*q)*y@6UD70#exkh9$O8Ds7p6pENavo z8cMqlV7^UgXnRp>VMqs(#aObIs0Gb7LmD5`3gqlIvC>J@=T4$`cvuYCT0bUoYN9~j zm*F+}xyn4D{eSOpmBO8c?+)UNyRJP`!wwi?NBa+b9_iUSa}15Ae$8?T3(LA|42S3b PTVx3b^Ly%lpc#_vM*N<6 delta 2257 zcmV;?2rl==55E$ShJQ_uqc{}2&#yr8UY*&QV_#>b-H}$BUUlzfE{K3Tv6f&Oo1RJk z`jyQ`02^aJJCmHc1AbNI2X-9uidV}2qaw|Uf>miNXvvfM{BUALTax7WNHlT zQFjjimf#PsTJSDsC2MGPn4t^@9bqR9j~oFzqGW}GLV3=FuI0hq}M%!d#-+wP0Z!1Iw*Un@bHtjkw@e#nGq=)M)i zT?R5@1!$YVNPkoX57lPGimdHBJ$%m&F%|ZRt~&dFNh;`xq~wj2t%OT++T<-2i!osk zHUMA=fJXp40C)@ed45li*@>2dRWz$S6#P8D<7s3lwRNcBz_G?lnlGov{@BKx(6`#< z?6jv9N#$p4YU~@~z7g&lSpij>bbn6wS<_I`tYNBlcz=J!V>>t4m5Ek^wNJ4cY(Z*q z+`{Y{xd9&3csSQ&GXV#6+IoD#{ql>h6Muaqh@ZlFQjqc9e)CE4;|j5FRFi@-(Zm^2{kuWsBv+ z?IB2m3V&9n+Ptvll&Kj!T%QRrOl6gwz*kVkhS4`|1!b3^VdQOH$a#f}Otc&-V-5lp z^hDo@_aNpnD1;F{ge7(G2v!oJ3}7WE+V~xG#TveYx|pL^X@m`4B`0X?Dss@!Roo#X zS5XHJTqPpTxP3m?{^M3IPl6cX<5p4!k6R@n%73_3a-xmfL07DCJE)5}Zk0yZxK(n3 z#;qa;ja$VXGHw-h;J8&Hg2rtRma@A0>9e|w#@Ad&PgKaMXl)gMuec1DNRU}wo6xY| zjP^0BX~A;-(YDpsaFK9PJe1j%Jy}%u<&((fTGz-UFc=xOb z3x@mfewXlHP7-hJFFG|FYw z)q!{}w0g~^J4T(D^+SDVTJ?-(9y{whrjuqyR7-P5K31#HPq;sbUmAA8^|_{ILQDH^ zb@$BaVc<^Wx#aQu_|?eyd5*zZ+vLQ`YL4i6KQDNn)Y&<6-4JZM`#LtQ)qi6{@ccgH zqTSnneJ$%i)_>ONr69{#C?C?0-2|ZPDe@|vaZHyFri*ZMt&QaZu9VxDal#a!6)qoP z=vV3m6g7Dz*&pB1A^&O`h=n8Grafh4K0&KoydyIuRj+jaqel+e}RoB=glhoC9UbSZN%!&iMW^^-d4( z*&$xO`nu;URA*aqXD-EE-@{*2jI}btrN+*LM!q>&LZVC?WDHZ+BGZg9#RHNQ#p>6givSBd_gi z*F8a+hk?L!5wsaEFXqm*C9TFd*~k0 zp%oxQ^P&O8bT-{drcA}q0r@h)#dlrZL+(`NHZ)TzIMnBL4_S~k z!46Hv93`3!E-XQ+oE^5DQB~}-O87WZ(Ci3M*aGAlGU4ISWPigASU2x-zzSyOTnx8P z-aZu(Rxf7zWJFWvU1TZF%Ee~pjBYo*ecphpmW#(U(B69c48T?_qtP|YVSD@Thptu( zX4_cK->~E;-y3YLqU>%n%Um2OXm$iBYyol&necFEvf-xFn|C>2tuk|Khug((pNa@; z6|-eLqLKYBvVRn3tzt8ud zw;g;~cW5f11=$^I2wpd-bbym)tor^&}Qwotbb{&9$q78^MYBOUp>TUyRmD- z#I-Ufc)cjW{4SIY2aN&7{;o&7GBw!VQ(@pROd&=#>njlqxI=pz81`_!uTxA>9NDnn zI}4n+2Tc6I->_!-dT=o7LG4mTIzOwHPsOa^O|jPRFy})3h~AwIMWHsM81@cViO!}I z&stW~w@R + + + + + + + 2024-10-29T21:01:13.960938 + image/svg+xml + + + Matplotlib v3.9.2, https://matplotlib.org/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-10_00.png b/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-10_00.png new file mode 100644 index 0000000000000000000000000000000000000000..b0dc2d9ec56469ff3926698a704506acaf848283 GIT binary patch literal 22833 zcmeFZby!tj*DkyP0YyS2B^8tqB$Y-`=@w8>K)R&6Ly;B`L6HV25$SFakPbn*J2u_T z8Qb6UKHnSXT-Q1Oe}8Z(o3+=PYpyxRxW|3pV+ATHNaEp8;2;nPJZUL0Wds5p{)^^) z84Layy*W|~|M1(3tJ|ws8QDAO+8QF{b?vRqt?bQB^=>*E+S-{~S#q=SvvINBG_kk0 zwi94yxA^w~Y*x0$?6(v!hT$YvtfgMqArQCfJ%4w{iD^li`Nta&-$*#-ZaqaJD`!mLYd@hpBlzXpa$mpeMT6%f#L-ff7$zAO$3JP;<%YHE-o-z;a~6Z!z;TU`kg#$_ z2Z^Agqfx^6&IOKWR)x5xpP zkgyytPQW4P#}8JGW+q}sZG^L{tLnTY@6pGY*&uF=ve8W`NJudlyv+WSt}ZC^8g{QV8?%Q!f6H*b0; zKk@$<5rHA9r$=WoQk1OM6!gy5cYM8as+$Z9es3_aUkxm5 zPB&B?&IJF^s{H)!-6e$tq1GbPK7_TC)8gKsw(RT4yTBopRK1ia?Y9!tv$` z5revRY`>bQSn6h3g5L^deZ4vI_R(q?v4Xl^wn`*xlQQD)@X-47(5AzPTR}mA-0u-w zxu&M(XyoYl*miU35fa(h*w{XzDg9`GlHc|=y<})n&Hnzr--|+=!$2{yIWA-TpS$=U zkXRu!XxPnF7jhS;wGH>G6HWbymieg!6Ptb)QH3USFSL}ihNc>ZhhvoU>D0f`q_VcR zp9yW7H|eMQkQXX%dB*+u>o6iX4e{-HHpTSxbVn?27(A2$=PkXe>gpY>bN{Luw0jyQ zbDz{+CA;pe$VGGc)_9z}aysFyOb7@d{wSNtQA=Qu;DcT3J=IlORIV9ZpKlk%=e&aM zub?&8vwU%O@kd-CuKN1Xy&&LSp92_T~3ADo)#+KprVp1jZ7=L zTcUwb$xtwys(bUEk{92}$;qfI?n>QqUrgaLK+udka-az*Hp`(-~F`dC`ZD;Y|a z4?8P-G(xwoR8e$H$bkIE-VqRjqUE8eXcJb=o{`37MDX+04r3d-RSJVcz>`J(^*{A;PIjyUg1U`OMo(W@c z$$b1RLH;kB*~*`JiiNYIkY~a>U8`B2?edR?tEyE{Q4`b2fW@5%Z$7KxiMDO4>gVP~ zOZ~kK=Az8C)-P_zr&+IG#8E$(my=FIT?2<Yvpv zS!&<#PfO8IQQ3But54?~!+Pt!5JwcfA+pD-4GTZMqD9{V-8sk3LTjW}{u_jnaLNcX zKi{yQnI1h`&pdP8c`+Uii^{l?vO8rpr`%gFa(K*)_uDHRo@4lX zklBd`{||CJn&PA03%pnAdBJz*HKX@Th#tRwUgRK9E{%$Mb1R`u^)vP4hFM%G1EW z=>878{Kr+7u#+@eW7pz~&HaR+BAo512v5Su!A8Nfx1K?CbRQG%kdYF+Ard_LdP-jv zu9~>6>$GXP;aA3I>Ydp87?s=R4rYU`r`(q^hzQ zDpg*N8w);aKiAAF;~WdnJ@qar%GBx{$V|PAy2X5_WyW&8EXFSWXrbA|>sG=e5q=Lp zna9fneL-afK_dh0xw#^*X@_M#tFrUh3tY;!c$#^0YT2MSfB*g|HnzPcjF#cH2Z45( za9vMxvr_ik*lc}i&fggEkhz(-8Ka&>&@#@AQSek0FHB@GEKgY(qlPsUy%Wvf5qC-v zuR>-$l+8A+crWSk4ZJloEBmXWVvV73LW!+zDj7S!dOsFJ|+XQiUiyxfl* z7Wh1bN_OGOmYwIs2{EOC(fAum?UCpQ3h(OnQQu96@1_!KRIOd^zBf^SJBnE>k2XdG zEd(3B8i_zH9GP1U9AA!+wpx~LYgtB^@7npm0)*L zfJ~M146|JHV$ufsx8HRGTd9{&h{-lqR>&j#Jkf$-*&HinWW1HAIibOxfu^Dgv$%3d zAR$r-bvaA@Sb{{u#>G)SH_lia;m6KPbAlhrNMmq)EB!{{Af3MlJ@M1!&>z>GI6ZgL zq@q4d)xHEzPjpr2^6CeteJieEf%JbJ$W2zz(a1W|TA02C zHlnA#c}>iZ>{3D$p$rs>?%H%2g``2J^`y!sHe9Ha7<!PqK@TjbpILJMeJbBVu)8-mFh}`4ZpGH$J9VyiB2XyAesawD zjRsw760MfBB$T<785J1ryw@d{JK4Lo@na|~HUh(Lomm$7&RAy@i%I3ix(C5e?C%-1 zW7p62VZ1k&qxpp@tr&*vbD9%sqE0p=dhiVTItV{^ufY287;YY<;s<&?Q#hI4W%}c%Ui!) ztCUOgn`WOKr@MQ%mb320poOsw)@$Qv<&z*F_2N?UyvM-CzeYsVQ1=Fd-OTQAQ}>no zmiR!9mh9ul=!}X91|vnLgIXo_%gO_}+TEelf zeW8=xbH*cs;KkJG-Dm7~9%nt>Y$UzBmVL`3O^R3+?Zd~9KL@fkmIrfb5!J4Hbo~5B z1%4o&Fjc-Ndq z?$AUZU!CXis_QmPNG{B$d0Y8&Ha6)@cIxHC0AU(2%jbuP*4EZP-=1PHW>k$w%Q3in zcu330&~b3|jIc2?2fi$R{X+ZX=qNlg(tg}hq z7n@5r4-jekiJ7<^>cUVQr^0a;`|)7u&2K5$DS`1!0CL1lkptPQ6V#cFd(iigZFshs`Lx zXRK-ncXxL_&r?35!W)c?jJORqnVGL>Yfrkb!N~cYH2dv1Mrr@pp{Vt~?+U;X3R;`LiB1Q!rax9f}xn!%!nnA6Fjg4+t zTdiGPSW}f7HT1V{r}90F3251S!Af=Fg0*l!`I~=@CA1Rr!|(<6T_L_F*k1Y3dX(5Y zD}OR^srWwF%>J5QU+?OO=0+puGPn%jUQAqk8csTtuW$OB&dQ{n$719fH8q}fr(u}L zIp4|tT8eIiAD^J$?EHLFB(q8oG9@rTbNshOoYwArr_}Yi_tRa+$LvJIC(LsAp(P3o zj$H=ie!9qOC39Fb+W6MfHpe4QY}n;?$mcgS?mfKkzq>Xn{u48E<`41J?_ch^{Q)_d zfcZd@+jIFvmtpFb*r@1vu0BU7e#IPnDJ?2ws_Bt$jxy%07~(eQc+^QH2#mewc2iW& ze#_E#!khl2dZk2x*|raL?bAMAmCd!w0TZ@kAAv(@W)yl}9hmMT8_qMp8IPDut6IJu+&-o_@1|`e;bDchK%bU?I*lNNL*O69Ue|zQ9#{)})k2|+dsTHkr7RFUw zt+76}xs3=UNadq)d)mZ)swzXSf==fKBl+ARMub*vOJ(Wgmi*oE2UJvl>J?YR;CjrT zU_Se%3*}x?cLSPm{?dDx)5f}DZ2tBxTF(i08GXk9r?|NU%tGW{Kiy5UQ&WcAP-9uW zyP^0D2?PSaKJ;15M%v)~r18ty@HTVNkR-`RWjN)#g@&e`r% zp_V=|ggs_hs^xtHHsUh4aC%z}uEm$?6|>~D+0s)}nZc1Zjs_-Kf;UFm5?=>i_#Rzg z4=?x3n40inQN>$Ozep8(3KLTL$-K}vx0H5zHj&_?J&(_Jj)Kqxk9YmOv&@-Dy!HzM z#}5DP{^>X6*Lns9!o_7$DcKOX4O5MQL=gB>n08=QKQ&Td)3%g0YGcRdPxvgIR?zi+ zmAu1y!BdqLiQBBF`&)<4?b=&`M`4OdasJu*!IA2i73e+r`jUZqQ;n~uG3(kz9%z*6F>RRDC~{IE>U?p3_^~9Xkua_ z?x6<-0l~9=I%T2sbJqYTwbkbK@sOy>{uC=B?Y1($g?m*W&}C_S-aS)#z>%Ahn6O4x zehV(IRO9aQ^XJd9#RNAd?ekn?6Gpi&N=x-(VqJy?-1AXBhtHYY!!8CXc#WHDNoh3k zv?Uvwh%Y0twI&A&&*(6flF)D7zaQDt)AO|r>Xq(DZT#>A(}m*oTVB+sox^zx4(b<= zCJN80jYLhXMzKiB@kqWQoR8+Cg75kVNIhg;ZMwU1b!3oL z6X*9X2(Yqy>b2)ciN7JpIrT0X6-MXQ90&PcCHn{kM*tyx(B0U8q0Ch78>~ZdVr5o$ z1TKB{xAJQkd{UprDzuGf?<|gS5-|1^eHlyXTwZ~@^q8^uM?i|*z}`y zkop)4V(K3=Q0$+nb?*lg7ocmQwRCoNI<;Q>^u0Q_ut4g{M3}FAqL^BEdz~r!t&mB= z{RbOU+85fJQ&9qk!NgzT3*;O+2mk`JZ?I_)Q(3t+GruKi?|syv(@XqyQAXR~&5OQY z-@WmZIwT1;g;LTE31N9CItilt;R)-lTenVk`xFuHX+;v)v?_?DISBJbMkAD8lpov< z!%Uy4+~@zMgmKK)QhC5m=ey!})q8AA^YN1>!E&M|C6#b@ui6uiFdDlau2H1dEj2QZpf2WtSrAunz)*6cnpgL?_XN^T`;AAs zdxvDqY?!Wj`w4FA(;>VQQ-A;f*-acL2DEgx2*iptIMC;Pk^4duN3iZRB=9j{oa2U{ z?wEW%C*Oz!B zh!zwu#ubdYGh^~S{i5r>|3jf({V&->fkW}=VcF#tqdW^;@mK50?G^!f9pYt^{a+BG zc2C*?eTm2NSbWncWph9d%p-Ga*_I@U!e_R3V)@oC*eBXrwRXYm$Ya_*ez-bMe^C&ATTQaG^nzi~C4WZ^geI7Y$r$Cg>GiH+9>*@OtjI)j8E#iE&e@+?Uit@-H;fDza7`nT zvM}@-M`>y4Ki{9VACGi*caJQ*Y~NoW56;SBIT&}M)z#JA-I%=a!yzJMmN1o^4#wv6 zmgK$&3+nd>e68L$kSVtM9Eb}=MMZonJ{{^atAQUcfB`0z&U?!d+xg>VaZsj8#&t?c zS(qJ{)qIu%rUVXMbO_7?7i^kkN*$)+t4jOghcl1LtUu;fNftg>R7hA>rIf_RJEYfR z!F0u$Iy;zLtjDIEJDBupZf?egX{$L|uSDi7&dxS$%{Ft!cJlG_>yl%^O+=9p0O?C5 zhz`(V=^^p1s}lum+*o2Us-CZhDd@C5*Cn`7weH&g{TaQG zP@K!o0$Scb1n(7G+>XHznZf8Ts4?8TY~ru`IONdb^VGmt9@dXn-_Fp7pUJoDr0?)#)VT;=O zVCPzI@ZOb-7m3z>ucjw1J~jnFWEWZV=fTrCq$lo3$5bR_jns zeU)XTD-9bD&K5pj-nzoaw>g_Yv?}$m*?XaQGgEm03WGT-oIlu8e==1Dd_=q}D=YoR zNC^2V@IJry-hQKC(o71Fo8gvGjYA(=G;Dn6X6z4v^XoDZ#4L<9eKG+0UItv}q z6xNcB6Y(NgSI<|r!cM3W?vzfEhmltSP$9Z;DxNVZ_YyDR)a@?!L7JIc&PZH|TQFTz zK%{+b6`os^X!W{F*y)*~L`gJ(mrPyZTNVuZGjmc!v7BsCOi_FL`yMCz^WDFFo;-eh zAIm#Hc%+(dBfOSEw?`j`?{rVG^#@*HT+N53+EGm9fwa25kN_!8W+fEy@VM6V%=&Or z+Y##PxVT+1&Bh$f2PN zb9!el6q%Q!-AmZQr&i{dX`c5<+!CLYAXz#-gCMV-r-KG+$0@)WDBnN&)3|>7RuCv9 zZ4*Ls;dN}{fF5OQd!s*-Clp^TQ4k1AKR_EIr<)iA4-ap`k50`&1#mI|4pT3c%Y{?(f%o4t{dmKGi!{?uSvtnpWeY0nE6to z@Hxw?a{b9e+5>&gso^e%AkMgevG0_3Q8Y%KHyXwlPJKTIx|@W|P3IG{wS({5T~9Ae zCAayXukuST9`|3_$yBYnAwKt+_#4sGRJ{+RlW7nf4UCLlPFnROJxazVBBbQRJ#-X% z6?QSu{m5h^i^s#M$x{xteWv5qJW=@Lr%C823PXRXCpk4eT{%aSUs**Z^H~7-|h z<#;JV@XFh23$s#^F=ga=`b z7rx%&qZb5ATURbQRpdYGBpp#aj4palHSlmSG{`VMnD2*Ft8z@}4Tz>w8z~oB(yFSe z$?pim=^R<{NeTS8uUzY4%T3YtrKGLAXul_YJF&X4Fy0I~#cms0nT(G5%2`CK0Tj&2 zy)RfdM{?nD*X9a%e|L!stUTSp zBF})2N)zvyPtw8rsz47MlL0?56!XsW{h^^2&L0mcF_|RvvwP>DSmz#k0y4UK=Y0Ti z0S1ds>*W?cybzi*!nYs&a4p8Nq$^ISqhe@ZXE4U)29Q9|Q*{f7ye$j!|? zTlZSoo)fMoV(wiy^u?a+4n9fMYMV|wS(%N`)BuDUaN_YAD|L*hruq1oYeh&Q)(EaCcMXvLUp@*xiem-d!}&D|H}90 z2{a)&Li9-iW1g0okyax`%#^&AtUp-kY*}zIN;*o zm%m>@K^>J_z9fViD5w!H==Aa;4hph#`Pi1$R_0wLI%Uxt#=tR6A8aIjWZ#X$uW=gR zHVR8M+B`}ZFP)eoUeAR1%dxs0b9`D;3%$a7Qz6o(pOG*>vbEFczs5>| z+g#E>9kR`^l}VxWt@2CWHi8r*VNJ7Asg#B8&J$Shfkceky|V1n%gcc&DfAzBuTOzO z9&|e{K(juSU1#`P73Z0TQ2gLN&96v{JcU>H0V7IHyN+or}w4LCAh!Ht?rjyOH!` z>74wG-8#WH4+1fHKig+l9mp2B?S|}^Sk3k`@_5eg3sd%|mZGWEC9f))~W2csI58nGTJi$pz(FUReRc$6($Lw7(9&(wZ z`g|de@0lUVFX4z&Gw%@~)%q+6U1#=J2=K7}f6Eq(Jiw21R~YpMdqd}hCk~ojzddJ% zoww)8Ta8lx6ZB1gDDpKNzw0xX7LxrujP6|-OGJ%)mLZ;m9gaqG$@z1iz877ZCQK}Z zzYkx&NTtbq3StTkK;$`@PSiaF?P{50>F_RJ6mt&)0HU7dU~?(H&Wd+^r;bakrcv8i z>$VQIN%`7_FE6?F(AD{Th#`5aypNDe_IcWp&0@G~k4O+9kXZY$##B<;_*7CtHp;{w&B2f(lE!Fqfy zfvBn~lsh3|VaAYbfSid5B4Ob&8(>`-%=LOvd4t<%b3nsNH(%XkFo&Af>y)#rt7}jT z%f(m-rE>r&9Vh6N1Hid)KXju5D3N2)R~zRvDs|Pr9;iuIMmAXacd2)86C_laXpyRC z3t_Abeuas0I#Ns1yRm3yE-khi(#nB5D?wRmF}lBv_eJiNfX1f148X2V20I}N>Jpp1d>=uiLj<<&%h$Y2NT zKjmu{<=d>JL%UagxMJd7E%Le&b3sYPmYBr?s;!0BY3}SqJ@@LdMsqa<$#?+nW|E=O zGdc{RZ|m!h!^d>CW-@)8DWaHloiftWw>UUH6dHHW%+0;iB?l_a2bK#VIk}0&0RUE% zr6pZ18oh3NzWoNTB^3n7$^|ZOa1U(`>4$OJEy#g4M-?H}>a>4t_3*kQYl~Y|t_)%~ z2LHhY#S891y*#7|1(HaiaC*wLccVz(NCqfq{VoJcBRy+u3VjMjGc@BcMD*$z~!VB2fIj z&B!pW@jzir&_`ZsySced4*8QYe~WP2#y_qk{plOwvT-D#XWA1L|7j%eSc$>RldmZ! zrB+?-O3tfc~zY1Z~(VJ6<%~c+}awLlyviz+u8$I@VpXl;$g^IKX$9~kDOS&8;cQ| z_TL-1GAui4hT?>yi>+;JQ(Z)#eT9?BTPVJMcF%aWhmLOWd6EVK*q6qprWe|jevib& z-gVMqRFR}D+lCU;$+A(MlQ^>06*w{DFUZbKbtp>kY0nqUsL5h{SNkps{(_=xt&kQ3 zL0j1pt9EJ;i+uBYsP_&TBU;5QEiH8o3G=H}PFh3a!}!-_HMv7Et{Go3u(33&;f*0$ zU3@Y+((hcO@ZjzDPlGLPbhe`ahm=5+h5Hc&uOb3Dn49s~7f1ZMT0y zVU{~%d5tG)Jj})A6R>r{;#+dFSt6XxL7QeD4Nqx>0A07EkKN zTI&5Xj(OV`FQU!0xdOdCXjMWA<2YPwi>6iHjq_4TGLCnXg}-G+J&tkoJayKi^ic;} z+n?qfs>_IT{>E(G=i z1Qnk(!q_-oT)I_Poz?tendPp9dvGPIzjOv}>;}~%liWp9<(jYAvw;DT+H|%+$YuA)+*9Xa(RwU}@dWLDqE)e8i`&|5qsv(>@VZ5wxQT_YGv@z0zPPr`- zMgB^nu$&ya#SEDKq?SI{LMRe ze515Iqp1ZQKSW2HdR#arTottxX+95NT#k)0jXM^0ieX)49ep2kP%YzJT?taU*j&le zB>zNg0-E=UiL@DtiAJkK`6yf%b44krGc!VRX!AG6ch7-1qs7nRQ_m9*Pe^}Hm6QDG zt=ASy6}5cLQ`gg@gd&q29eJE4JxU!6>PDZ!?Ww#>OG_|3_{w`(kSokKT@GIW^F#l! z$RD$QqWd?(0*F&UzGm9g_eQ{WLKUBFpIGdGcYxyWW4O(mwcuYW7d`ebKPVLF%U_Rq zDC?te#>sE8qD2_40rl@qFp~g_*ORL)vR;8?8yg=F3BEAeVl} zn9uZkTM1U~^#O}Z4=Jh@#Zr}s4>{{ZvbAdyAi4nQ@HRr_4J`u`r%c~`+^E*Xl1HMA zvTJ_#O79SwObptQxiO`JOCg1iXl8= zy0jP^M1J6z4YGW8c({b1wfd@Xz5?oSFt zNo8q@#DSVA)wS2N26S}$;+WpV!TQqJN3+N%(~lLnA`!k?h8sW6Ce*IvPIe4{sb%#e z4uaV>w&p0n&xYO3pV|K`=N6y6dvp&&Jh8gnucALtyme!9GMtdg$C6!IUbk*yx6 ze&Cu2?jEJ2a)cPp>&0Gz%*O)$NMVWU$_?<`K!vA-c2k^z1$o_x=1c31yS-C2%@)*> zVq)hY+7d^XZKO{(nO;9VnSEYTl|35}&@%ZAt`cs>qoRMH+ROapY@Pm}!$IjL4jlTl zv-u#jpmYHvGFQE6zy{oqw1B>nxmii?TE>f|Ps=I&DJ%)42R$ByTb%JO?Wk*!v2|Uq zpQ>iATOj$swFTQVwTIu*IgzS?aMH4SR3He1Q(w4q)svEQF{yogN7WVYD671`gLwvn zdHm_9&l&N3Jf+Z!F#Mw&3?t@=TWQZyFV;+3ab2ln+211{ppLXV_IE-sO+NhfOBzPz ziW(W8tFy?oY1Yszg@n%G_}`%og4Yg5eA~%t+Mqy`CFGcq&Q=g6sdV*E;O(CZ7g5d` zH&?_R3mvGy5s!8kG55KNojNR***{o5p>Zxrn;96#H|NElH9k77<0ebi(zVvdVo}qS z{5}2=>iAWyZ5k4}C@E78Dr`wfjb=iyvZ|V6ib600cIy&0c3-MA5tOZVO^)0~9XFYn z0=&HufFWfR6uKOuvR_rlKvk@q`$`yUg>JiUVgDvQ=Fi=R-E3M_qSiA)3R907-26ra zLcuK}`u}FBdR}g8SaUdY6?Bhwp!q@4#IRfFV9p6MDs?<{y8cX>KC|m)oYt5*YK7n= zspEJ@MiQ4;j>`aSlYwe<=jqV-*F zE;|StMFYzLZIS$TVPRBA>e$2{y!B8C(GOg-MX_r$ zCH_umJS#$o$Z}P#m(d=`B>cTm-ej1=*ZtoKX=u8tTy_xZRnDBC30=a%S}+^TQe*$j zrqu>K0SB%Rvr2kTsnsNs4IEtPS{3%mvQcbMQ>61f{5a0VO4?>|{(-e2x^BID81>-C zQuQh^IUH70(-q=ntgSh$s`p6$LoESKh8XexIo>bh;x+=azO=N2WILJiAsDK1;nwy# zdjOCNS}eAHQCblXN*1!X@vx?pxQGY}tv5Ba9~`p;K%z3>!fnWNxU8`av>)7QNvO@} z(4LXTis3I?+bN0lvceqH-XqRJWr%0-h%^)G04-UQ0mqrUC8*dl$CH6BYN>wwy%g=+ z$en*S<#PyPl-tec>J(b)&7oYKn^}W@{>Bkf)E{iOPn@hdZj=?f4GcUL6HC3uH!R>C z>CX6Z#x%0xZFNraAG6+iI6UZ6lU{w-iOeVotQ;R7k2uOK#0R9z>BgvYv~6pM`v`nH zD5Obm8Z?lb+}wQwPgB2?mzTrB%2w9C457kIAl5e0k9qRr6tSoj67{T<%|Riwwzh`t zco`T!B%iVzun0@PQ&Lk?r{?Ejxrl>hO0)0Ws=040vh(PdqR!p<{=Ak%IBKli?(pd7 z1tTZX$3O@gp}R$1#o>%?YDXFwh*aP_*N^2o(>6s5|D7lA6Gg~aexg;Y=SaNJiM zybWqg)bdqsL4DqIc0eS=*PNUrX=B5p51;Eb&&?1wb?H9fwB)XO&-B5v$Rbt8IpQUSGtCW^dOX z;itSfl0i)p*Xg2&^{&Zp^GYN6vNy~f@(e_|wdVq`R_CDxtO66j>S$?LQ!p8d($7fr zlmX=$fb{2+yG$PA)Accbk>QHWTG<@m@A$n`|QAJeT?4^ zkMb94`oP}$qTKdQibTlF(nU~mQPF)=(%4@cbva(nK;yHXLe!ogvjE|51fE*+;R0Wa z(Go&X!Rmdmqxo#UI-GzhK!3QvP)+C%LpAGph?=&?C&&!f;SiWmDQW5HWPchI$GSRJ z9sxed-<3{QUG?Z z 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 literal 0 HcmV?d00001 diff --git a/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-10_02.png b/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-10_02.png new file mode 100644 index 0000000000000000000000000000000000000000..a744f3e325bfc4c53733abbd226ba5eb1de93c80 GIT binary patch literal 15360 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 U7v+D%)40T`V~TP~M=sy`Uuv3#ga7~l literal 0 HcmV?d00001 diff --git a/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-10_03.png b/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-10_03.png new file mode 100644 index 0000000000000000000000000000000000000000..41504523cc86e0996f01a547ab0d016d4efb8b7c GIT binary patch literal 21541 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 literal 0 HcmV?d00001 diff --git a/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-10_04.png b/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-10_04.png new file mode 100644 index 0000000000000000000000000000000000000000..2e9743e1693a8e1dcc9ca62355bd73cba938b7e3 GIT binary patch literal 13809 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 WcgEIY*EK)R&6Ly;B`L6HV25$SFakPbn*J2u_T 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 z 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 literal 0 HcmV?d00001 diff --git a/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-12_02.png b/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-12_02.png new file mode 100644 index 0000000000000000000000000000000000000000..a744f3e325bfc4c53733abbd226ba5eb1de93c80 GIT binary patch literal 15360 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 U7v+D%)40T`V~TP~M=sy`Uuv3#ga7~l literal 0 HcmV?d00001 diff --git a/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-12_03.png b/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-12_03.png new file mode 100644 index 0000000000000000000000000000000000000000..41504523cc86e0996f01a547ab0d016d4efb8b7c GIT binary patch literal 21541 zcmd?RbyStn*DksN36T(xE@=^^Q%VH{>F!24Hr*v4ASvCAgmi;+H>iMgcX!7=Yy11| z8Q(eQj&a8w9A%=J}XRvZ(Z1RVl_V1ASkRfIqg!G95a(NMsj z+2=E@;18dpn7X49)Wp%nz}^@lW8i3O1$DGCH+=4FZ0}$Wwc%jqV`hK#+|1F@*5M5c zi}n9}fEj9U%0eZJGz}VgY%8JR0D)l0!v7)oxP;L_AWG36Mc*mArtZ(Xcs_G_=sljy zQ+hA;Ugka8V~NMP5JW^oYDH1rWJyBS7pDB@!~B zW6`$~}#eS7p?V*dKR;%CU8kL)S)m#4>lNY194{2BAHZlgmkEqb8_L@3nM)GLZ} zL(FeQMMVeF5q*P$gP$lup5oxxy+en9FPS9}z*k+!j1cfm{c~gp4h{}sF623Q&F>im zyrli@|6eb;CF=N2H#IjuMnhw5#K6H}M3qe!_~`B3GHo1-mVgaGKtRaN&ri__3=WP( z`uzE`NrJqgA)|jIUmC zHa=q%OHWUKgo?VlzHaQyNKI`liLitVzCAua?;ah+4(&E{=2Jw+=zLB?<3B#G+|ki7 z#4IkFE6oVe4w$g`US9rGSXfv<;0%Y41N=ueLnwU0VqzVFW5;+C>Vng%dpa4_dU|{A zQS41Yy<#z-1KC<==6|hO{hXaWI)a=Zmyi(kt%L+xI4KW3_@u8-f`CQW%KkfDQD&y^ zS3Cw>0)h`Q^fF*~=pW2AT&(Z@Eump&|I>uXvV6Unv02ee(YRr(wz|~rKj%Da4Z$Gc z3?}Dyo=PauZir4yBmy%DH6x{_9{Dkswy0bA>G8x56{MvxIbq}R0)@S~20Y*HP(uDS z*>c)260VTDJ5T3>xsTr^<0L+Q%rYHKe}<3GW-^qhIPa{W5GA6EuF>qyHUHBor@lV1 zzP|oR%jNR&vgc7ds^{Ht@7mg0qFQcnu>VUJQ;7HcHPRX<|#S3%vhd`+i^D`OM&p~*Wsl)jrLI-uyRKjy&&zoiNU>(kj^8F`XQoUF_uZ}@>}ADA@1BwQfvm7O zT=U(?om-VpfBXI>c*$sMlYu$By1v#q@@#b8mynWLUF(m5>@75>OzQchxt(rQeCo$N zXxOBfv#E+)Fw3U5XIcx})P`gZ-Hr@S(%Qof{aQT%FB4eB2OH zZY%xCQl0Tqos{F%UJmm=vi;k-36eIrPQi)+|QFXVcpZ)jxn zQA#RDDPLCLdMyU*JKNoox<4gaJP@$aWSyP4!E7K|-DA9e|9)>DlY|pZPfrix=jRt3 z60&kSDs1{I^W9JqM-W4XC$8`5<|up&E32z^4h}S6hg@B`dO)`38+mFhCsCerbH_j2 z-@*zn)&~=+oOV?W4Xs);ySuv+yvnw>x5tY$@UXG5YoUuH_m_)4&6Fv@ycNWY^aeyn zZ#M%?5>{*nj3HMOeNi-SOP^8u`ud*p@)DI}?ww2-Mg9gmHMEq&pyLs}bfUhGCl?35 z&NfbiDODCrQwQ8>~Am9o_F7acoGs_l^18{r%U_(9X_I ze=w++ganuVONWX@VkK9>WssHmvD#nz1adR}1nuFl5f zSQ=Y`>mzdU_&h6i(dxL-pR*SvPp|W)+E1W9XJQJa5s#RnWYKFO1E$c^)3a}2pi;Qi z>^F6GcD8guxnn?3&=_bO{8ImLjZO$KGRt5)ZYG(gSF|$I(RF*9f7<@@ef)CH!Of0Q;?45y_ zReE}(LqoKztWUwZT5kMc?o4a*f=ADw{G(=Oy1_~WsMG8v?vHBS9sPQzC1$|=E_Iwlz z*6YvM7>jEuK!*F<%dr9l8Zcg&AJPMUEtAwE+x?L)C&w3#@nM$YDJWc$#q**290Nu6 zPH^O2ll&vQdGc}2U?%YIi{ELjRSIwiDgWf}Puh@@z|woY&u|xrH~ef!JKjbv-$}x0 z=F5$a8!}-Y+)t7<+PFl0@v4^mzOh51g6BQlpGxicy?6R*I$2iPmg`Nxb&5_zr_#SR zk47$08DG?%NT`wD>tVvZEyhdP)PAGocxCDxmG2I#(MhO1(~OW9qU7&W_E_&W`X= zrpa*faVzXT@`p-MbbR~=W#wnUfae&9$e>ZLSjnajZ*~p`nJMO@&nJ&_Hm2H(m_i0V z|L^!a7@II6HouMG6g)gU5l_!1uX`<7?|zxLcHM=p3UzGx+_^h6qQgW28JLKE(_a}wU4;C zxLd!nkbeLE&1pRoOQ`30>~}Nv=g-zm4HM72Bc9jI85Ir9YWAVS&Uj(9`B>oAmYMt6 zR(qC65cADXmj$<=TI<;pU~j5ym)`^2?;je<1$J*JLzvQc)}}EWj32S~8p&d^R7O*C zrpEh>S`lk##`as&d#1<*g1j7<<&tZVQ-s;F;I}00H`Z!Uh=|b7Jt+W8XxP}T`t)yo zo%d&=;^TYzV;B&onmu^RS|8p3L^A4+rkisZ72KO|OaKPf7B~Xzz%)W`1NdRrqdo=7 zg}7R^RtQTOusa5DvNwi#79Z)~UhG@V)#Ct=`Sa&b@Yk=)6KZ#g^ie zU;+yRKYxnxU_3&tHwqOM)x`x0CP_e98H+xDNW}k31fBI}Gcq#TUTlSBSm?EQ@@duC z(9zSQl!yQJ;rl=F^YaW0tBO)>{tWFqK=vSx{0b9I3TW5N{GclCN<_~+g zYy~bEdMB&vYB&$@z;DGS%d{I#kRyT9H@r7p1$RFg8NX5pxFnj?T{Qv3%@` zii)+34a9HJ(H*Oi!Xq4`0!BVMl9K3PKFA>e8osNRXg)$g0badCiDnHEo8cq)sICEk zB5X~TQI<7dBsUMw&1pLyE_n67xjEnM{ad2tcDZ1q?8*?7t|=%N67HLVFbuX zM@6;lmj+vC_Sl{%B0OxlWv*NFzQq?Zz+sFOno1mM@H3=1APH;)>y(7=r%L}KENyWatQdKSe1#xbmWo# zO4rx5%}od3RL({YFvzA#RGADjYx>vK@%W=+Zijl@jwjXj^)mv$Jp2a*7$rZJb-Qb^y$+t;0L$;&9Xb&`VB&So$C0*R#-Yb zI025W9;ZAUoIwo30brM2HWjUnsjR7k+-1(LFj8G~AZqXQ%g}=!de%c+eU+F_)gWWS zt3U%H6GDT$(Bb`Jz7?Gy0DS9XyOy|a*2CVqDau(IV=&DnExS!5&Zi%EF2yoFD>bV7V_@6;Z<=-SIybE%R&4TulZb;Ju4KP@*ufGF56A%W1qz(Bo3RR`Txkswq|{DFF1 zRM&tF4tXUn7ceaFKRNTszC&0-ul9e6!?q}{rO4;Tow0et+1;xo4x@YL!2|LkW^P}) zo9^!s?wC9rprksLOpNdZ$;vOGh4hhQj%xv1%YujpsejoJ-eNy$Ca6zBfF2!7;9PMI zEc#!@1j}+d!ZG60rkzi|{7d)3SQ?K+htUPPzhjoIcY!l7_RqlxIy0X$ z_`@;EQET)fuF2_4?+-lT(zX2T-u_IlyVoCQ-|v4d@^vn zQ?v_%gSE>>T_~32KQJ4;30T=(H3y?EoJ01dlZr35oMZ+bW)iCbV$O$fM12q|b@lXA z`oO%w&NB1S1<9cV!=m;uXw1?1h5qV;YYeCJ&g1-73-@s3YyjkNP|-`vPeLx?{<<$EL` z`COit3hu13P5iuPn2t*y{>I%tUc92j9&U5H&R#AH(~E|?$ca6y7`l2f!3m9|t2VE* za$u=3<(E&;w$UDTFueaAC&T3MkNLrJgNC-dZ+DbSBH~XFg8~k@Dl`@(5FZ!oR(v9nd7xmAp|W`4 z8r!ChC@T$jzopr{tf>!d2zp$Y+jq}qeYWoi1uNHP92MawT5*G$a%id7KmS@vS zs-HMaKjmU_1?4x5WUUTiCOqKzZUH;4^1L2nvuP}(AKq1Y-4IwcMs;k7)=2&XIS#b( zF9edD0LFwB!?iv)^1)>YweyF$Pg%^rxk>(CqIb=HE^X~c{2TA$+-o@?_QU__Wz%`u z{#I*O**$|dl4;~r>3z}Zq7!_BL@7qu?~o0yVvkV`WhCBANYx(iw>mzAlIT|M|9tu{ zpu&fGCj``RMm$t0QrXq)x4?d!OV(NwX2bhV$Gq>zoY6&|XKjW#!&#tE8Ge|ENFyU*993hgyrn2tvPqB3-;dP@kjHOoQ3P9;AWJlSTulIAZ)& zE#<(c-Yn_bd=p%J?QkrE2fD_rv3}bnEwewUo|Xw#v;RrUmugl_=!41LlNhc(JW^t} z-yig97BpM@71`gM5`Xs_7ST}aGjUxe3jggsy0m^K+K0)U+i~d?#j3u3mP!`rlHON@ z-=9S%%RWfo?*vSqb%NNK>`iFMMn)@h_sT=9}3$M zbe6xqys*tN*5}IJRb$BWcFOiIT2`BGvvkCZYPf{>8V+0Mk^Lp|_IrPJO_bcKL+Itx=h zZ(qCeV;NU638vgpGeHQRaF(u1P119HeE=;5>vcyTe%B)jIiY$GDZoLeN*gNeDU2YbWeOin5Y1v2&RKOF;TKK1EOL%fo_jo z>`J!nXAo-!tKb{q;-!r(;FKUY$oM!0p1~{@dlH@CwBEHqvf1dEuumbD}_RUih370(dRiCs-8j!ok zOIJE`(|PRVQuKeQzQ`B6f_BwTFCAb;i42u?nZvDD;tOW37|_M*ll&ZYOf$`V^h+0u zw}-($H!vG5Yw?6dcCeqa5xx8i@8fr13>ABdRsFd;<&w_r~AlHMmh8kN_^VR9*gQd(S7}>IDIi_cuf&o@I;esqq?S9%Xx$ z9+VdPe2E^-#?qNfRt5k`Zfx2>zv)As$Pn!KY5piaa19xJ_Wyi~+J9f5(cQauLN<6H zN5w+=M!00e=Q|v_b7RSPlRAqr`(MpQ$%4a}NrLZsR%-%WcnL9<`|IWc>#FunRLuoz zXF6Fq;m^RJ_pxHs(q?QlW1?zQT|R;+v`+-@6G>j0)TEgPFZ{9fz-A;9j*&BlV)rdJbSpb z=X)Y91vZ$YHCB53gYYZ1LKsavXICpBVYvHn&`-;R3Fk{ z1IdgCOThY*0x~HNq;EvU#T}N~5PqmlW@1wtMqE|DTF~;5=Qv3+n6)}8euU!>j>Eb- zMknhKbB9HZqOx*8g4*=r8$2Q+33qq*B&eF`(D`ndXB9VX72P^#Ch_&aTokWs9fxRS zKx1Bt&ajGIo>!oG9fCJVT+q_fg9bkN*noLAiKC%re$R2j_cZ*@^raGF+pjDUU^%fB z6cp+kXAe?TW(cDG&Pc;Se@^!LKrFtf7w5CL{uosY2 zq`hwt0plEH)t@ChI{C7J1Te!m2^XU4b*=(W(r%8V9UouskIz<(3R!;Oqh6t9=Av1= zCl~ozsHc-aLf*Z+Z!3VH8IEu`V4}8K3HkJVrhYg2H@YQYh5t~@^_HFWW(dac)Sw4Q2Hu<|1iIonbTp<4$BwK&F9D2W_^acD{ zl0pPv(gO|3g^r(rG(cZZ?xM+BBftY463Y)Q_U)`zcraJBFDCb33$26UCUaX$0-ze6 zst%6jP%Ua_unTg7-oLvbuN&^0%s19KIGpk&_&hPhELSQvL%>^sI@9HsaDd36m4xcM zvSJ8eFj3gYTLY>oI*?VkxVKv3gj%q+K9Y!qS$_z($CjH4%+vYz6Wc!G@*4}VH z|59CVZ;|d;82vqFA32zY{xnIT;d$wVmpX&WBaD`gKUDg`d)ee~V8Uyyo>)dD2(SGb z+T+KM)wCH{SR%deZvY`kqgiX!zhAc~tEh+z0coyGke!5cW`N}WTc)S?<2+Pidn(>O z*}Uj-tUjJ)^!#^?VSZ*5j4T=)(rMESV}Si&8=#h_Jy7!4%&C-+l9CR#c->AlI4}UG z#&~b40wQoeu2gM38{gF>YBCBUNh%S}p>henm^iIAn$VRa$2wLciCC0#JCufegHh9` za}HoJK&t1LjrRP7rt*?&mwk8NYG>+~(%yLdt=$q;OqA zfN0j)$N(Sj8W2oUo0!182l-P5p@r_KJptYNBI4y5&tc|5PgaaRzQ=zJtC$+YxKk>6veHU{Qo>cdG9^2BQJm5qE6U%)(8 zQh)7;GivLtvDlMwE5vu!R$0%>F|W7+D(|e6xZi%jt@c0@@G8A?2S5DC7i5At?AIg! ze*z~PbbdM-018R1`C+_J32@zV>QyF~_)My~hTS0`lWV&-#dfRV8you!Q0K7f0{~Bn ztOkDfcKZ5D;jL6S4K{q&Vgl8+s3<64$M;P3emT5kVfMpo^r`Dy#L#HvkJ(nje9u4Y zyz$ODQy0Tk?P31ri|woBj<#~Ii2Wy-*^AI!lz9xN97z|61#6P)(I}0uUA{}*_x27B zY#5yjgi99EDcs@M!gt@eEdR~U@PE^!WdPIwYMuv?fS-Jfj!wpj|hTy!dkSA|{e?OpI*^GKH zemZX3cWb6@r!Xom01B~ZF=0PjD@L=4hq|Xh?p~|pTh!HTl-mr!Z1ZvJNwFD!Hdt`V zDfE|rUtGUIAMK2)*V~!0xaGMVhYot}J`kYz+0-IG!Y;F19O;2|ByZ|3q5krG`!x>A zZ8~F`X#Y5~pkT|d_sf?rse&FCA-l*ZD7uwZ`XIr7wUGjq%oW06^!nO6da}1EtdRc$ z8%8|UaqawY&1dU+dl=DD_g42Wbg&3nq$^X;`J%*n@??H+Nv_fqxnObO0=YKAJs+D5oSN>k9_)sY zkB@J>;8?3t(C0w_@b51M6-B#5L4H=Cnl+-s(0}{#gF^EkCo+RKxShVmAYxU>w+>tt z{%lb5+U3&kO;qci=k?6fEei&WkCNUHz+~9ZcpX zEBUI&_4fxOrE7=QX}D0gvzrkLiKG`}QV@{y{A6PC&)sp@kiI=t`JvpfE(-Eh8TKsw=VN(r}?7{8)dg!q2O&fHu z*^`QOqfWm3+-s^1onpb@34v@^(gkszGos_8k+b1vjM%DsZ#qPttk%;FMY`ocd*(}0 z({5nq#GV&N(6n>-S)PXS-)3^lmv~Pv*q8=7ry;U(YB|1(rUymbz zFY6!Fx1!og79W^n;^~(3rb8zWB3}9M!zfKV)bQHtupF;uS?X5A{Og`XXsY*9l3Z4M zAw0uxJAO24{LSd`FO%Yi^L~5~Qh=FwQF-z!n>=-xWo0MVbD%q$i5j)qN8rQ{bhWkuY}%d{m};O(BhkqsY@lIe4q&19a)oW( zd>-_QF>Ur#bU-}`#TQO^0DeDiR2X)bJ$U$2%1A7fHwWq?G*TSiFN&&W)Uh8v#JstK zzt+*4^Bm-uT9HtOQOb%a>!rJ*;>;oHfE21*aAyMK(@aJ@08S7&F*tJG3PiF@f5fN6 z&RZn?lHbS}^G&yLZmit4yd+0!O@8b2O?~4LYxjzyBcU(e`PMT#PO)y)z@eF;__eVn z4uL@a_0$c)IqvP zUqN@xNi#daBFqn4Z8T_y%)asz)cstGov0HfQTSpE@~aNID8*c*{)$Y%wH%`eC+bi2 z_FELFXNttw8fTFm4pO;t&q7jCqe-^89)QBY;N`f z^&i}Ck^EI0j;c|2NDES~AZPk`__dxU22u-*r#QthWy$106=KK*b@po z0Gt4bpHKWfSmJSr)bQG(-aZXyCN9g|#L%8S^Qb09QF=M~{iL}$|4Etl82sHZk-2ZP ztv)_L%4P0MOl^-;IZAkPl+8Og_o|7HHd%53OW>E80fnc)pW0LGeT*Dci%k~h-q^)o zfSsFy>1k^Z0SN(%tE}h%VJBie*8S{*Y4*8WL41h6VUhc%o->J~ z2ZD{8a?b5nDTk#{N9vU=`zIl;X3JQ>tK&Hc&$d8DC1(=$BK71&JE_cCln!p1+zSzv zHXUdv1KyGQ#okBYy%Z|s1l~&le#TUIcKCD5rt3*Wk0>&bzNCiE!Z3&Sk;L3sKUFwC zP`3i_dd>%S4;NAbKk^hP!Z>V~-ln^*Jm!!D9L<@z_8Sntk2TmqE?pddd2Fr{c4T|B zb)tUoMp&*((TNJ~1TCcUIRpX?04X3MfIQe02oTg;JR87L_BrvovIoI#&loIj+)sBh zWgC0r4Lokgu<=Q{OlZgei)y zk*wnroc`+I9U&w*UG$(nF50tp{zzDp5t?)CD9u5&I`JAWo$P@&d435}X*R?ZaDcwuu~g$g^eqNd*3I!S`pZ z4*>zTzyEILN6IbXCjwqWrIK9+aocph-=z|8pFI-=T=ZisEE6D|c!Z2>zR9A9m20|j za`~OV5D3`>nyvX^syPO~wD<4CN;9Q>{NWmoN+2|hpcEbf>8Bwe z2GomBA&lCEQ-o1sc5v2pqWyKD&ctWu(tPZW+xg`!*{wUyvvd@j1Nf{Q4RAsL6=!H@ z2-*5uLJB09%!9+BeNM@>?!qAPN;I2=pacD3?9A87hYOv(HYNAthdoJSuy7QPDpJn# zf?#wm0TziU5Me6t(Zl`fOBFI#L?HOC@rHd|&~@>R|EzND5t#xkE)Qx;mCh*(b3prP zR)3m_8m(e!tT{wNLLyVM#^QopNZ-e*Lj46ZGxMOm=o-3g>abBqw5w;cpzG>_S(5h`vdada|EmvXGiv_fiK=-yrr^gQjr-(>M`+C3& zGFC4PHX3AkN$>pN44CEP$i`$m-NDH@zi6Je*?mB|1e2j(dZOvZ4V8TC`Us*(p}V6_ zTx%BIDQEIuV`DMB6dqwfiJ*N_gGVn7lAiMqDh>AQxFuq_O_iFM^slD-0p!iONTK;_ zA}6a!zhm~~!`WDPyea#xtnk;RjO`_789fez5^&8X({F*)C-1%i0SRSJJ_RHjXqcD= zA6$QDivjJzynG6EsoB7f=HfZ0SY4bNw>%f6S0fEhavXe92mxu1$={w&nnB8@GfNV4bJA1O1RL!?8IL+imo^^H>-p7UTd3ey${O+ia<)JcWZa^IBVJ)YsX(Dw z4bMz#+`Q%gp>p=}mO7$q8s&oTnqxdXuyrWFx5rp7s1KiaOejZs6f)<1yYIOB7c;cG zqZ3;=3}{GzhX7P9p%X=F3C4`nh*lqkh8N?z@Z_gc_%3UhZ$T0p!734bH{Y)t^QRC} zodC+g`VN+HlzpMJ&ma&x>i~hwFp!Lx&(*Vm&}I$D-N<-teQ{_$#DeCSS&pwXfSfxd zKjq8xWet6~J8|Thi)Y<_0c?u703X4}jnqOs)*6$VxmcPXf!pkt@6?n!koiov`Uq2c zo#B884q&uU7SQe*YlH+#@q5!pDpb`)Ysn7{EwgbJY1Qm;>uNtD&1>hcn|c2>pJDj{ zT60RsXq1;~3c%qOGFuZ1ByhU6YQDj-rB!ZU!jhZgK#tVSNnYwrAZqMLu_lm;A{01ls3b|hZ7H7a@mfHSf9x4Qfkra0AP6;Rdv|^H*Y}Km%P;T{tBpT|`Fo(P= z)=by?x=pUwvS5FC$WuFnQy+mYtzE3A#LD3SqI)`QcNm+fR)#qS%z^Y3tJ#cl49dx8t_;M(9_{jLp^| zeQ^HL&X8Y`!)+~x*FyQk@L-GkO67vNIXq1eOHTm(wl!d&#-Q!?SAoa2wVbF;Fre0A z-T=&HbEq|J@3^JWQd%r~R@Mxw#!wZ)+T@@zWIgjl2612W{?|TCpf9z1&oH{dVShm| zvW9=W5KN?rqQaDhnKtMfho?VkU$BMk!s1KsC26Wft(Xn({7}Okb`4VM>hcMHss6L_Cwb^ z34qCP_Ie~VVKsS^g6;dKr9@s-G8W!T#FQ$^}CN~Kh{}{4?#;3#_XnV0?Qm1Qg+~W zfnF{de4L0=Z3q8KU)l1dTf(n0r+1~+C+Wi+?N!ug$>=3LzFJ8m)Xdc1MG@ZSl1WL7 zZj@0Tv`zNCut_=I)knQiTZl&Ux& zp8-qsn>F(!oJTVebvLgK8|s_F;OO&sMhMO3JFjPXa3WyFbIIO#mHI|eT2ZZP3qi5N zsq(xZhy8S+#S-#@$UcBn$1)2CRpxPc9TPPc2&QsV`2e>%)u6@ax*A z7eg*Lcv+l*PQbHugE4nPRKGjwAIvcZt(V|awBm9-%i(p-H92l8!6g38yw*b^&@$^h z?qfwb9^%{Dgjqu)nX8IpX9e$lfB{j{QMXOYv_qQ|r(6Ibp|$w^xuImO zI*y$y{OPun`p%}4iP1Ub*@UD{qob4h2#@0u)mg!NOFiFgPcs;+V-iL>o#Sq1a4Zve z0qel$W4^2Xw(O4bxxt8+b-~K2+kSYeY~bhvde8&v1nJw>x-9R;Xckq`0l0h`wf1t0 zm?E*2oKntZBf>^x|Hq_jwGC1EKGM|&@e2V|Ys0MB($e+}=xVGW72dS%S({`>}zeC}~Hvpr|}-_Cb@ z+tYUHmDquaru0aG6Eq-*1r8w4a_x^Y(9{0`QeL2V76nYvbhAgDn^?%4FJsX~CBQGh zy>BEf$W*A8uIR!Xh|53Gz9PpYaH;n|z;Ko0_rYl>22vpuEV90yaMD7()(7O#NFeM5 zIB{{fINJ3U59F_7`H(?-fP>_)G-9`YZ^3G9yEcJ&R^@`+BhEIKQ0;)K*u;2&9LGO$ z6F+ZJFynDXn18oOR{byM5}zZ1f;ByEXhUL}R9$LOoa3?-jODFUm+pEvQJC1I)T#L84quW$}{ zLF!cjZ(syye1rQaV~eC9gm}-Mb%AOY#+NSc(vO>u3WO!zhbvVZjDCHislR8t?+>2QNb$q(y=!wL?Ii2ie;dX-;6d)--G1 zf64g^KayzfINz91=lUCjkVGn`I$t)2x{7;w`um)n4L*L4Rtamz-%g z>4W)z3UU#UXj*LqW~$fuT?yLN;H>=Z&P_R>Q(55cSKj|J|1dh;1Ca5-!-W<|5_GQo zR;aI*ovsdyS&M&df808AIjZk?`xX$%Kr5B|ta!m8HHhG#ZGN}|HAi!-P@(M$3vZkm z|Bi4I<{jy5#LaGZqEc~iJuPS+x7OA2WsK0rOm{IB_cxS1$8>+;H`aeNt+)IOmg$bPb;&&rHPrh{;i7q)fe=e;ZeW$Au*98bB(4iXWC5{ORqM03MH9#K0V&-8?d&x6S$ zGTq=)V%r)kCOqr%PpIl%15@6VnKiXv1 zUw<@JMfUQhbLslm8FLlTnl``}!SV=b?*!`g`BgiY=9k&#{^ka5zP>Y({1c-MVBr|%xpRV;b7Od^JgXP6j!n^uJws(W(`Qsf-<0;$ISMf|-bkv4# zK)Xdp3pf5v)fOyHKWK}S(d^#tEcLr*Gl3!5j-Y*i% zzXqykG11acMBhHK)IpY&&&adW-&{jX}>%h|}iW7yK1)2+;7q2Ad@?feN-8XK4S^XgAgZ!5lQ!%~% zH8}PK0J^0hr2MPhrs1#(W}~J{`#Jmh%-v7*>(HfAJy2yKbTdfL3|%kHX==W55IS>B z$vfzmuWHyYXmt*l{tlWTL5A3wpTZKlezU-a^V0{9%87m*|2v9D?2Vj26bSSz%s^Kz zbY;c$o1dO-j^=B}j)6K#%ae1%A!Zp+Ee$4f5LoS%L5)$ivn_tt27J4g34i7KRlcKQ zeP?q}N&5let@ek7Yll6}bBY@0(dgnsG$2GyF`E^{NK(aM->e`tp{XT*y=cq+>LDu1yrhiqoR;gUVc&MX$Pkm5=5F z!~OII-CB*_Qaw9kUVD2LOn4zi@rb49qz4Cg+W&w+%0a0MC~z8P7LlAT%qgTT zP5dy{DOI23@M&c*^0N_I<0-Vdko=Rg8#Oi7=r-teU2O9#@9}w&sEM}-zZA}P{F}SE zH8#yN?{Bqn<2ibwYZiPu5O{S+pusOtH2rX1=7aO}slM|^dw-0gxOw5?OxIOM%?)e1 zM^n2Ku}yz{zKczIpq<(Nq%;BxX$ojP*2duI=;UNcTU%DZOG&2-Bn1RK0vd9scFR1O zlpav7wHN7NZx4z)U#?27TRbCJt2!;3R$jcu!VJY$v{Ikio{b7gqg>5XtxE#qtk3)p z?>EexBg(4+xoQTLAAbPXJp#ml)02E-JYyQE{R8@=A={i1$#SpR`?#7u7EA}VrOU~) zRD-nq*Wf1(Koc^S$}b2iQbCWDi&Qav#X<>i@bQgp6zpXpzSBono~R^KYRPI1y2&bp zQ;IxD#t22)SLwZmFSgxFSv&|l<>!ll1hNo7B>i4QB#8%_K5g8uA~DktRm?ROEO1I* z^IBDL&VL%uPWZJ)#Pq@5a_Nd`U`zBr(iT3NwR_uCK0}bVQkOWf8k+87tKJiep3z;{AYh`VMu*t%hoC=^ zn68Qo%ivk^c4cxJrI(-NjexNXj><=6Fp1igs$#Sl>_0Z2{@SDRBSo_cKry(JqV&b> z*+)g^Qku&)?5p&-cV-K^9j~qf?kfc*N+`5`T=->jk6X<|Eqzd^wsqmDF##0-0?3dC z-fA@Ndk+*e)*LmJE((ju9|rZ}H%S&~J$N>x-*V!=pH*n>E_sAHPBk_D11Oj@ z86oxc4yIKS3pJmszQS@=j`ssn7iGLg6krMK;*a%H4y~U}Sbx!ri3s4d7U9t8Bm^~^ z&mh{t1~vAaTv0TScV7rq6Soezz7L5ux2Zss*RPM+BOcLhm1ufDgFBVY;k3h*8PQ-I z8Z5ym53x18&^o?=VVBX&qPP^!&G;EAu`b9Grw)h`cO5 zK7p;-A-C-QyzlMuYc(e(-OiU2zY{$`4KO-ny@wLoZTanz1M{`p1^LY(w7Y1c8t+{= zwG$Jt2iicyk94zI;>uO!f@A+x>-Z(NmH0hD+T)9|60KuUC;NjD!s{!%5TXXVqu7Z# z&DS~(*{yllR~3+BQL-e!i8_%%$PCkQWm<^5GCpY9DsdIQ6K ziVwZbu<7O(MWLK;=pHg6aQ9SD=8aRsyHR68k}cC8)=)8hl{~ zA`InH?dd&svUs74!LdyT3qa#}|7ofN&ahi@V79<97 zz||F>KGA{#TT^gLf=R-sAD~Ds;M=#Spiuny`1oQIRP35Bwg`ek;%ukgzu>}%*(U0B zkXTBEmv+L7M?sGGY=1TZWL%SVqB}o=V*BRH1-M8DTuksS-F=44QDl>2NDtOFGl6VQ9Fhx077&Cbq(3m`^7$)qdn z{?cvxd%~WuIMDQPH@xfx(r^GOh)Y1i1TMsAI2%<2w{w8Hpr)k;PzYacJ`+3MJRjJ@c$r=XxFv+u$Aj^V+RV*qf2nJQ2zpKra{sAr_VK0zzjer{pz!e7Z z)9Xp4-~mtt9R(^M1Aua>0$e3=@N<_L$b612FL@dTz+vEk$eMv_XisoQfF}??Di^E& z1~b(Yh)D|WNuUB0DOh{&yJK;nZF2*=X_$G~0Df)F#zqg2LLz{>EwbPFqku~b619_z z0GYE1Zk+(ty^noC6)0SNsjZ#bAIBG;nfW||LQoP&xb=7WqyC|MIedV?v?Kw26Z|Fu zkouMZ0`ei|-YkKuC4VwO_gJ7X0xBN(io&Zsv4yTOr@!-I0FAay<34xG!;K{*Iwt0$ ztZW`AkEK`JAo8BC*q?7C^ab)MEHd7=V7tha4po5bGGc)Ckl>X%q^;6;5MJ^1>ebNN zz}h7zZYJJGIXNJV4+fHOPcJWoS;yWK9w>JMd+&IIgDHi_9vi4=H3d_>4z9WZ*PsM~ z+dr1U*nuW(5a9X{^PmAxrw4--TH4qMoUkzdllu{an7wPSQkuhNju#Ny{oo)Rot}11 zP9}hE!S99uH*kPEIWi^VUJj)TrT_}5YA|l`Um4W@=;Z99nyjNZJ`=N0C=&%y#6-i8 zm`5}f#!Qb=dMbKR2dEWG13k2m(3?n8VZ|sZ1o<++ZLR zfd+d6Hgse3{Z)U|IsVmuj5Efb=ef_l_qq4`{iLj^b^7o9{5)_|;cte-4D5!pZ@pPo4wwnyK7 z9PpKi#AvOoh>6$KuL6DNb9i>2&j#Y}TD)-Km%ASPWP-J28mI>0;T~`(R8q&a1$9!X zbS%x~<(H#jN4}igS%kZR)m+$w6c?{3^TKS8pCJ-HI?)})WR!(a;M&nkZ^rRry6hj0Vnwt98OHAKvI%f9MSOUd?D_Dm4j{t=! z2L1-T3|+Hkf5FkCvB?G;kgS8#nI!ODty$#fw-n8H5l_F$XWqPql^Meq@X;m+zCFQ~ zk!D4l3fdz;8l8ntKyZaZBPPJm3rSmxh0ZdB5Z)e*NLCxo=A|eyF?d;T{%x@gsfdlA zAuW*Ix_vtk{{$hC2hbnjj<$R&AL|9Xz-6wsVi5Sb?aZ^6u zL)(}?-fBULacKyzP5+Uc7HHu;QTi&WlLcTi*ONGeoX%52;nCkxJefp21pu*47b72Nn7F+C>T0T-Hgso_y1(N; z3?a1;EP~r~o(4AyWW6C580B**IIv#t@zKf9;ZqQg8hTqciZ@!6bKs~v4^5;JC*1}u zf;)Ic0i+qGi>aVZse2=(?HT-Ga3>1TV~E;cOcXALeLDhvBlzRbA;IM&-BLg#&KwSu z4vN(tP&@*`K?q;yPx>l5i?NZs#2sSUN(vCB|HdetK7G3DyD?Y5d2TOSlOQPZNkg@{*JakuQn^RMhW5twG(%fr|Z$Lx;Ni`srKE>2w+%IVw6|2f-##fW|TAQ zN4s;0*^QAnv}2^+B%7UX(2N}^AF)`(ipP3A`;|@ZJbRsSBKoemkbi_-CGvhvb?0j(cMsY|OAmpIp?^9LPlZKir~HFr$Qkt92MSj}WSB5u z`{*A(mlKsZh2&AOnti>a!z%|sv4_Ntk0 ziCf*L&z#9J95y!jigu%IO<-#o?l$f&^r=wTmPS;`9JK&!IXgR-@q*{aeh^2w(T`hx z`ivPj(Geb_X9Xb#|Nb*0f6|nh_i9pN>~=dO0w*OtOk{ER-EiO5|MK9 zBzK9%0ukPFC4phv^b09Lx4wOS4n6Z2T56ag(poaW<7q}N@aD;FNcb9_A;e}z{U@y} z>qeC~g1HXVXF&D*(Q0M?@bEMbWtRgF<1go;1EdyJ`$;nB{ zIUzLTESjpNV|nO6Xdxl-9kt6166@T5v!Bve= sRIWQar)AdPPe>o;{O_l@zVQifa;;Xk7t(@&?4)d1|KYl_wVxgM6IQ|=FaQ7m literal 0 HcmV?d00001 diff --git a/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-12_04.png b/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-12_04.png new file mode 100644 index 0000000000000000000000000000000000000000..2e9743e1693a8e1dcc9ca62355bd73cba938b7e3 GIT binary patch literal 13809 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 WcgEIY*EXS`RhTdb)u?b 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 z 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 literal 0 HcmV?d00001 diff --git a/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-14_02.png b/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-14_02.png new file mode 100644 index 0000000000000000000000000000000000000000..a744f3e325bfc4c53733abbd226ba5eb1de93c80 GIT binary patch literal 15360 zcmeHucRZK<|L=vyT|`nLtCSK#*&`ZS6bXq$6tZX8qZCS!Br_@`G7_>!WQ7#U-m9`# zHs^VDf5-jX=XcKUzjOZZz-L_JJzlTpy6&D;Jh5T@w)F%-Y&dmN?i@i-;!g_qKi1$^ z%l761{F1OecEMJ~!ob!}*IJ)AqibtvYGG??q__QszO{{!g}D&F1pfiP?bmE=Eo~$P z1kC>N0e%Z>LxCNNR82U@I?Iz9HUvSVNd8c`+1=ks5K?BR8XsPNiuZ%a8 zKfNawIMcCu*XrwP)`hm!IcMsQoU!Jr-luTjj`h-Y59a20BNKy=#s`Cp)mu;3nLn!% zX*l0zYSeIEh5PNf?d!O6D{_x+4(?i99&2g3cGjHoxWwo{&wf8I!=%CRx$xrhT#12D znUt*Wk} z!R)Dy#;^}~k`kMPI-`MJY5LrhFen(^25N=i#V zP0KaYjZ5fc7Y}J@Xn5qaKC?@~*%s}qS7P1fq*!Ug6%7*$o_KkA9r0vYniVqt-XlFl z%RnDT;Z^+pQA{PbgpTT9%P;fR$00)Oal)$}KYlD|H==d!+_|xdiK4o?fD;@pk52{c zrg&pBpvdkzt6N)FXOdT{qqn>`7cTAaXdu!pU(-x&e7ZqL==x998$*rnGp%}p4?2nJ z>gp1?Gwn`QVPbwYvMb?h+3lZ|CVx50jhn4^ulo_*>r8JEp5uE?+Sn{dTRh97#!~WW z;2QT=uek5|_{>e!DUDB0bM4vVMZfcSr=@u2X#Rq6;>&yDtiF{Kd?oM9T9`ylnG|CK z($a*7Zsas=Wo50>S)O2QcO2Zeo|?K%y;uK5mv-w$`na_*_Vx2oJO_k?nli0+zCNE= z)X>1_URZeO3IC;!w^mbExzc)hIE`d^MI3ah&9SqXG(BWsu$yWP%`^36?c29+3mSe3 zr(RIe{FtDT`n@GX;6~2V@t!i9?horak8}o0I~?#>OZU>SCPI3;UgdP8Oq+9JQPGj4 ztp07jY*NRMA74YYmUb5(-~ExcoK(xMBJ1gazP|mo-_K@WA1wX;B}&3|(f-cDT&qpZ zmkbM?qN1Wd=;#K*Eb`;tbbJit{n3!j;U~K+KG=|4W}ZQwbAD#Dra9e&;(Kijb)MsN zHlK%&)OYTaiLWcJD;EnI3&(3V$d|;|*4F+(OZyUQsV}0S%af(Nva+W!Q4q{wr}bw>+K9y;N^W|e z!X*~xYTVXb9&OKap89e^*rGi=H&@zmW~90{Mqzw>yel!IU9bG%jx?h>&(a4hsaMKq zot>S>T&zU}Gx)~Ieb?&rk0bDM+=KdtI) z&9XTiCi-A%%66NGv7ELx`;Q+#3fX)FCa~ zz@)%?!ots=Kfh{VV7)jyZf!_$W4QTFLBYzgSc!}#Qxpl#ojZSY6v(!`GrKZ3(I>sK zIBDASc6G6!{g0TS%(?zBUabO+RD-@Jdz2zh>*;akInC_m<@FgGvn1Hv7OgZh%+F|Q zZi|SBxX&i_WOATJ$JUKUlIj}MnpDG@-I9{?kIFbPYG0yG*!-;D`zhj}Pn-Eb=X;On zm>Bxan?Fd6=Gs(DC(2(Tq7_vK9AkS{Zr!5e`s(U^LCw-qFzSRK4iWm|1+`(TwY7Ed z{wr&220n=_^!4_RyZYv zgfA<_<>{Ya`*nT$^2NMgZ`I(p#Ga>i?ay@zT(4fe z`n`B%)0AO=cez04vElZ$&m>!%roXC(2pQ7u*s;Uj$*HHS>wQ&-P>8g{+osqPe(bxr zxW+p@=(>l8t35ZcylFDswP#PNd7ETzUfy0_-km#kP`GDiij!5W+QRk9vKl)hBffQz zC*gfrnHOqDs$R+Z{KW}{$vFv|e#@CQyHtbfZIX5)RiB?9txOcV_IdkA?xbS=(yxoR zJUmXx%Ud`7x@6Z@f^RY(xcY}>*QTD{ihy++HYC1zg3bCcMj_}eMsPh<2`Wyou+gSi zrN~l2nnwWv8Yz0K0S1D^KW+%BzV_Wt^40CgNRGL=xe@-T_uTya2IJi&2~v!jeG0^x zymJGe9Y=XL`=5I$jFH7(}<3cnF^p7u3iN1R=cER2!H#j&t{`AmHy0C2(Hz%jw;q?S3C+F5^V*6kI z`NGS|DWV$SAP|3~gYx10v)|tnXQkEl);ZFZ)m*SsUu__hd+%P|k=Cr}=;+SAzB`y~ zKbd*%fZb;(FAscrD!n*X+)v{k&Ddo!Ap3(#Gpx5frg?r@FEp8Q174hy1LvqTjOR zn3dK3NZ0wj`T6<1y}g2ZAO2vaU5lyGN&Kox?^SH25fRh)&Wxqlb3^eD+ec5Hc($2~ zwKz_Fe_yaXEui_%^b|@1HgBtC@dn$G)+U$LIsT>Se2bJKA;m95`!ma{s;=VV5;W7- z>*(lo7FD@nc=g}kT5TYU&U|pD^=M7R!5?io84jY`u|p`R)_i`gE^y??kzg!K%P!Xi zteF=U9r=yJH%k3DYVI=Zai_j{Wumu&hFv-soou3BMQOjwyzOK<>RncUsEPQEAtq*K zW*S!Uhi~2pX4{Q^D!M~m`86^qs0_>Q$G1cl?Ad-)%Pk`VHZ=!NbmY6Nqo&>|Egf!= zKlif8l~+9}8rwyBdA27(r+_`D?Gw)V9p%TQA!&8z%P{j7`jt-#@61u5xGQOEYX|z; z9VI8+dbPZQ!cKAV%+}NHgjlO3m4kx=tJDn|ckF8+quO0ED~mSW-QB^0x|E)}Z~oSZ zWR|8>4jee({oujs%N38fX6NVMI?b44^H$!Waz`DTXm=VN|EjL@yK3}@S)9|-qA9#+ zkyr9?$I)wbFE`x0d2^^S#lvOcSBl-JHqcDfIxpg!ii$>o>p>lt=`E=3RS^eU^f?-m zb!u)>t!+#?|uqSu^ew1wR-IG9OhdG<-l@se+Ubr==n@;%xO8}#d5p1F@#qN8^idZ!-MV$_ zCuCVdJJvw=y!s*xA{u!X*MK0``QtpuQXi5TTQq-45zt+W3YdtopdM^#QcA;+B@M zw{H(@+O&!A_VEFM3GP_z7wgyQv$C?90?sVj1~|qf>nhEAKB2Qxpg=e>5{1OB!$r*G zTf%d!Z5lSov{pxtH5l(h}s3*a=Mp!XII^^@` z&+AR*#)|1QvTgUG03-^Ym7eYN2$#Hm51kL&nXvBccGhADV4`b?x7I%!jYCh%X$D2m3O)#h4@B2D0skXnJ@7)>0ZwVT+v$OSSSN(bB z=2*vrid~3k^TkEOC6x_7gpQ8#)BA5D=L1+To8g&O%5O%qLrF==s?tl8jkC#JQ?e$$$XK#TXdJC9T(@h)ep9b6jfGMF1EWIU9o(_Q!FU%x+spK zh5hwr<@kBBCA@HVC#-F3sz+lKivOf*?m3mOY{>nh);m0W=Iq&x`uh6Wn?E0FGJUsZ zC1}NOGa(oKNrKgPo6DsU>m|u>HJRhIdbTbX$sFcx%hdHQ*DUmt@!TvMPMM zT%VazF3C21zJLb>9vo|YX{Mv@t-iveM~`@NU3z(wbBnr5e1IsfeEsRShRkog(KnJQxdk{H{#n|A|ina z34Fe+5=HT9uX)UJ=6}9+SekB_LnCd>u@hKXo+)quP^uml1seb&o_tQ{=3l9>mmMhZ zWLsQ1VLA0(S!S-60f_C7LszfvLOHyuuOB!V1oS5-w+e{4%plcjWoaf=x7bs@<;c;a zKkDNc2voyT^NfIi0F{ePgyuzZ?;t+GN_VZs5uzCKd#^6IzK~%^}vH#me3z0}Er(b+7^HV#(yY@snzf~Nm*~iIQdsfTpsD@IcOf~j{!%#|D z=JNa?1;&=D!*yYw)2|_2w1DWBFW=h!s9oRS=jT^eQ&Z!NasFmF2lx_nN0XW)1)Dc- z1|M~&wp007U41<(SPY!`05cjzFEsVE?o5W!EY3d$GaBh<^Z)-lXNh4 zVWMW;V_n5eo`+Fs7Ou$ta@VeLgL`t~LVpdnOqR(mr-<5}f!K67g?Vd1 zWX!*hF_W!CVs1-?I+yZYk&t<;x|BX!22s^m8vs1QfMwVq1Z8T_n| zd;H|d`Q~4KZi^oIE(^7JPIe?3z2bN9xQ0eZRy)uIiSgdQe^0W#x>%)#{-nF!-oo7J z+Xzgzx36zMxZQ`65@6rH+5teqs;5#x;OlSSz7@Cb{R6!!K5h8t>*Rh&Jp(=h`J@uC zxX`iE4;Z%k8J6P0NRA(N?xT>9ij~Ehm9bdarMSN>i~oUAKvmeW{7a0i5V#8h07Yp9Q>fy0W@D=1Q4wzxCzI&zc6#naN(C9n%Fn z%9{RmQ6O9U@L>vCuc+e-SZB4L1E~r022M%I=1b|S6+h}?NpwNd1#k+N^nXzl4hP~J zL1IA)1O}BqcK9_wQ$edvo2M=*^c^~MD9e?Cg2H*STCCq%QPGz?GXW`S2M~3OdCr5z z#zqD6$ymdkt~`G!1;(SVy}io=KXDP@Hgo{@=J|65rM_$?GCXzf%q~J7x{zVcM(o|Y zclN(k8$7+dQY|`U^5=i@66X^x=qByK#V2Vk%SC`Mf=|VNDLtR0bxKurv(MIjFOKke?)qy8HM^Am#p|;rC@>0m;8y|3tvF6+Ql+fHg zM6Tt5lvAOu`PLdnCnK5pgNXI(*E0cGLCuXZs(ab$IGBiXof##Hr4qN3pMun903gqu zJ$ne#4rMNPsDK%yl=ExPfi>Hqc7VMl_fMcEziAns)(F4_*Y6J!B0P01v1V-M%IL{X zP-~ePPGJuf3>;klgEu{4+Lj&2rSPQQNf+;)v-`N3C>A8;$(9U@0S`JE;&SPIW`MBb zeI?j(C)+F~s05v7ElK9%@*NFM_;Oz<0X+vOb9Q-Qv`x*AJTDc_TOBG=Y@Q)x-CJ%w zQ-O|@+)zY{`XiaE+#f#Nh*saKjPHBb2Ut@Sf`$eLmOvZ)+xI=JuMpDG(&F}G&vJ}$ z|Nf5M*6S`qq66e+*s?{JkpDL4Y8@IsIfq5H$#Y3*QgSlEIHK`cjHq0!g)Ed&WS_U%h-r~Z9`J(~!q zCaBE(GvOH-c6nQNkpoo2MF^X>216e<6=fm7#)XY)qyPR5YYul1J!{m9$>EHS16JK~ z?<_h#%})=uDTk5gqsKJhO$G?v-x4qGr}0=#y){#76Wktu-Y^BC998b97p?SIAr%oW zW#@}pxVW@5m?usyeHQ*Jgn7ZzjUdG>2lsHE$uYBg27uJ7ndBLq$#vkqu{$Dy@##-FxmVlC)#}TBP#&v=Lfm;) z&{LOO`+8>VOyXwj(s~I+UXOSZRql&bemd4;E4hV`&ar?2?o99a$ELw z>G2N?JdYQ2=O>Ux3z&Dz;7|@j4c@ zt!V!NwJxQ;QWlF|{3HyVgFR#2XDM#K!*$)Afp|O7<5v#w>+~yK#m?iql>NA4X~eGo z65;j}Lz_fyqTY!vTgkoB>M!;)Z}6UDm>U;ZhQyc|x0#+ktJUcA@nYRI?vOsI1TjO~ zEcpHnLI;HOQYcW@cDMsBqjLUyDLN)8w}C_inO0U*?BLei0O^3LoO3TXBvs31o&v2h3Z=vu_M*cDYcvCIO{GQA~m4OOQ_4u#1*z|o2Owh`D#D6LKjs3VD8Z8AWJ^}qx{-p_T+`L&1FL~d+8<&>&>eU|@ z9Nwv7_=bMJhX3{hbO^`kpT`PZmzZRn#bL#b3dl;5bMUw_F$5&@LcX&EWDq`7 z%ALHtm8?xVAy_T4n!E5+xcm^jpSElvbAw5|f`&Y&HsxQUtfb5Dxg)bblq)9!pleq>{ zkj=61jznY~L@h880Jotb)1ezuSnoC${mH}SR4M$fy^v*qh}zv&TmVWTp!SZstw>>& zjU*`JSjHihOzuiDbGJbR!zv-n+Jw}qs_GUhG|iL6oz^>_ z$pSf^4i=;k5D*|B@S+7C&tu$;lU^_5BBn+=B5^IhK@;pc15XOnQX?iF>5KxnLd)|F z1&~{c;P;f5m%kd#ChvzfYn8jhWPgg|v@u4QfH%;8-x-Ii6~tOXw+w>C+cP*weaMTJ zjhl}zVdfwG9KEcwt4n!AqFC@};&!rVJMnuEQa6T98XNOqP{8caa&Nbp+Z{C`2Sr_r zvJf!5Jo;1sPG8v25CnZ@43#tMZ)m5F5-w}+1F`nY|GEwO{)r4Oq#A4>fRw&^6<|21 z`VRa7kkcjEM=t%stosxsWrR7_oxd;=h1qBFyjg9~dBTOffVID24r$WOeoc1m zOL8RdpB>1E-P0ZYu{9FJ|0O#~L|ThS64xP5rp!=?X4_>@g#+VC?_Y*vpP4qpdcyN1en0y#Y$+8?D-N z9j+G~Fm^JK?BO{5{352@TwYd$95+80E;xmxkax)LVY9v+_f{GY$kL8mou zXQT;wzmD6|b(ebFEa!A|(GPdGUR%i~5NF66$qg^aQ8CA=NJ~pw5p{Ib%V>cene@-s z!NmW8tY``ul%(Io=c(=+Em(;_gReJHCI>MClbth~uK*TS)ramsi5B|pA8&yHg($>g zy*chZj??}0QXsxJr}L6~TQQaab^_|m(G2sp)_(wru_9`LH`fQxhYB0rN=_CaacWGE zw)F`!@?h?^u1v}l54L6Q6*825v2lBPY2VW+coQjC zD>g}9|9RW1?9LAkGf|ctyU`@uD; z3KshWt{NJWbO`;m80;i|s*7$T1H(}W_VBrO@$)AYow|)1`T(={)R{9}Fim%!@O@+a zHD10&Gws@Y7$-0iT+-j|<+RS)TN2ew=il7Fi2(FgACV!{uK)K`FET2yhL-h0SMY6x z#6M}-C$0?~GU3>2!EjjvNMKf@W7l>)sP*jM8nBX5(|_K8a~_A16i-hLh>9fW+;%gv zVb$L*zg*?(=eI{jrd^AlkI(js2QH8IWnF_MENrKOu#SWNh#P^p=%J@(8f5l;6yx`2X{c!|#A8H*52(Zt>VqyI~8oYaQ`uow*0xYLH1M>DCF5ID0 zlV$(y&Zp(S+Y=-*`7{fQ=vjA#dwe`ZaHJP1`{uxYf-Xi#UgrU2PPAlUG%;yT+Y8H; z(Pdb{OhqnUk;5^`nLF-V%Eqis!U-!eoaaoYp6{uBlhwNRH%F0KO`y6^pMwTXpR)ab z=$~5KLI{lB5ax}iXU4_~>r@K*WAq#iVWISIQ}*=gy4v(s|Ep%Q27?9ry{B;-w{NM< zIU?74VBqG>y8ib&OL=g`wUWPYUHG?j%oA;Q$GdzBiSySI{vWSxe1<~#@5am4P{@1q zT8bmw^HsY>kj7N>V*0l)c8SM&<)b?^Ydc~1{ z<+k_Fzdm(7(JTJ~805*A!Wyr8!gAnwdh0}(S?7BS&-#0k76D(3q{q>`__@Hd{=9eB zPyk*2H?wkIjR`=JXt$MR$i{bMT;|`nxs}*`cI*pOCnGq}(E*_X;UVhOze9$Kthlg> zIbdJEuD%2;Xmr+Cg!u5`!$vl?Y9v(d`uObR;rSTzchnyj7YE7Qs<)i}e4^&GPcs1! zD(~o+J$J1(`jpv7C_1;tITMOb@Db;UiaoHb=-tc9Pfkoslz;rl(;xsM;qCngJXt?9 zZ-@(q07eC`AlAyo$9|(c^k+ROteY&FqWq5}v)GqrL{k&#p?`^0;(&Ujd@%=nzjnKb zcZK_(m^~JB4d@U;#Yx0Us^KDEng^v};NY;}XCwvmIL^TMk??5(ZkEC9R{FSmnhOuQ zMn{!?i*HnLZfJ_PL(zA4ceh?5iN&W+qCqy+)>SehW}rBC=5m1_3RadzQH~P@i4VW4 z&&8yI^1h-j%dsPio7UF^s{Wm(zC7aYt*Vi@^zItGPr$>3iy6KkQ-31$o!s27vE;ODF8V85 zWK{R9+T2t9*5(U<2li*&Tg|1dg$QeD054t2w$(+b;_vDiJk(W(P**OzxeV!yW;-{x zH(o-one=JK_587J-E$yqM5FuwT5SNOzCo3(=S2)?8WvQN=910x|EREt7=_8WNJ7X> zK3sw-{w-SSzgoQc!hGkv;+@nBPzEFuj?48Hz_I%2UEFoKqE`QLxPZ0YUQSN_->>~O zo(Cn4LEhW+ZGkT@1HCe_G0q0IodjX8mJ*4?OboHTw$O<6mba=L3?+&>@m2I$Osfh1 zHK%(v%Ju5uXncprzXoh~lA!kgrmnTEhceXqB3np}61=kWN1R_$^Rp=AOQw@v3aL4Y znSZQe_TyevPsw%|=-EyrB(C-!Ue~j&-~YhgZc#OSDIa&~KS`zhm9YHFyvqOHJF2fK z$h^k#(n4K~0^|JDk7E4EJ2dl=H+dr~>uGFzq`!C&;Jn^U(u_Wo53sl$&?P~NHX$ga zs`^+V5<<>?GKQ(5Qt|O)H=JfL{`gPLfReg<0Z)DvcUflU3|0CXnwfq7+s^SsyPvKQ=3)(m-PvM}<+FQ$^J)c!U(nDMSG?7)jL$Pq-Q6y| zS&BiaMsuMtr~7NOKN5pcxQhPw=}o4qR;_}heUYE&?eDLJC}$%fDEP3owN=vO^*=-z zn&Lu(RJDb4h%-FS3=Pqqq2H`hwz>8m`#LzbSdd?0um0Ne-0UEMuBcm4dtg6KG8?ng#O zvhZ3LKtcmY=zrHByEd05_x^^lxc+8=N%-mwnrxNpsU5O3QjNbU=ZMq~UC^Q}d;V+i zbIPm*oBBw~E1w?X>{D4yd6Pt6m;y`PW?KBl`-s{94d|nEDQ!v1)RZqJC8fa9f@SO9 zmFrUd!)4u+Y+ft1DYF7>KAth()=br;z3ZQJ@MfT&G$|GOtH z_u*)L-G9iCpneYIp8A@Ct1YIZSD4&t3Z+mlv_tjyL;EJ z+X(z*=j_U8M9dCl6;#~u*H8tfq4mFi7=}h%lGY`8ucF`|%lZSr^d^ zR&h&rCE2CNr0ua+K0(sq!b8+(_pOgJ$RcJIzLiWP}tIQDjDLoNK#!U15>P|qwBWN(s8XhEiR|h z$_FkVGMYduyRokkHxB;({o3-3+e$-Q%-0-9XJkJ_0CDvp_`VR?_d&QePfBo&iH)6X zv+LMzKX#cwq4PkC#zmPYRk^rIc2HY>Ay>e2tN^5g5mmVf(Ts%aSvjm34xKmGa&vQU zM_LD*0upx_0tWVYvGtN>o(Tj&u{K)E6A2!Ln{L{{H@m z3q3Y(%O+D>cu0Zv^1C+c%6(HqO##pX$ow{}CByt*86B?Fhmcr8Cjnx-g$%q9R*TK~ z();&m0KiUOxWEMe&=A6{!9i^8E?=pUXBRWfX~6EFh1(c^^GOVfh){%}nw|2nDr?w$y8dm|c= zqF=c+b!osY3tCFEbP|#$&~?4g-+O>$agBHH-X&Ed%v$!)KuNn2=@%hhqUE+UjU@R5 zk|}|&_hBH>7@i2|xPIx`-F@EkBo!r-O@GyXRB^262d|U!o5gLvKZI$8+?H}`N1c+a z8R!9%r!EtM&VooMUU8o53&Ow0Po27Jg&DVT@}lDq9m(vWy@Gc=p~B!;5%%5dq9E=a zKYaKmjx}CLMaP6)A<{yoXjo;O8}T9NhJp|+41wHPa6A+bVXU4F#e(Yle14HY!GcO{@$1pg~tI5Fe;0`G73c69R}En1!+j;M3xa6 z_(UUylaQI1AqYojwPD%RB0?EjISBiroVefHdlet=K_D~i3t(C*n;^oRy8Ica{mvY= zLyceTQ7NjI%vv*3#*t&Fz$p=h$@l^l*t#X|`;sj(fiPyn7MzC~_ZN3`bilU|Gr5>* zaOO^#e6RKM$#b=xr$Y{`c1NO-tdGmcCv3tK2`F_MIXCvPAA7C_0?YuUx3v?g;<5PQTWn5HxER zj&Pnh1)+jKKM)&D=Kz@um#_ipCapk-w`j_WNQ(m1?L2t!DP{nwH7z7I&uW7xl(AN; zGPeHQp&-rCfp_L@@_+&oKQ?G(YWatSRU&0Y<_0kb1b-|0FLd4bvEUBdx-+dVGi~?T z4~CMq7Bc7x%l9#bRc_0Z9Fw&tfph-)bcH+ANgrRSYZy?6DvQjnHCPA&bD^@=%h>D) z(#=2?I&0}y3k8|UnuFgW?l2K8A$$DTXe=prl8+bZeekw!IcV8QJe9nT@SYFQ$oVXG zdb_j4!!*u|HhxM$p%?*njEFU!YLd^;csh-2Dx`4aobziP`PJ-z;GAYg^iiAdvr0U= zL(OyH~>EC?AD)bUuLbll2eK=X0)u4W8~gcIwnR zM7M+&I#6PBSC$u?5xOh9Gx(X@L@gY6lmn=Oe4M3faFI0p$Yg5a9g|Kl{nu|I;0lmR zFS&gP*cF*SUWSd0jS-g{k}ma|Bx~n|;sY=q-eWjnWRU}bSi~E%7EzlpRBe4E5OCGH zx;w}ec+-uzX~=5I<{jo)eOpO;+Az|^Kqdp(YywY0l#&T-5NAOe4?KCKmg$D@2mBMV zzp%SZDU$}Y4GSYQkM{_e8`3_KMkJje^R^J5;L}r_RaO0fYATSGcn{S!q-P@;Dgj!% zIBd4~>cx!8%JLE!O@vx4wgB*<0tVgFKp$rT!DoYS-H%mABiB?vo=i=fb zA3t(kay;(KT7k}qG=3CQ-p&>&08-F)A_=iLhV6&?FZ^?#VTDaSeaR=GHK!D z4E(}O`15|o>SDrkH;AIbL$PTw%h->sxm^$!r~1aH6u*_u4V3T`|BnREXDf87`}b#f U7v+D%)40T`V~TP~M=sy`Uuv3#ga7~l literal 0 HcmV?d00001 diff --git a/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-14_03.png b/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-14_03.png new file mode 100644 index 0000000000000000000000000000000000000000..41504523cc86e0996f01a547ab0d016d4efb8b7c GIT binary patch literal 21541 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 literal 0 HcmV?d00001 diff --git a/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-14_04.png b/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-14_04.png new file mode 100644 index 0000000000000000000000000000000000000000..2e9743e1693a8e1dcc9ca62355bd73cba938b7e3 GIT binary patch literal 13809 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 WcgEIY*EXS`RhTdb)u?b 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%0Da5w>*s zL(#)5+I*z@>(_Go2lT(|Gp&hGSNZw_i`<70_K2O`9Nej0;*upxXmjTdZ|+%dVNnT7 zwz1T2FJ%Nq<#OOaJV1#^!6m4AO-)U9&M7(ThrWjX?NdoveMAxrJ~A#Y4%>1_11i_) zwcUJm=zneBQc#rU*hV)UOW7%i9>%`D%U~$|-HZikx^m@8XPicPI5-Tp`~tk?sddJ0 z+4i*-FDjq-r3cBt=%mu*K#h>MxA&nuzqdDcNTJM#@5Il~pJAt3ku5V#gp_5ryS&234V>J*yP^?cgh)YTm#{7>%D$!5tf{ zjy*!pUIok(2Mk0=;q`5Ia`EQu1i{q-ztA$&eQtn}f-E*JMkYZ)Rh1Vt8c|SCKt5)L zkAX!zdHE6x%0W4nc(d8(+7U_p*$n0U+jouFpAaH3o3ebBcFBYz79oQ5ssWM}mXKh= z^@kI@m2`)ibIzeLdV#-O&{d2#e^bheRrFj?iH1ZsH%B8v$vyP8G}^&%w^zyf!$1}R zE}!7f5BKVl70nNQkfSm3Fn-vr?d&4a@pi%=f}A)@-MO59`}Xa>7FcD=r+pgq+P9Ah z!cvHiw#In6;8#nLBHpDpYx)Q-$U}f4G;KxD@-sW1o?Kvo$|pj-ii!$K;W|6Y8R%yH zh7Cm_qX+qAbmzcMs)1_&~HM0u>U3I@q9X;WYG@+hr7JIyd-#7Rcy&N zPU27`<6e0B{6R2h8aedO>vlOJ0BEBX%@bSzGaSFCTWq}U&zXUu(g_(+d-3w6 z{Hdq&Ep201s&jZD*foWqK#m?g%1lUjJkVM584rE4DfHdt$E7 zIjJNMTnm6=0rCMg6An#wXri2<811-)#*wMvcMc`q@`!sNYF710CuS(Au#BSS!`T7lHi1Bn z_JkTj?v<9%C}OPe`v4fjt2+ z81w8*uLWHxDT%#fv^|VyT)?R$h(f%qwzjt3mZHl{9lEX;Jf%adsZqj}iH?Op35;Qp z^}W*JaArvSMr+TDO2oP%Z*XL+d*{bo>jz53`2JP^n{N!0rt`-SHC>V9w?y)M!d;0N z3=LXCWF#kaYS*FOM%ZXD*(|O-s;j#U*t--_E(Svzki-@%43^M=)@y`f4w@k90V<8y zp+Gf1K0Oe};?G6#Xft6h0UzfY*45T}zte>Li0J|+Ur|p_iU=a8M!GpvT*Y1T89f`) z^h-b1+dDWgHyTdOfu?s9sVH_1j^{r=(pw>EkQhXXUymTjP$Kkr5DL1a1@3(CnV(?S z=|!86=}9_&o*N_&nGRpQmB}j(4Ro-PyTVH%G>ineX1;F0LrOw>pLJ=9iiU;|WIE&- zE_&=Z3b1(kd1*}X8puK<`+@Y0%k<897$HoBp0 z0GD;}JrD$i`LAfu#O9wOF`Hqd6Kxn`378Kf#_}$mu5tP8I*QaPUI!NU7$R~x35K}g z{Dw~%YdDbCA;Bst9DFjyOSMII6wFkAlKUBmvb8}E-gBl9etrVm zON&>~%Eay@5CmI^-~$|AqKJQc{`6^I{{L6j<*YeFAzsl^gv?xlDnE*j zM`RsQQBgE3MjD(d$cuM9-$!6C$gMl8wrF@9E^5x=*jV)`x0BO^7isQ(HivX|4+jS2^S7dX&bY_oTcLj1YYr^%2Y z!9r+m0|NuXoq`w|z&&DA_B+TwB&*ShIWhJvuV88Dwg%z_*89GEj2v>TFhW1Z1*B`asq z>~#RG0V?dKwgT#^t0z3CPC1=a;#sq1P0QT_Qh!JL6aT>j3U?qBsyUVn5JR{M5*EUT zbI~&;EKicGAbLaPyLaM{3nPJ{dmZT6D!@Log=FV6swJC^W8sRtJB5a#rik;uS#X@M!B;3t$K(Xh0 z5%dt^Mh5-KW;)P4XtJ^ih*(u30omBtIAe3+TcRUBa=ps6UyLVLT(pSiU4e5Q=Hl=gqulB>TGW*1`hYv}*6U+T(4~7xxuGVB2 z)z)U9J(GKs6}6=xPMkf@JqAcrU1_9vR%w1N!P2Ji@vKR3w6?agzTS#Nn*2avNoWO~ zSyqcO?fKrTmEAeMX;xE(F)uLiTWrbGxB@ zeE1+mcqjB7lJ7;CG1t1V8QIm#>K`Ij2J!)&c%sJuA{zL?M!q+?!{yLzsPO*s39HnX zA~_rWogpN8^WSEO>KW`Q_#|sUOi+{GJkMGz;pOG+=&oT<@j?FOau}T zRaRyI4ruR;yb0uAje7yrH8rRdL~gbo>`@Aycf~daOP~mVj;>8IrMs40K%LTe+fFFK zO56Xrpkmq>*OIpsp-z7ndX8ng;aDp2>({UD0IRHX$x1wskqGkY!~>w*z3ta2H1QgT z+9KnGttU(TOjvZWqirEVkixu~*~K?_xn&Zh64=!(-Ac)iiE3IavN$qBiMj-HKBMp9ZDaxX%Vn9GKPh--|v4>;|8X3+Mz#iN%Xag^Xa$`lb{?J138ByN>vy<-G)c+a;FL?3Fl$4XKD-VpB@ITJHVi*nNE=F z28gg}FK5;kfEyZ|6`$d6_9R+Ck|^kv^lq#Ca}-uM8ZN2+;W1$Vgf;NT;HhQTbJKS} z16?AM^!DC{oo{b!l`sr_NPcRrF&zGi>A#B+y^RGtWT!x&lQ02E+BV(LIn{>gL>M8m z8l6yB&+GUo?0Ioso;<;EoA2D=_wKEH`0yb~kYl_95~LW0$s(j}yng)&-OIvfkR~Q1 zwYPU4fmnvfhL;}Pv;oG}8(nr`F|jDT4U+mNDh1XIwVi+_#y@Wv9p7sQ^8`q$fA9X3etw5j*L0+SL{^5F!+#xB3=L4v$g0}3U}PtG8EAP3lER`5-l8h z)G@f|I6l%au`D4WfqCM@7w$QoKzx#y{Auk5IEB0<>Mpoh8RV_W3D|L zu`!|)sR*L|0RueB*>sHzXd(q5s1Si%-OLTmcA&1mhk8h)b290n^I%`;V^>F^L}C)K ze!-Dk;TI8B+6hI2;3bT#C_$Ont+)3e{kWMyLUJZ*lxhp^b7{zk=MASaNvHy$p`qvX z0@YJeQf5}z;HuUsijSA~)q_B9&I1;g18!lyw) zO`t)7oGOS|?Zs(243FwN``?j##n{Az8-R>Q16kkk!Jf+?5M#d{^t*U@B|@V7++fI} zM+?flNsDGOuWRdWA`~bCvn!X&4@MJ?@Z{bd!7D35fuf5OI(L2RZRHgQS|f>|S;|C4 z>S+BOidB5*_fCA*mP2|7S^)@};$08}5C@-#R*m3y)oi)L6bDD@6q6+1`o1Vt;#845 z;1}%Wu+CEKR~Q<(vOUmQ{X+(O8qA@FBMf#7O7>+euGbMO1%<3wrBh0lA~IR}OJHY^ zc?osh_29wjXYU|cDIyM;-}(@a6K<1(k1y_?t`LG`cmMQiX&<+Wr*Qq9$OjgD8b5aq zWt5k{1Xui%p`}Pcb-eCeu^P=Odz;leL`0Aq*e?R~)=e&^0|M)p}G zqH?`cvaC?T|AzEe|!@{kpk9W$|J@ zob<_ZJIz<7K{3v#=Wp3T8yi0zpWcx7TT4~SQ0`^jItm5-pCg1Bmobl(bR*0@_iS1b zy1L+T!*$Qe!`gB^$Y9`9VZuMZ{MX^aaKS|j7aGAzaYZ5E%t19~8G@NvZtmHjYUt~b zE@Kn2e6UgeA1BdzEhKk0q#3}h#a`w^#TFj?q}!MrDY^2XG@L#FtfZu*3|-6*e^Q)C zcJ6z9RX}~meI<3JGqGIZ2|WL=>daDfPx%kH%DTKS8=~vK=i0>89V-#UqMJ7%w*#$K z82HiD*qEJU3gNdXs;HPVv|ZWR*}aKp-qLbfM^;+;L`KGZvIlX1OaiBQ&W8`#s!vJ2pjq_4N+(!*e#kcvt+F6*ff^qL00e-DM%Xzn;i}ES_VRcP>}upt zDqlC`Ll`OX|9-Y(*N{HWNM7Ih;?hbXyur!NsT9C&8XwO9m zz1rn(vu8-h`yj8Kef26iqX?Sx2*#c8oH>!m?rmjg$2b1(QcOh0u8XkY*Z}KHVJ5Iq zpx{TbuK?4zR9>t7Yj?~9x%^bf@dyMKxUI|@FecrAS7%adn4XZ{aRbZ#m)x@iwB!Z4 z7atcE7n2}*5jGigYnXZnJFx@?mW^XM61BrO>#mIraP=K zl3nDNTERcs-yVJ8!aU%V8M#v3Ao`#4!d(k+ghRn#=AeXyP!TymL52#N@sKbHl+OGS zEiEAG1sL@ABN5n0j`Ci zkgdD=(0~hx`eOc);2oh24L|XGc+qRndvRpxPj#2&NhMcoO?c@hI3fl2>NvUuVL;G# z$YB4~ULi!~_TZ3J$CodWLqiO5=n1B+^_?Tg;!=d0b@uh~piIeGPE69xKRXV=<34og z5OFq1r4ywx2%`N`?+zpQl0=i|78Klk;NIU`qYIRjTyXG*9ApJAB2$>EB>ca#^C(F> zL%v-Qx-NbBeldbK@n1f}qzLNUTmC=Jj;j0r&IxQkA`UN~3dg`Casm8QV?3nh;W2N@ z2)So+-V129`q3jUS|xWaNj90jr_?Bm6`A^gINc zuWn3FK;|z4tKtAwhWFoCek7!&wY7X;^zi%9*C?M3JU_56IYkJYU~%#RtS8COAe-Ry zx0J@SfYv8WHNnnWV0khdb)JKbVY_y1EOPm$FI>n8{sh*j$TfTRx|2$l*eItUab&~Y z1xm6+q_+vDYwUZTKY5abbDIm}Wev8SeBO;eYJw880Ap*Bfx!;^7W4A-5Kc$rrR8nE zck^^|vOM1GjuP)RxjP=*J&n{Le*5x*mieFI;WPMRJjWIEvUTS)oX_I7lnJJl;_z3U)=G$D8DJYG%?qyb`Y zIU@$K_YK>Ny-8R>( zWGKSf|Bn333%*I<-lsu9S$%H&C~SHmYDQ5(P#4IQ!fMZM-ZlaG@BHc`x}d>OT_X_D zP(&YxP+o%MB+jgN{Q8vu&DX87`Z(k_$Tp84+S`ZZpBpX@i%m!%(AC3Fs-v$v7T}N= z1;mI(zKGJ_@n;wdc_s8K*a)!Wdw-x z3a_@wXZpLl!AUB~!2&qZGqebP7*5DK1=TnGA!n6f_J(xtN72|{z)2;0E_?Sx*7)d3 zP0dBWTlXd+AOW4qL;OJ#P@2WbNFZ4vR0VgA145D6?DqADa2bDviDeH`V;qP69vg$C z-}@#<6hRE6ae(OfV6nQwGtPZCF*fD`_3|ID;9aJiL2!0(D9Mw2xTgV{Z})DT%>@NR zJV!SDvRS{nyX`&FfaQp0gCWjEsX3QRv5a(Jw@k5J~lk#uiIJpaXM2d(;#N>ox&PI)o zk0XL+d!a`)J~cJfL$(?qCi&dC(SnBG>)qQo%IGo(Jiyo57p$|ez}db=se2~b2c_BO zr(U*RNJL`f7+hgd5h)k~LZQ!RGhhZBofm^eXuF~IHV$gSf? zUv(r82~(g|=d`Nc!vrECF*!}5?cT%*7`tS7BKaE(aD2G=#RR&RTlcdwxjh)y;ZIMg z5Mdf$;!qK4K)HZRjv>iGR*vN1)6&v%M~R7~Xm%nTAwzN)8~M2AB>%1b-(O!7g2qoF zSvvIdgE+B4Q6V&7;>pRwBqj>RPg2Un;=>|WV_xprvqytJ(2x~`6r1$FIaJI8yVS4G zA@2*5cnZ8o2*{Bb@h-T@^ZG%{P)6izOS9J~u0l>DKi7A5?~wxuAkzyL6J(_>=Q37$ zSVdT7QI*(C{%nuWop{zLwK^6RE6i>oF z`OFa)H_5a{#+?(094<>0l4ths?#3{kjw@31Z3|(eg2F}{XBxpOnVg!^bg85oi$E^D pIf3CUgnYK)R&6Ly;B`L6HV25$SFakPbn*J2u_T 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 z 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 z z0;A8s*SSPkT&=0n5mJhZ&3gIPaP#PExkaD>JonR`Dp|%Tz>`G(dVfAwN*atlSab37 z7dv~22fsm(LpfK$+oX-^L2DooG1yz_AFzM`@*yTB2%-_h31??#O$RSOU8P!252!M& zhYK1T#o9jKa~u9pKHnZyyRv`&!dx@ULKn!T8Q?NdD;wO`d3K8mFH0@8QctS1mPozT z*Ur|kR~A<9Y|k;?maUX5ILB{O+zjENDY5Bc52))aF+2QxGx8B`GF8 z1dFqlg9e}ws)z1ho@G6MF&P{jOfM*S;#Xk5)bj?#tj5QO44WIFltpmViY7M0`CwHc zk#NR*vq3gkpLlg-+U}1)YR`O8xL|0}*V}9D=$I}MLII{ehyquOHhKZ3sYiRcglRT3 zQXdFeA(`lGuO1(4C`w3R6`KvFn+@g^z3y+TSUp-y%z&B%mz=}IZaXP1{-VQVNrcrfirLQ8btzH*g}tRg4}fF` zg702WjVyP>(-D7x3VbUot57O_JtR3#RGuBi8*L{;jUyg0p`C14z(cB*mTag-L_WSD z*G#R|=3>wDwB;|LxTA}Xgjr!IW%k+eC;&;*^e7(Tn|c`kF74uH7neMEa(q$w5)YU5 zVH_A^)(Q@IEytvyxx_^%Ok`x*NKUX&VlJvSYdNqAQ$<{6{9GH7+gf+D{F^q<8b@kwMT{EnrvtsBkCL|(3IIj2fI$3khf9zjnF8if( z6H-ORH$Xf8UiN{~;6cmnw5G>gkJzz3xn~_T){6e*x1!9+>u`vLj zCptPefsVZc4!_|-V~wZ_cnkmlFhFpGpea@4#V~q*-ozn}MOX z*h~%j8o@)r*6R`5X%rVHGjU6QzU>ogX@Y-EPhWqBL=^Y{_x)jGR?V^x@K}e~46da0 zJrpc9TlQC-L6=;?YiJ!tRVH%+(9VEL55U`{!1)o7p|>C(a5}E4n+X;U%fa%1#)VsS zbU#N5A3l7T00mP_xFRxE}yPm+1QS zpOjWr^+bw7y5oc3F8rpPh6Cn!J>VQry`!6()({Jt!L60R?gdB}JX9$_2H7JALI9^} zZrO!`a}Qwtbs8FlC^junfIV((< zYWB+qlPAC?G4k_A1AmDI-5oTjmn1_=4$Kr#)NTG2)@DlUNOXx5kP6(X-I0L8$g zWNRL)3EVof-0EMTnIA5tgn3sjyAEb+Nc!TCfU$ysj_xhU?gVOTYNTwMQjk!<)X~`4 z8ItIEd<8xP&@2XI8nu9Z(u+bP1gc#ZfXEEE?ZJ)dJnc*N1sppy-CS_T`x}$p;Qg_& zw>MZHD}PVU`4)Ixt$hzMNl7AVYI#_V`T6tGrYuwO#deY_(JxnF;4rb+ab z2nG}z$o=z&TDf6i1W?52E%&C4d0m`!#5@Q#PV^x4hNRD_*LWFl6$&E4DIxQjp;>QK zAHaQJ&UF&>fP~Rr!2Y7(9Z+u228}j{*Xni;`ahFFcL(2AKG^@D#B(jwj@42|(=oQ~ zGA>%h0C^ssIr4$IYKAwXGe1SgoHVmC_;h!7mna;V;A zNQkHe1(DVT1oRg*?)>1jH0@2z>gqY@UUtRCqi6)x4S1HDw{E>*)7t(;0I=ac4Gm4> zuV0|Dh;=6jw{~)A45?V7#5ZRVI3TIiB1zP%>t`dVKl;DP=F-%#*G`R!-b3A z`CWIH>LHRi?{xA)2T$VOxhw2ID4tNW3Bm}>L9|shaO(fMMnMr29DFr2G*swhwGg&^%Sbu^3)FI8OmqiuLH zu#yHlEKPp-LS9f%P=?H@{9!!L$;tUASNkI92K3m2v55dB^MR69SR-Q8K~Cc`M`+ZY zATKJ4fY{Jp`U=2`^HQ=upX)9Y>{z%IvcLk&Hw`G<42TTfg_;5$tr#G^oG$<|Jg0$h z*N0uA#>(V*yv&GlwE%?V#Pxw$-r8!WB_bhl2(cRWG!d9mzF$1Mx2jnffK`jTz}tOd zx_@X7v;=ehed;`qKKnZ56+R1h6d_Y<$%)D|bkNOMr*K;1a%Zo=iBPSa=vB=l6pa1n zbAy~4VND!Q&k`0bsKtRngC<&{eKd-_N^~LWV z=7R+pNqiR}Q=a0#|C?!z(Xo<;F7K(?UwQ;QbfU~o2E!VBF}NlVdjHmbm!6_21;sxM z7aLkOq_W0I_nh-UjiHoDP%svz8J1)wSYnftlRFZGM=MTIV3?QMQhKY6C0EnoV}jYe zNK8uu~xROU4e6ep46Kh*Gv z-}l5Uoj_!|&B7841g#Q8Kq%>!M~Yd1{s!Powp`O`WEU9s-08pPrak1KG59Z4f2fDU z8wMyIycUCtT)BKXPiyLW>QE@o*47pn6|X}i2gs2lFtGdIUw~lO-oE;3)KXp4YXDi?<@vO;Vz?Mr`}qdCEv;OXg!vO2w|791GqGUw^5_3{Ft5Z-iglZ~yb z!V}!ICPR6*U~=FBSS^%R7bu_w--hJ<8zgFgif^jk>Vu7`$Z|Xerewl-77ui@E65r! ztBQWQ`wZN=#FdU~C|wQMe-$93z__#LeiRWAVG4>h2yMymJ_T5t3qgr?r-xgpJPA1u zsM?>f%x#(+AZI*Au^Kb&deXFT7Ua>T!S6 z%ckdD;*yfw=0h9+4O+g62czmXs4H3r|Kn8;|4E^S-1!ToQ1`X3_D`T{a{E9JJjtny zWI1um@za_Qu4N`AT1N`bOTlJ5fgvGxn3$L*<-Adf%Ku9aR4Ci|Kjc8fP>BU4)Nm=F z4?)-@A|$MbBG(_>#DGdtp~`}{XUr@t{8AJ-dj}svj;Dh}j!!M1o`LZS9Qa_bZESB3 zM%7C{ud;K1L)$&k5Z+m_I$4_-LdiR`wA2FS!VTzP060~-dJ+&C${-*R10G#~K}V2; zLEZmeO7uMYr8rEie9VyJ^X8AK>NyA~H}as4Jl;cMi{`$nMkQ$Q1!-48Soj}pj~XwH z!q~LrG8ASOshT75a>U(UD2d6CqOzgz765YVnZ_&dbWF!99zZf@zBuakI)u=YshW8m zA^VwCccRJ#RumyA>94n#SNYrzb006BpKPEcGtr3`_7JMnE9{vO;Lt<0HegPH#}D@g z*E`T5z|{Q<)`@QQG2%axC@KZ1!%H*_hoe|u`~;kfTFp?JLw@jwd&=@00K!cPfJ|Im z9BS^NFjg}!g^Gm6WA|yz>9#DgpNKh~#3!tG;pz8yL&25)Q!JLYF5v)lprg@K}L&;BwhEnDDyr_{^>y3f;Rg_X7d$Y1y2CabeL-*rewsypjS~ z=}Uk)?U#Eoy#eFRPES7qd>ZMqRf1VHS+|riXHrSb@+xE+6eNYhp3`Yv6Y5ZK7SN%{1aKS{mB>O8 zhcd6oV)XNWN!^U_!WO8w`-)6e=;-OufSkbwk~S4$MdUq=&+p&k;?q8K?_c(IgA5J; zxgIQo(!e19V06sP%>0wBK?a^!6x0I_$aMTTH(wGat*bSH5m+;Uz6{0MncZq2I;J4O zr8sR&sAekrg2@63Pmf{yI)Lh+6r;cx;DbkiI-p!If;#(X1dKCbZtLa#5axb^RU-Ce zMmArM`Cpx`WyNHfy5zU-+<{(z*xY#FaX?5bs!@=WD=H};HoUn1*DQaEjCO{`UyXD3 zd75ZN<^42`2?gEns-4)S1@pP638MtMT({#3Clrr>1>b_N3)PJSeb5CZncB4vQ7gTb zF%bsni+Pn)hbvkg-Y)|wprNS=Gq~v|Fe-?Ez`$FOS1Q*l+FhU15E0q+qu2HKe}c`n z2|KIMYVslSME}?O>2OIJU0@!d_V3Bjs&q%f&Ikg-ZUA)tUMD7Q1U$tyx(^%!Ks{qr z6ZVI}WE+U*Q6vbjV}J+F08PI@j3K!i1c>D$RPcIwdI5p0v6y>nrIYEX27!~Hwcw|6 zC_t;0OjcEc+iHb*k) zVGJH0MS&8UFN_7bzl%Q&Y%GGO9_W{00g2?i6ZE8_yYdasNHIM`2Gchdk9VoHVrvpV zDwe|g6#mm|m69SU_-#|O=_5_xJo1y>d&`0qJRab?K88kCc*m6%+JAZDlDG10Zte&g zVb_1vipxX!^bl`KLZ8uf#_U-`nMX;0kSyu{O=l;e&q*SaX@v^5JFI>+;Mg25yYe$Tm}Kz z^q=?u`MU!V2}Nzkz*Cu20BJNZ3h+S=6`PUGHiwluq+V~}z=aVs!-@_F4xRj4HC zz?uc+_jm9FQQ1a1f?;}P1t^C*T|hNP!wU_ps*2u%Ej5WwfK$df5flX)vmw-qfm;2c)>dqD)rd>Uxl1|Jk@y`$4{9_qMN1}F=b~B zy`)AWjFM(5ib8f9HRz^U6VXd@ZN-e;bRp4o6*a}`LPUyOMkCa^&I@NEIvPrK6goJi zuwyVNSA=XYx^ z{&ACFuKZd~P@Q}0oot${zS@VO?B$C}<0nlyGdaovSAkn~h&4Amqt*XjEM-~)QU7jz zK(_z9R|{sksUA9O;@4uyx~jf7rA(OrxeNuwLbH|qzHiJ=3YF@-Yvv3g0nr@`3W@PJ zXZkF+ik#1LnyPqd%`Y1wRsmKZdex!6x|(ym5LcTfmbz4OG~4GkU5*n#z`nO zRgix40+(YCAJvGMahLC?E@qJg2|fjG(cJN?Y{6`UP8n`fEqS+qz<}Kh<##%|%``U} ziX~_4L+DW|-yxTs6{r^3{@Do^V22kD_0{7qDkXf6EQy|A64JBL@${nDs3;ZVqCQRP ze|BKHrYCMSv3W{WRdx1Xit2Xl1X)LAqjCDcw~mhq}N zbrW`#1g@#A?JduHVIlT}aQyv7y*=H+gZ^JP*tuMM6MkwSAfRi0F}x{4{3gY z7j27JL_tAH{UU0NG+fs@?1M-eho3KdEa1mQWD`u+YTELMFfr5<5@JcYZ)afs`lA(2 zPMx@C&j7XHllPM# z2fpy<-m;HehiVw9apZZ9Rae(DGwa(Q<&=xbOyA*{xQ1?ariaqaoV^ zgG0QXnD@;%xWE+VqTwbz20qUmczu;ItL9uEJ0_>MHk_XfcB?u*2N{gu6{gI_?p3$` zt`YC@-rVw-X`Yxn-xg~3{A_=AsE|kX^!3Y{pI2MR%-EMVzI1NP&}*ema&mGxyVuy0 z7}M3Yt(~qy`Yg%P|EG|)?^I*xKeTw@SVDy-kdqrjF^=JhqmGGl<${eTr2QrL5f^?JUQ8qPbzGmdt+ng z^GOBbX$O*;@NXK;Z$+xHWw@yrC2o7+rozFem!!{%`MVr`^0Rv~vdj1qfLuJ6(u=al zR=%6khmrA#iQeHJx!!B!-Cr;f9D~}~JQ&*A(h~E_`d!srD?)n?tMTHuFK`_Uw_mkt zJ{O*T`V}x>Ph4D_KS{^u8m#(;-U3ZS!<`=X_DT4-ByHW@PGss=#CNYk;YmkG$9%l1 zYUMmr(~O+!8SeQB5UOIR4@*wcg|%1C2JV6hFy`oY0@|ytpQa7{h^|^ft+a*f%cy*w z-#J6x73w2R7efUN>FcIMinjCVrA#dG>I^!j1f~y(764jmM?gUS&L^6BwlOdXBA-#3 z_8mBIjuR;i=POTHPG+(a;#WjZdO*eopQ4CClF#zx%d;H)R6?&Ck=kG4=6ej`g&}M4 z{X>~tPQkCi_nBfAq?c%BpySjgOelU-`&js+$m~)#J;GEXI1ZrdhsNtQ76%0lta&{> zFF$|Xk09ui0X=OueV!}2-|B|oGittQ4kV(?!oBW56P3GbbEjYQ^t9Feuw>`6=J~Q9 zWw$I2+a$OT$8q-_#ooK$GiuaN=f;O>7ZM#OO;m?ehvUMm(ONeM8z(e}h5Zd!ARjai zDAK@1GUo!H|Hz^~H&@S2-lQd}E;Ppmi`v{B#_J1D(Es-;YHb+aQT8xWUN0s){1o<~ zSOk`e6*~8%jg5_ocYwcNJ9|9ox3T&0Y}ue7Bq@>DX;mpds70mY<3ss9`3*z zEcva|WHEtCByFacp{n-vSRqz$>i#4U4A4luFxJN7iPDg^93Od(cjGLd0@!-y4Y!Bc z{Jw0Jt0bl2PIYxEHO;*+Bpyz15`2eP!^D8jd5;2fP++RKJqJVJ4e-k!hWU*@d^n0` zPuvmOOQ|oCfBg|7*Ms1Tb!q?bZM-;@f^+(SKBXS~x*r%(r-X)gvA71tPAcl=A|TN4g!#u567MDHfUlsm7lH z-1_?Zu)4xTVNQw|QAUVHwyR6fkuN#kAijS!r$M^te~_7(`9(&)BXqS}=zGN=2O*Zb zSU#dq3@MaqFRTtOQdF6W5d~@@z%?W3<7IxTiQ}C+41`38jpZP)a^%=GQ_L^NX0LN; zQ?YY&oWL{=N87*m*JUC$ggsea7v4f+ztqn6BCmj>bdow2|J4Y^hdh7r320B{@ zQ+g6vm|5^8h<4)Yju6OO*_Q{DuWJ}71Y)luA^cg{E$wj8)eUp=s{Qmh|61~Ol&Cng zdDQDH*UxAhAs?uyK72br9f&}!-8*oS@ATRGD{fOuXp7i}cLV+ieu&9s!`4n0VtN{2FgW&)F;s15PjPhL| z7S%O1U4w%%hYVm1ogj^kjmj!2MTDZE40o{YgM;B=VQ*_Y!FrBDxw*R+5(?1qDjl+NCa(+3%85Q`gtm zzXt>a%w^S3y=>qbQ(i%Vp{;FXaWOSsxagssFtt2pKyx$C*!Vai0)jkunhM#=25Z5k z%ZfQWvzC>WB_;QXnVN3x?fnaQgFUkAlz!(Ru-YrqR83B3dNFvm<(qOmZ(>Yi;L?m zHM>h^^0h1_#l>M}cwecz94$yFDx%NM&eEt?<<1&=-(ML&KRps~I{2^mM#jd*b_Npr z%p7=t%Tkxg!vS;`VCZ*8Or)RlUwiz4*8(KRR3l8}%z->ii?uT5Ljh7oYaEVXzt>vzDOot@!%rQ5dN zl0V*El2TEH*su3QCnQX*G<1hzV_;+Vj?3{6?oAd42L-+7=g<5K1AjJanhAx9i7C9? z>YevvJsZmtyGDanyUB&Mxe_lNj+i*pBR+0-clYM*4v*;m_BJ{rW9fj&Z(>5(=Jzgn zOl&MJzYmY&)<9#)rSN{}^P{JrZ)-a5=SVcy-fD|LQsLs%MhAX#cjMA3Yh6|Rge8pm zjik;%6bu}kpyFc7^lkXJIDRU{WbEwNem6I6OYYl*e2*7Otq*5X`LgLR8}9!6c-?r~ zgYUjqSO96TTZM+$HlM=P)zux$*Q5A7KWy_4Wb$XC@ZCWCzQdzbSx(a(93GBZ)Pkiy zpVG9|H#hH7)%ETULL;?vbnN{1FQinn-oV^k!rh${gp1L|&S+P6H&lh=wrm6;_m6@C z3UD*4g#{T!u3Ijbdy{E=-YJVst{_JKnPz(Tq;WdV)R-%^TpL~;%noGmruz9okcs&Q z;EBEbvMC*k+7Jng5JrZFBXh(eW8&jQjE%{3eIGC1*&6=&_6j5zTpvkENevRkb)~vv zB?!&Xp(-ajNmu6W?JaIuupBrCB_%Xq{e=RNH`gQiw~|dWR<|>Kd;0ni{gCk4Dl8_c zga#*5SS`gRBp9uZ!TohFEfGO%ZEZi0lFl~RlR~IfN>-LUk6-<4ZcYO+icUl%tEEL? zZf^dg8U+Gkt9N`H!%w~1q|&%Q!K2a^9AR3`I#fbJ8DU}A^0p_BSluHgCMG*q*WQ7F zFtDKLgoNIgwrOZ)mCTT(r6nU16GbJZ@5#xyA=yzG84;0@a_RPbe0(1%DDa62^7HX} zSZWW34-O8JxSXk;ACG;Lxt#Zm%i$SZkF>Ui(k&b#)3yKmoWgscedG``MB+w&$jK6 zZQ1vkHzfN6+^zkh^E7KiYkInNdM~rdfZpxdCfNSixVWwc`*n!h-EP6|Sl*jJ6yhFm zQ>nJC$sr*<^k{5Ot^wJUJeLzn11YSNWjF5n&8!x{jXSdkk`Ey{QuQ zxcFUqk=*?Jvti$-SkuhMW#a}AY<0HF$UFOaJUl!nXJ;Q68PQNsP>x#fZFGDeoxw?j zY0s62Rco-z(oZ!uHV$7JbvA!^dc1evj8{!!vrbuMvh(rb)6vmMN=~-FyD$goQp>aj ztYgN(ffXcyPWvB7p7;w_*&?BD6DdG);`F+)Yq1CW{gRRQ%iA)(6suJFJbJ9Ht#SA~ zG!Q(bj%3H9hGNs3++FN8Kb-Y*aBx(3-8w)_hSK`Ff-#ag>_0p`J@Gt0oWI3mLGWAc z3}p7avhpKOw4SdE2gwmzNlD4V!UB|#xYfw!La;8(&+Aeam>3aGng9G8GqZUs@q7PZ zOd?AK$sU8GW&HGT3zDayzW&$3!cUR>PaI&M8Nv{ekc_)S-tnCMB~?>Xt1ubF14-O+ zy381C4|w6{_^w)w85-n#YcQv(Dh8|werx=2DtqL}$OxQaMNN&-zqn6cH>-hZJnmyB z4-dEJjr(OyYK;zLyq;G^8-Jsnr|_AK5L_4R;Z27#$QT%+-chSe%wMIuE=lO<5Rr<8 zK`vf}gDZK@#8mZ1&F6L#d&y&;mhb+c8V=(n(KrnAUdt;h`)5;@Xg4LG@IOQaV}zfd zOXfIT$-)o5Y$YkF&>;g?$+@~l8sDB!v&>r)p{Fc**tc$R4d%n_ZB?j*;?~x*h=_== zuU_d}SQNQ%WWQs*v|UV&zy+B`zJ_07Ud14PRDqD~Ri?bRbGiE!V|)%esG9_hxQbdB z(;Js@lvDoU4TRMA+%+jS4T<6;KT!p1Tpi#9v}$XV0uf4N*8I;AN~|v8|IE6yoT>~d zXt{mf+yP*TMFbsUKRI+baZOMk+|qfX74FFanZxk>5-fp0(zO{4E1>mG+nSbl$mRpS zs^FRp1CQ-ADV$$6^BAf)0?8b+1f=T=XX7;mPv55W^l8#Vq2v^|5d>nQh(PI&dYJMN zvQ`v#G|ld{$90jxHO&3H!CrR#Ybqx6YZBomazwudgLlScu(~s%G3Ig)-wgL?hpP?) zT&>}Z$pWZ^Df~}=fw%&=0u~k)m4HCn&5eUvwTy*kxzbQ9eb;V2bUVYdY*fM{MZ<-2 zD2>xF>3#)d%gvE2p&!P_t@m`GID_*vULZ#-w5?%CRu2_Ijn%eJoz1%0b-yeu0Mk#s z*unVeHvR&`b9b?P)n`pG$dcXr&WVben$zQg64W0MqYjUk)8HU?dS5S27u~nA97}mt zyPungMiR+@O#}I+EEW>*My%Xexi0^Q46^|Ev>(UgPS*}>u-s8l79W76ciM6JMG5a?<$|Pz~yxK z*y4F@(&3M|vAM~5!?o;nE^~LeF9x8F6Q~GJR4ei&Zhu&_08t z18VF>^)Mfd-o!5j4lXX}yIU9@US3e2Rqv);@eb*|F%IVf(yILvj!2idQur3V@Cn9w zIgsnVn_rExMaTxR)p$^C6tM6gS#VtYar4EZVMID_X zP>XPRJy`7R?;^6eU5_?qDh=H{JeW*}2r@kOJ|)noD{j}8=(MDO6IShcZ6hrsb9+!d zoWyL3oXTchbnWwk9cHUdF;G$4!42K6d`FST%p2`T)U2~20my7d&DqphITpl7$VZ#| zxTh42B0(E#r?5~@_NpDh#1EffF$JxCe0+Xbt|{e9>w~&sR;%#?neZP#4YB|*cK$$O zmd>cw?}P*8OugQQ@Mk&m$@w|+|G*3*zM&CeVMbu{7CiP#OVldA^%DCM_??|OYz-uL zMw5y$Ffx8Fo^$}{RS25F=fMr^8dMUiB^LX#mt)HeyVXoPNTjF^qF#%u$zbY^iHfdg=cF6Y$6n2A zDx{=lbV9_;Rx;nh_pl5N3;PI;a&vPtmnoFX@ltqwJ-dyK4N_UbsM&}ai*yE0G61br zAjp<{pS_oS?yXy&pFA-|R$H!@)_?Egl`U6R7vDdhhv71-wR&-ajr>SP#%Qy^0m<;W zGymVTCbmrfGU*C)x#%L9#4 zR8-W<9)TY17c<#OFa|{ffTOn{ws3gd>|*B+4{|{+WwTyW@R&>^UoyvGbBU0ND7Aaj zE1g67n9Bl-p3Mpi2loOkOa@a#)YWkzg@uI==b6te((yjKjfeB~FcmI`8vpNVdslBS zJ6GOugCLcm@(nDwzti+5exNm3(P7h!oB-v$d z^RbTrnHV+jC}?XBg8SJIKfk)#`WsEE1psP^Ms3LD{`53DfY$nbYtMRcD#L1H5e~i05-^L&! ziUOaRTFN{O0+?Y!%fI|YD~VK`aOZ^4@D_k`gJi;A-0fCTZ-p=sOF z4IurLp5Q6CEO|Axzs>IFN$j>nkn)x*Jj31y>jT=O36_v-N(=a`{2`WlM@vN~E~e*k zeC9m7>D%BWHphE88x<~_(2m(-o{X8ca+@5=05e{hK{R@<#QdjH?r}yTI;fz22ajj0 z-=AjFPMce2zw`U07NBr8tk4Abfg()@7#=#QRX*=tn)=VKx>sD=C7!EFv699j>Xrdy zfHR;1Z%Fx~t{{5cOq-i@Gs?_!R5eX~jQ%4aKjA_NUXzgv5Jjp&=#bG8j5ea)q^rqs-ua@G#?!V>G@IU^(8w z-oZqAB0X-&p8O5p`-e`RDUb9gqXe(+znOa9%`HlLokmWrLpzPI;9x}16#uwC;=cd$ zN9|LHAOJz&g`^~>qvO9IzRBNh8DnVt4sM$svo*W)r! zNqK5#CO)p%g_3rtw>R+O!l~1HH`|ekoxQiWSL~2MBmE;JTcV(DPxDy?cG;nO-$GiN z!}6WD-K~C6F%@Hdg;fB8h-Vf3CNzJKDb&vvd07?xR~Zp1RAQ43G&D2_2nYfN<9&I4 zvXVKYPItCXiQ-`WHj-{w0p9*YdfZ%e*{{`E${(>g2F*W0hD-Hepq%d%mC?#SRFjnlp?DCXagGxtx_^Z@X~p9@f| zd!_n5_IcBoY+;|qEp+x^~bj1qt?hL zI}U9+7=%$GaPIJw8^o6H>igf-JXuQ@I#N!hP%)wB5et~s*hxX>eW~Sf_h!H{dA=79 zK6QlBYny=jZ|8Zhu&Cty&Vz}fO!F=--$_cn=_=tX0h^8`%cTS}UG%EZTQ6O%#|JGO z{5=Izbu)JOk^vbGN@s{*jTAUS9 zzwbNuFtf9gbj$~L?!Ho<-ct^dM;OJCfC%&c&as5-FdBG-T9v2j+J;ngGxE2J)KSa@ z>Y_W`l942~iMSL*CMtb5GMf7Rz+n=RFh;U{OcTK7mLkGgs_v`2QrWt=a?i7UQH)zqOKt7U_Guf>OeEaq-C_J2uuXQ!M9MA!1I5^_N8N7|pPxpmoWi~Feb=LDc zfT03hlRp5lT^MqppP~*0fR~Y#74*j)C$VX13o-PAl(~m$$bP%5;GBdd`r?pyYMhnR8(}k znl+tmbfl1wkT5betv2e5F-hd)=03mO&U9SsLPRFw`3qXsA%HI}X3APxc*P-IhM!T_5WvfP~FJrBWQ0SYU=8MzWWRsS*ZZq z3qTKch`A;R*Y7icJQeSa$r)%+{%Kn)WZ=yR8eu=>%6_LQF5X5@#ryhxo$}%w*2VOa zS$aVE9!iFiK{QGe%CwsdO!C{ve~p@*oSu^K^0o{$fDGy7{X9*-Fg!fWkY8x*n-Cx0 zJy&b_LWv;_$0sD9BKc2lr$0G>qHb96NX5*iYc#Gnr?$8!qH$jAtBI-HBIHXW|= zefFudn(Y`$=XT#Ot;f^y{hw&8Ii?4f!rw(PKNm7bEPkWmFy>BPtxriUqg7~l{+hfZ z(dZqfsG3c5_&RUky|ZcV+r2NQTLQz8ME(-%*t7`{H&4&lIWrMu%kKryX^T&CdV?Vw)s)QNsC@Bb`#Fy|0)mHxC(tuAOMzkl{a$lmcpquY- z@xQ1Ysz(|Jfb={2`$PTw{J7Tt_w0^}qGAW2mvGo^2ml}{uO3WGBj{X&j*pM`0&O9{ z8Fdp<`xh3-zQ}&ZLAa&AiItd{$7ns)w3Gd^W0y_{yNh_ubGPCdO@$#gSE{PS=o>bX zE%C`OX*8l{XSxM2w$*N@1|Ue?Uij`-Enm&qfn?_Yuzdd~w-N*hNYI>skaDT+f1yvW z4(EHPb$zWHCXe$Hb)fa8%e29@jDf}wz}=IJiw(djn)fA6nZLuJ{^ zK9BhF`F~gONoJTV-nN$2-YKb?Q6@)`sv_B#&~=9QigYKP#Oh&4mp^q;60v6U;~PJ% zE)sG^B}B@aPN)(Em|=f}Vo(f`6`P(w!qgMnsYpn_tLMCpAmLCF9#T&(&*B~1#nhQ| zf_79wlGE|sl<`eL-`^Ir7ePYg>;@^Eq$@rawq2ZzcsV?iE`7W#r?R5PV%$5`DHO7@ zAhC-uLuAe45s`x%u<&kMERwE{_P2F1j(E@&K!K#rPX_zCy$wxsUdwb}?+U+CkE7Jx zwu+2X6JzGc|d5kxUV1b@kb4?C^Z+wKZNX&fV#&fV2B zVkM~LCf}}p$$<1M{>awuqb=L$Je0U;oU>C+vpuKQ%2VUV9>R)qEc@9EQiQ)*#z%cPT0wKFRzw>1CK@==&gVh9B$zlulv%4j=q}nAhp|A@W)NJi2*!I71 zSlFnF4Y5ilf81XA7h(sQ>OzJx7D{#AcDyHPN*cb-8y_AHsLaYJ{Z0R$wfPLL)X`wy zw{lcj5yz>z$e!cX&Ks!yaU+YBs}%tLMn5q;_vo>tSlZr=V-jQIFC5Tr%0ft#0S^^j z$<>%Z)g7lpI-h@OYv}bor%*+@lFL_Xk^}Z3C90nuu~9l?N0gYpKxH{oG>2qrIC)%M z1oMk>{oRv4DiYYrpp6VEvfMR>(>i+&XYuFRFX5dtlY1}60bPn2 zgNS&#Y48gFaQ~a^R{(FU>*Pp;wPPSS(HqwNjFXg<-ub@>Uqi4DJlBU_(HU7zB6pj4 zy9@O19vGM)?|ycr*k_wB2MHvL4;I z>oqrtMnj3pOs>-O2Q-6oPRl0w@lE*`{SYZ9 z&JS2!8pk};ic$awO#8}B5zZhsT3A|~4Bvfq z#B=rN4pZSKfWg=FtjS+;lO)kg^*k>a2knEKi5G%N{+`#{E^$IX)S?*Jc7(JWZ;T_Y z_oesYNl7V1gtCN_ONVA*_ApI%oF)%e36=#P>&fUuS zn+6C}P6-HCA;Q!rn?#8VK1Z5I0ype9?ogac>r|_J!!>JZn2i zdZq)K$EXyC5{n2!P({Vi{bcEU<}IvP-)+GEng@ZyNAfuG36I7hqL5IsK=n(`di=4R zfu;Vx1;)=7fiOF!aIi)mdL+v45d|nr(VpK;hJ5-;RSy7HdJD#G{^BVmZ=MTf`qF=^ zDW@wZ84a_VMTE#F1%mA?g&=B5C7?%w(}yJ~Y91h`Y?TcSuBzN=qMLJ9`Aso03ZKj7 zvYa$t8GmW6W{tLqP#GXtD|g|5BSKbjYf|gS1%V(>5A`255XoYPbM%SKS~Iv%G>fg- z+v&+tIy|tI?el#gNRA2Dbz}-^I)m%$9{R>htw*rIm(HsLx8Sao|8v`UI?yMV)4J36 z6C;kclf&oY-5;L8;4W*tKVjdjM$+{B@EBQM{&HxCH!(hl zOo8u+oZAQ1YA$B=ZF_}&Ck~qxPAs_$(0#95+Zr0Ye$Q!mq}^xGEFeVS7r1aFlFiq# zGm_0y(*E`<{T@2E>hzi`y+bNhR?j4RwQqmY8e}3245U%Mp@*0#Dfch5Q&@+^qMw6? zigb|tLPOuMFS(Hd^a**9Xn;MS&RJ^>FKywRG$V~7ZyxEe4CJb!#ZD-3ei9{^`Z(Lj z^mQ{)5?7Ry95HOo+D>!Du*^5CTmhtW(6vHn9cB|!|IzD#ZiQ6J+1b%?1Nf~u9tQhM z$?J0HpYu_k$`Ko9vsWW>NLo%NZU3U3kYD=OtIq%QuSUv#bE_=WD&%nJ*@Kf(5C;bb zAUolali!H|N-!z8_E2keZSPB5JZf57`p5B%8#u9I!Xe{x#9)|q7ELbbI)CFPMGjT9 zKb@p7c2$+Y3Sko9$!VZ((&6)Rb_c=54GawINe@J4(qlL~eLUrEZP!s6y3O!a;*O(U z+t?dY4~MtuRzz?sbqJ-tH4|gu>hv65S7Q zKk>&8q1TyWj1-sY&xV&%4YvgI?`7n+(5AX@2*9lLwA*x$EtSfXLpHc5Fci5 z>OabZ{24oa-P2LB&T=1i>X_9~^?&CujhIFWQ zJ<)sfuNlDPJUIHJWuN=Q1@N#Y3~dla)Ko<;D9q!!P^lGaq+;_Kjd~r>cTeIH2F?!$ zI6rNzw=jO&}7#ei8{zu+4b;D4Cn` z9#F2`x9DSopAYTIl48SOeI{~opzuSr&IM={sP%x~-2sjjC@3fbE~lV3*mNgHO~+>! z<8thcm0-`9EvIPE(a~RsI>4=$vy+pN1ppc^A)VVbCN56c#f42Ofd&{js;ikZeV;ff zWYb=_{RcpXdI2365*HU|2QIl1FyrVL7`s!Y_|Lb)zGas!yYgcg5vaj3Dd(a@t1{A1{;BT03|x9V4$VDp6wROz8O+|NF? zJwI^|^PIm0R47Z6%i$UT><{45fmI}H6lrr~!)~P=Dqm*2J|msSoe8vjxw*Mq>r-Xg z{XjH5y|@t089ix-K>b(+LqKC}p+_<&(2~;)l7;)z?Y8^Hs2CIu(8R#$?3$Q}Blfug z+w1P>iQnq1Ye63Oe`AdJpIh0<V|L#^ zz3~%+w|JaSIwFD5qcCI2Lp^b@;>zedVs@7fzsxVMAKxthMJfN~tl;}~Ch`Wje3UI; z4Hc!)n>y)%KSSEj>qO8lHc^hR*QSLgct_69FgU|Sg+S6@CLYeMDETdPi8OLx7kE#EjEasb*keA~qD1^L-SM1d{)Jhd*C%99~^r z{R7Mbz~o_3-47fsFHJCzk_>@L?_9?T0B4f89KkU)oh;MK z#2J?{9JF+#dQ*l#LYGJa<+d7tokDO^?)z9g8&0d!oCFLR=V$%&>nkhmXPf;{Nt}-4 z7!6?sO%5tW>uQMmxWaasPf|+i_HMr%%6q!QG{YSZ zNQN&C3Lwe+Dl8-cvMM;UI=h~uBHt+5ikCCJ$ zg#DR<80SoG<_Y~k^DPW<>%kYphYM#2{1_eJxrM36D6#P$`GM#HF)}i$aNbuTmrV;2 z&Cv&26Nbkc0#w;zJTuGF|86@dn_HbOFOb`{p&Q`)rpe9^f&{H8@hKJxS4tw~f)EN# zXac!Fn=4kc1Ly!`Ba0cf#6)4cd6v)n#C|!J?_J2QZWwpcqq@G=2vGBM)}ANu4E5ja%l9mi*w}sHPSKf_Fg|#vaTL-1 ztje!@2ZPzsFnKS`;d(@{_}dxiDs#2ez~o^){PSqG*UHo1|rs%h1U^R}?UyzFWIDHmm5H&#_@gaZKwrnl9vW|`iz7DpGG%F^k< ze(HwHw`$yBuMeMtzkM)mNf;nIJbzzj=+&m$UXfLsQ zm?L}?-Y-ssyhypR6msZ*mjsrs0@-u}V348mCr^oqzJPDBly&H^N2t4!wFn%~W+5j} zt9{*7&lQkTBndWO73$R->3jTBpRR6Tm^Z@;2?9=@jUSTzVPPcgJqN+f zMwLqNiG9a}aOYQ+UBIAP7A8V~_nKDF6L?f{ z$bXmJZZe~mgf=z!6{ZloL9Kws-%S7V4x*K!w_Oe_P)8~#qFO{E1)bdMnnUZte}5u^ zTce_B$yqsYI77c4CzYo91EsUz^z9!W;jrA>?u7~1f9ID4PlF{Z33BZvrz(p@)fEBz zI{vlS9aGqPYfXb?=!g3qqhW$Ej#7wr^_DKpsB8Z~(QJLZ((F8b_wF6=34}H@a7aMr zqQ~LuM>YElB6|u10MB{Ud6hzniGJbU%m`7f0 zD;(V1#b~K!!mAm>5Ig({_t>hkC8!O<$Q(>)MbItYhM%gXrk-8g=sm`YJr`5+o zbNyZZDhk8i426er^JG7=n?gY3U5RSfHt^=XaIx7{&k7N*2P!e~GFD|!zx)^V&*ea5 zOu1Ph#sck0si>jBw<#us%p&HADdl3qh$6mQ+5qNlDR(m?2w<*Py<%Fkm$JB}-3lHT z&RjVczGppKad^sScCoNdEWPGe#YfKXO9v44heslW&1S*urlqbf0U$*-PNWJm&C|9L zvKVyPyTSJIQv9ZxO7uke5@wW`3^&-!6}8$<1rea@9oxus4Nv|^7V_9Bn9+76R!;nr zuKO)KbdE%)aaFG4v|O*>5tRq3Bpr_sZ+*LC?mO-Vrs|4~?W76GYyGz%SN8kKvz3WfU zuqRC?u_;q30yX6O1c43h72K(n3NzhD+=v%mW^@gYC-4EtAk2xt-JCE=3vF-|P_w)e>5POtYR1xa(}?O@7BnWgeus~mT?_g~a7_LJ6Y9U^ z=O@>vr|Y(A!(L=ItC^pIW^2Pkd1)USxH8-VNoKfR+B?dNl@AEMh3CgOnucxD2-w(@ zz44L#*%Zr)f{fw^)4y_Yjmr1xZYkfzjn;CbTJP{J|8U^HHMqd8J5HryB~S#+=4bqO zHozf~m6dfadKw%Y%tI02j;b@{gqTFv7ZXU#GhK&3zvtF3{})}8KJCLJVsDHDRx-@_ zGxWp7TaMd~8}>=$(#_e19Zei;(>+Z*_LZ@)z%dkopaf$|=w_#TU0}QgHUd_sC(T-m zcQA0`)GDl>xCnK2@f-bMvV_PB31w3qfO3Z{SUSbA1*=i^H^>>vRY(-XiIMRVOjt9!wD{e z&{Ls{S?O>A|3wQ-MA;9e)b}?%T%kaZdJ&40)Vuwik8@20{ml$xBk5N;afrzvyCsl@7PbmQ}<_jLY=5xe8=V0UaEL$lGze*R(gR+Jw; z0r_NINnTsWbTp3(DDn=tU|&8U3UFh$Ir7qBM(;Xeq{srrmN9>k6zVVEqWc@D<%e6A zSH_b(-rn?9ZN4~?j`|(*D;uRQX4bt+FhBTT1?*PrA996ed!>z<>G`GrqvEJy*m=;{ z*9jsW7{B2YK#>UZ+I)V5`n8uE;OCo0YjoM_ba!c|Z_q6&J_j8={{FzER>;!x@d&AQNE*B@mrG~8_F_0Htk^U#k7>hW9z46{hNNsKHg7dVtMfZoN>|gIAE7q1d^wDJ5 z+jJ}fbMTJ+>?GewS*kfhfW^)j3}I!w2#r zq)PpAMbzsGLIZBjL5SnWd9lgfA(uA*Aq5PS8A$|*X`~~g*y%F^lD2OP>-j}pE=ct zv=DiJ{P7E%L@xHWyZDwB`3F?{;XsBPVkg(C{M4NI1;qElZvc`3EjbH|Y)xg{VgD(t z^c|k+{&G(P+|~CS`D7oQq%s$d=>sPfMrzjrrXo!w7&#u4DY}#T?mP7}|0Tb`l@qF) zO{7O2gos7piqKylb;OMOvT9_gB~$5dW{%`D2c{Mx6Lo!(Umn04S>r4%DmS{jlTa7! zb%2O#;UB+(bb|O_N>#&LmKL+fsOy7J;U-~!yQXtgqy`m>8rHHcKBBA%KinUO6IIBpI=OPSae!{0dM1Wz34g_G-#Ioe5eFTTg$yU9;V~? zu_BGOJ?y;T5jXY^59k~*pH&LO2G!wgS}tGNX4@O;!YN7JtRi|eY8u*_18sP)uxwrIoHH|yjV*o_B&mGSVOzgEG0l$re&h1eZ!5IMs% z!X4YnWj9b}Mq2R+<}e2I^|vo*99GP+ClWF297j1qkHho_ojGr*iIM>B(n4(NiSl*Y z9TDFF%DfJ&NI{#wg9_bd$Q>vNU%!6kIUisK<6N;B8AHInDy65VC$t};g4(u^|65+* z$2Dw@HIS7PU*yO!lp=z@NlwrujisBq&Fixw8*4Ni@vq?KyQmR%uK4=puv_^CXDvD@ zPww5UTV>5D)Y3O1R#-53`EbW&1TxaM*Eru9&w20lkk93Lh$V@HVnwH=y$t#MH}~S{ zs2Fh}TB<@3-vcLvuk-i|XUtV^z3YDzy6tCqK!D~`z8?1W{I(yzjH6Wh4!ZoiPxSzjeR<=2m|vBeC`UyxPR?w#Jgo+SWQJeu&~A=UO3D&_@L@+M<0t>*Z2{-{eA6IB z6=$s5x526YKXZgOcNIe2%XF}EkY}_8igL1^8WecN#jhC_VtGXA$PwPisn1AxoFlBz zHf}J@_m8$=$z)EE-@+b$7PDp~lXV*xPQP{o&RmObg9}-kdwSqE3W467YU|nHgk6_} za#w$$WM^NL%-#9*X46xWso#n>^J01wwXCYrIit&1W(GaQQ<)BwmpokQ(XwxyuHMt& z!{8H5=x%4;5G}N|9Q}DlKYo%|hviIn<+8SS-qVI|Sp9+Twwssu(guo%i2NWPy(^LP z5s5btJyvi92=RWhmL6g%_f+QaKGAlRzVD&bh&4K8{BDa4DrXY8aNXg}w+2qwiI0qB z9?X4>qAH6zF)+&y#9ln;Lxew`Q1;}m#TFOcFg|5+Jo?sx8Z`0cn0_k&TW1A~U3K^O zzcDp6O-oC&b8%@c2`BqsT{*M!3ACD`U^E0wBW!?ZEBO8U_pC86GQK6|BM=i41HSG( zE8E@(LN!fIV7J!4`9y!L#{6S5O@<_Qjq=pRp5wR2FGAU-P0XLqKa?`281vz#bSMp% zBV>52>Y%zw2}B>I4x_kQ_2uOCH+$AibnRG3z8sp(iCVKBJVBO1r(DGj7~c{-AeH&P zD@jk$nbzb_XWRAEpw};Y!7dJXReGqs`Q?$1L?Ei z2Wghql9`17WR~5&>Xk1|GKimNI69a%UFeo856U`x1Cj`V=SmO;!2 zTvFyvnM!O%;=_aG=Pl)*k-L3+^aQs+UoHE$=hbgmAkHYrrNg#&b@>A#S$FaW&?z|V zRv^Ga3!`_o(FcsbF)=ZFVVX@Yw15ff0;5vlqMa}(Jng`+3a%I!P5_l$SzFsubTh{t z8D~q`l`x{;!+UA#SW;pw!F-u#seYgN&aSu6swd6;75$*Qw5^+r@0~^s!hO;_rwLw% z-$QtmyD|`roU&>{COyYzooHf(c5jWazi6os3i?oa`A~RWu~UkFUzO{8KKvdPtg0ih zw@CbYEQ|8|-xNl=MoXU`nCJwPiyz*$nNKd|D2qprXG-Dv7op;I_GrcAF{5DYQO@4HuYvvZmW#8h zh>1R@t50(x=nnUJY)!KNjE{!cV4JcXY#Dicuc`jh&}?gc<}`gnCH|MrME9TWJT7$@`)t40`SaM9*ubfUNMi48 z#aZL`+OaY_TXABp6o59Stz>EHn7?fX#+3ZycwpNDBm$s)h`{4tTj_t9pTMjrkjN-Q z1U)>s`1qWwRfvg+!BizuBmikhhAA3TnDFrMoyUMYdXaz*78}T^msGpBykYw!Fh|ApAmNM^Hl@j*K|Ab&+?{9a= zu-4lZPx4v$`l#@mN5u=BQ`cq3o#!o_o)T4sP`Pbx+1VUV-)yU@e|foc4pn(s^E-u( zh?X$d(a(~sF3pB~p(4hel>Av=F)ry{8)r4A_(M+$mcb+t1LLjI*zO#L)o;*9{>u3S z3;9`9g)Y_KPp|gBW0h4~q!0m9Wpc9ehv$01(ap`R!ff;d82g+%sLBU}hHI;HI_)&lp_1^M7z3CJ#R_An0I+>e2Ta$Hb@Q(2J@z3?dzF?>s*7lV}e9o z?0QK+5z_!VpxR7h#l)G-lg=I8!x>(fw?wTQFrhX&?&_RLQmHfK(ffv4-Sr2A2jD`v ze1Ro!BfO%YWUmj&h&cRfdfQ};O{9Q%CRzNK=GThV=f>5y9gW{!4{1LOjgWI|o{(l;w!+(vEs-dEyA_|l`U^BzS!dlzh?ACT&?4~Yn?)dGzf3uSl$-vB< zlb`?NMd9>3KEx??qDJ03wm89K(_R$dLe=E1#Xmeb4! z;@ZyL2{1m#*h<&znN5sxD`N256-{{Q)lthlPXhlCmcup0JtbB7)+2Xz14*;xIQ5Rj z>WJjb9WiCwPks*FXD+8uhPR-vcdD$;4NWIo)rml|$uANWbBTVU5j4r-Q)swo;`>Z# zG@SfKI^;kWCG*M7BepeIJ~E5;W=}*cPa*F2?K&9Wb_Y{O?m+1RLx>C^*{E1pQ#-tm zgy}$r0MTD`&{UF(x`ZHXc_dbT%cR~LKU1&w`Z2^Odnaq0!|7C+n*b7Ft0rFF`JDCo zO~~=Ar0TPLtIeN;Mv7|#T*mfMIxc~KQw9-rilhl)a zyqDCP{o#beh!CDz&ikwGO=&6mc>>1lz{3UPyceE%oE@955m|H~P(QN%rZp@er8g`= ze+L6gVB0dr^v$D%R$a+9R4}mvBHL& zh8Ui+;DVWe&kJ%VZC>kdEH8i!sDK#{CNW=^KNEt$V*9xTwjGSQ?(JEyU_ZaF)u7GK zXZk8^S;2AoVjB5Ox`|auZ47ipyoQe=i|#|A=R+|MTjC$8rX44m=}k}`1kE-Cz8Er* zXDt#`FtM-d&Aq~TBv9krGwms+vUXXttYv0Q^i0?vUhwA1;r|ZP#KKdNkM2U}cWtn8 zql(Ic{A63srz3T*5B2|OzIV-Eb-bQvGVFR)?Rv5AiXPaQsAkgf(mTo#8?hB%17K{tM%o~ESQfE5EpoHie?^pJC0dp1e6Ucc&4t93rleyePWP6y<88@ef z53c+Ha5t^*hy>N9zm#zu`?D8JjF}5uBVwUv~ef9n`Qshf*{7PF?}B`AR+m z<=ra+3321=C5(sh>@-b5D|_AwWEZRnd@<{IAABqqhCBBlPx*M2ksJ@tlefMVmqu(D zAJ#68W$uVhqWYD40BZ+f0G@6*=PV-Vp1IL*pUE`W1*aN}--hGQlHX$?H7Uba@Uv#}>B!o3;#WL)+?;-DIG6fW zSmbL*N8ixAZ9%nnNDm#v0E4-rXkAm7*DBW*kI``ReC!%%Gh&Oy@yj(~7?l1I8)Pf~ zbg4n4$~zSAL!F>QoO;R7sc}8%_Zq7If*&tRcsu#F@pnyWuh(@-@gn);n*+jbcwtde zM)vNhsRzicPnAFXLq@g53tQ*S9G~tjpS-3{!P;H-4~9d|)mZ^{)OOeR{&HW}bvvZA zvwk0(u^AaWwZYWKqNrVuKKq5eLs?o( z`J2VVeAfuKGYmnHKI)xGrNLKhu?fK>by>`rU6>{Te{{aHU5)-d~Tm`TEwb z?Or(5*4~)fe0am|aoq%*Ok6CPQBW1Q1J#z{=$`VMai3_gj9Vu05IJwT0M5R3?k)IAnGWQ`GU{;D|Cav9)KO?)ofLC__Z-fNp z2?C76qL(fdob_@4M`dRo&*j>#{T~WtNFg#+t5uOirGyNrsLUBMWF}+CEGaUCM9Gj@ zq(SB>WUNqxkjOkF^H2#H_i^*=_kH%W_w(8B`_KBUW!=;7y07~h&ht3FXU^;b7n|8! z3VW!MPDuxeU!LlqmdsbrVT}Mp=Jf8 zl@TT>%e?XY9p~Ru@Y*_<6|lTE+gT){)!g+VYMJjoY1m=&YBy_xsauoZtmBnGC0Qpl zB40^{j*l;CqA`uKUcHoWqG1e%Td4ZX2WK(yWcCP=3`jpg_t z@a79YWxZr$B*iE4O_EJhV?X9y>FX~DcewAoGAzcgZ*d?;&}l=~&3da7c0n}BY6We& zI*UKGV&ACf?Hs73*g-q(Y%(HtxJ}C`NXwj^<|yTF2NTnN*8}NyD-ZNhop7dJdeU$= z%OY#UKcWZ~5 zD!p=CJ|)kOYDcSI3bkG8(jIZMAT!^mYuqzSLGi7(r|+Ha!41VxA|5GhoLkbw-@#v1 zaOj=aUT5c0FNt9rstxn|I+pw2NnWHj`-pH2eDwl%xAVQJlkd^wgLXka`goqJeyn`c ztm5J3;pg-ZDP(19*UjV1$!9MWTUQhs*Ov;1PA}Ds=WzJFeOt!B)bxruktvPuQx`oI zZw_xd#q;OsCbOng^E~3wo7`XjsEAe8h;qc;C584|N)?G@3TH7STY8I=-S_tl440$o zl)n71RV7h_QRGGnv^OGQ)_stV=kCuK?~ohyj8_V$tb7AMUiOP;wXZ5>3Sc*$;eEm>QT|V4M?>V>k zuQYr1G_zG>k>2C?offD)kNL+qa0TUE9aC5}4}{)@?7d>?#}}T=J_BPt35%~@8KtXc z@h)7IKAB0f})H~E<89{VC)jYxnvSs@1N%->Nx^}!WV^4hV7i~1H#f80(6ZvN6L zv!v^o#iVIXC8%|T)0X|j+?X9yMw3dyA@wiZ&T){QM#@BSYHO=iWNn$+w={g$*u3-H zVuv)P;{7<+3bEm(YEbmfc4Qjr5&iW1bMb}4-lVlF#pci`nC8EMLCEW@Q+x*Fe|dHcTG`i5&lh=t;#J%yLv8tG=${NGHS_!~Z82q0v#qXnI|nn(kF1jUvaMtX&ZeX* zS8&~M-Q}ekEkNFI)jNbE)Bcj^!Nw}Yn;r?8Z-dB=U`{YGF+FFvICL@FhM5$1dQu%N zn^r7);tCt*j%TB-WHIwAdrp2?p%c|PEGngEIDdNQhl(;rsLq}iB>H;C^oul@ev3G4 z^1~Ww>OZabc1uI=z{>GyBaI58aTlOgBjDv}eg3vPKMJoMJw&EU> z`RP7FkdT`zh%gsaLYK9xTX^2ttZt*KdH*~92_(z9uX@QyW=DRjP(&~rKb-#JI3ur0w@VNzLeR9_x@l2@0o zT1VIcdl_L0{U>b2Q#||k-)RtE3>>VDNaEfMJFgaT+eb@3_T~lndTd=A3hk#x<>?O< zFvaZ}o4GmPPk(*HZocK(UyV5|MwWXR<5+1}v}wpYC)(np8vO0gcIH{}`wX@eJG(Ir zEIO!(7CRZ8v2hNykvo@5yIb%VNj1W&Ft6Rf|G4TDZMpX*MrscC z8$W!^aO~4h`=gt9yJU+UnRJT&K&So;uJ#j_oZgD^2ZAiC1};Wd=a-wZ{v3X0H!UQE z@jr%-dnmv1HBb6;gT`Dl;rUgch#a~Sv5Bwh?Gz3zwzK!!cl#e#M{s<3w&T2_;t=3m ziF#!>E#7_R`P)j{zwl{z%6)CZBoO-A*8q@^6pd>RpASfP|M9*&C3G=jl$7Eq5-uNX zFry|%Z%ivq<(8S#Z@4=_{SXCfG_v-S1q1Yiod{7#5=`Km$oswg=l|7Zq`rG)4 z;Ho)q>A*^TKHcC*S`7enIzE_=Zpsj21OMBb2kMr53I`jTmUjw6|=T0Z2lU_$`*|T%uJ{KD0 zdeHIjH*94>0ifC1H|QOk#<^*qn2F)8Jw&quJJ0}q8eI+<5K_&A;0XYvd{(^Q*s|8&5(_vVTC^ z?%F=%-VJ$gw@Uf#yGQRdf>Zto!M|=ALA~3%voIWEvF|gZJ``qClNv19_ z?R}uJnC##jukif5>&7qVns<`YPb%0vWOaf6$qz_U@mn?F3Qq@uiBFR$QwM=i7tE zjuUgU0|*Rsy{_?W@Q|R&3qm*$`u9t@b@{#bGlT3ZZ}&cM&L6qy!;rZ5jEm^CHwRf^ z)UW4+i=>efs{}yIepAK@+kekKejF?!g2f;uMUKJH2n?g&RY?0ygV2!;5E$Od`}+DT z$feaCvbVMEtz^+N1`3S0lkM!s^S56rGE50<5TzP|+Xhw;CKX0HwsLE#J(T~gJ@aRv=fd_f|(Q- z7Y8>tmrE}hh#t-3M_5=`0DKEfOS@X)E|jOMeXb{qgY@fpM~78B=mAaFrD-2)9Zu#p zh-iQ8cU*s%LcnEO|N8IIN+3<%zwx1=qu}7+7$y)T>`fMV@N_cg-0hk|j0eOnB)0$` z(Pxc-ST!Rfqc1ByKE5yYv`TH1UEWw8@?mdf7x{*+{pBz%e>GbXPAxjG+aqUQJWRz*I~IYZ3O`ff-_OuWrsI)5AdGpIl`YFh{Xb}lL}2^IjnTkgu*V7uf1N&Y>{tuoij^-6`3<~SE%f$u!6n7TQC&Ax zpl;hR!?}UB=;;JCOs@KU5)46U`~UQ+zu8MR{F(L`DWi1Z0GL5Qm)(JX;>#ab1nHu? z?t^23Hpo-`U?503OHAUD&qjI4dLI2+AE;erkIp%pDOzhAQ+qr!TrJ`>kSUb^})l zyQNt#@43xpH#hES0#ORGI$~u)sIP%fqW6Fl6LUaNevm8xqZh_0s3`8=aEY#Y;P*w9 zpG+g$c$3@gctu48nFl`4km%@+@1C1>dn?_!)U%bO`fOZXcw1u>K0Nq!k)UdIoop&u z2Dem1LM51?Mt*!)d4+0db4?4qOm4{aO&-zF?4Vqk9Xjrzk!4tE(iO1Zn<4R`z~RSj zd?B`VJMyb7TY{uBHAzZE(h9|MY^t6})1*Pj5|7c$So(zdcsLbiQy#gMI}l*Bb}j zXy2)+$o(AIGwksDdX+zYdbbXNAKgF_UnV13sJdZ$3P+%s`5N5S?2$7E>2TDB{J0ur zVb;c`H4tp0z@2n%1@W1qvif5mtn!k!^2x2?WA8P&R5yCr$B0Ipy7Jgzh63{NA#?v6n>uYLr^Pu;A2*j}B_y<`>(pUznsEKDhqZ+`B#=t-?>T ze;X^rhW|($2q9p#XPS$uJ*q;t9_N8z?`QSb#P6+JC*TCd50AQHP8DY`AF)ctZS~-( zWbEzrzYcNUaXrh`r|#OcCE?-ywQKx3^o30B_sQBHIX=jrJ?FSzpuXNn-IczQUVIP9 zp71E`-$f8r{k{u3QOVd8UkEa=NHmD=z&Lh@Q+8)Nu{8E zA?)cD7Wt9B&GR3BbglHL+Rz+WLOV8CpA{%&_k>sf&Kd>Suh!Ij3ztDcSM6}OHR*_u zB-I)_){l39kt(?`(3Zaf>fG%wD2DH^-_it)b>bV>U+t}tJ;X&m|33g@C0bfqT63-b zOMaQ(=0gO&v;L5~n@A&WteoQtu8w@KAO8A$@BHPg{}1Ntx2SM3e2I7W$ON(8gziB5 zXEKJ4f_ER-If}fTb|&2xBYm^>pnqPu%>%Z2dX5w2x#rEJNB^5?#!?Fpmw3;0?oQ{! z`407gA&WhDAqm@MN$XJ4%8wsuN%y3^f`hkUIpA0YBJaT1n5E13(2yyseIDW%4JXwS^!G$0gm40+5-KWR78sxnb6Y^KC>;uOQE35V7 zpSWYypZWRw;o(cQX$n~c&=Gb%U z>e~Yn|B-ULE?;}(=+VXz2NDwt%dalyo~=7}e7(pokENwvWYoxO@;EU+;XGOzyMgEV z9x;X^o7-`5_;oc{j(dnHlY-QL44A^C4oq7BAt zzs(iK53>jz6=_3gsQNjl=F1Ve>OckM4d4q(ZPd+5IP5ticA`UzVPNddAw06d+7Q-1 zsv+#*#%(rtJ5k_B8-gxcvoR0SJvcqrKIil}#arATe3w+E!K!FG@QT8TdTmrGxZb_s zD`_^@1g9rJw)wFk|8z>j>ORUQGr_>|iF&Y>6ik?3vPTeD8H{J?aY;gL&dsf4q$GZM zdWVbqs4S+|Kgr*MY|EM+F%Ok=B~#;RX2Y*og{6D^V-!rk=gg5HS#|T^M>$pyL$+Qe z8-bAk7P~mIc&7bSbvs@;>EH3lrk0!R!h?Uc0}^^`nVQu@QBrHCke?^IIgSq zzrLv9CO{FZaA;%h{`Jv)$1QA#;0(2VxR{{A#I-oe%_z}U8F$q6044Xz`pn1o_5;iK zNjf@DQq|l@O;ELrfaP>?(Lk zA?uthuv9mZx+E4hs-@FWZSifbT^sFa9Z7ENoJ|>bXxP8g8dijsf*|yB>fVn)_r*)d z1cb+tU0sL0^Ht|;dDOwmMt-acVXHc2U8`GGC%`9pps7^h&b!67HQPPr<3Wog{d>`C z{Yoq7g|I`gZ=jcwcJsKcC5;LQ4ex`h@7P=BvXmjTw)9%m)voKXT>x+UF8zV^$sv5O zYiEk=?!|eNjQ&3TO7>T?gB^D$oAGe*Q>{n(?{VJ96!Q3e`P#u!UN#{&+3xuf!KCg5ADf_nn1X!tb^Ct<7tRCYqw2ZkYy#2`^3XCf&Wl!Y4cYZtJ=A69zG&_uDHyFZnJn+@Uqy`A+HPLbZ}K)$3nSE=u#w`>g4+ zeFV1^X|4AX*H$H}PmkiPoeq}l4_~bx55C2sE#Cg%qo0s-=5-s9V@>CV1OD^UdREj9 zVU8sE9Za8mx=_&#ghi8g%Q7Wt^7e{uBV`s@4|vt0hAI z@!rHU`yGq33M;?sc3$RAv&dU^qFjG+&hBdo!)!6E&yyXUv%gQgcmS)xeQKNi@WWSS z3gzc~Yc)P#`Q(Ap>GeB^9AYN7&>lJ>c^cj(&Bbz3ciEn8GM4tbD=SP!+m~vBZyD!l z(sKGlwv%BEKm6q6qDLh2(kwm4GRHxy-;5hI+dK* z4w;c*S5`DHaAl;CdJxM3G4jc${LcYwYb7#@Bfz|2ccN0%l< z7>A1yQh+sBI*8)~DDHlRg|098h{ZPfQ5x12roWe{)smHTCoc?D(1BLpL|`>dXii&1VU&9Y^mq-L4CRJ?sM}q&jS-H6hF*;Czd7ttGP$Lqgsp zobo#1FwDTk#ntK1EFZ`z8os(%wrUw>Qnzk$OG@r0$9Ng>GG8m6_3{OJ+Eu3ow*V6p#$x_2B<@abZguf{`epJ#r=j4=cXk(M1dg&4`a#h1 zhp>#ZbJ?`#p5Gy8ru34}QUM#ajBh4b?+;U3q%bEJD=7yYVII5@lE@Ti`Jm3}sgd+u z9daN_iLLk1qs#k_{kyIAPAo^#^5yV~wjMb~p+c2urz9HUR69ILt^tcHW^UhjFk16Y zgY3Jz{W5S--T%qrrT}*wdwCQaP%(|cx`se~S3@J{dpIp?JOi6zS!rqCzUun=NiE%c zqRzqYJghz@Cl#=Id8wX8u8#>BVDc8>bb=iI0!(n!Ww&?-MX^pSyJGn>)#M%b^Ezr@FmlMVc2O zc9sSB`WJ;LDM^u}b-}bqXh!S(;;yNRy+6g@yV?2|Z<%;_nH)dlpUY+>_&`NAd0Pkg4ku$PC2r^bVfA{1^l6ClW89|(}y>8?s3321L^iHwXqAoF?F zK_s?+d_0vy?7FHl({hgw0uUEfRiD@yr;S0RuAHlt);~7(5{i?y>Eas-`HFUwy=>5z z6HfNGLNV*Gw0n~s8DU|}LY=l0aE^Q6esHU|&|TPw%r=6sKf!?oi2sGti4<-=J`-Y$ zm}!#rEu%u!g|MWH_??dv5=b72iGN+z(GgwlsYFN#A8^XA7~D`VgmjrAO()WVwD^hmu_b~dL7K)f{~}uU|ZJlX=Hi;feaop3UH*HS5T;`tn?vd_KzO1`qJ)r z11mGM|8?eqY^C%4G}fhmuH0~U-*M7K0FD0c%^RtSPwi{ByJA7LOC*9g@yV0FlNLX% z0;x+ZpCLwk+5Y%>3dB`NXApE`V7Um567jyp#koLa&wFcm6f1h7G6TT?qvaF{MPC2t zwf-|iVl?8A&S!c>YRP)iWkwMDvEIgKN+zkygb?zNA3v0Zk2n&6Q{v2}>9x$-u9IF5bk8yq|onzj-FFQNi*3l7_6XNh_c%El# zQz=G<|29JWyTUpmVG?tCHo+Y#9Vi+>@MtnDy5PH}K#Z3c*t>=X0p3o6)rPE_+JrV= z>_m^ApTtA;a;ef; zH&}7+Zmmy1YMcjb5C<;Jm8~8-c?%sL^U>*ead%b}-q6(4^fducn%J=7UNHSCXZSxz z?Y3w|A9Dd;_kTqenacm6UVR5P1Zrb1pwV~yiOat5^U*-P2~!_ z&Ul^*8vbHZIdB;7Ae{y-`YG~Lj-|;G5PYIbqq;;L>RWUVyOlbOT*No!hr%Q$PZn3~ zQ$mptQ&6l)P&ppKB=hFY8)9q)YoC-*R1}4XXvodw1q_=Np*$+@8yYfRr6DbVB;!2V zNgfa%@I#2P)pzjL^7rm!S(dkpqxgP+_}>9_F=o$$TDg9h!H(*ela`j2Moa3eR^n!- zdKxg`qPEL!fZ7osPEoKzf`BNb0+4uFD@ zl?ZdVI#7PJ_FWS5yDhIur{y8SMEl zC@Vie$(g4BJBZb#&rRK0)&7Hrv34Pp$YB`FlQT1waL#!-IaOf5!vX>}55Ar%Rl)lT z#lU&?Su+nv%g-=Pbo4Gx_Vy;kh&tC#uQ0Q)U={T_lI3Pwra=wRG0bO`LjhgjMX{EI zi`v@SLp|StD7>ia(zo%glOFzQ0#g6)*@%#kL{behBE<1PYnYiM$z`E@qvupYf|pGI+eNuWaIxM2ryWFdv@ck&w_sl^cQL@6Z@lc64YH zA(MCcc7rvPJ-oZyX@vRrio~Mz$$O`!8qmrAK#%+5*DoXFd2S$`r>d%|q^xZ4DC{cU ze;~V15DM&2=v!MO>6B#P21W1C(`f5{*c#Gu;sMNN|6UZo&PLBM_zG;c{-b4UI9Z4j z5woWd02ZG3l@^wkWDvI}JifGo!bp!KZi&O{7a9?Pv5X^#L-;n-&S1je17ZM&8}pTB zf$eV0ryxuaU)tNHQTepFOBiSNAhP6p-cs^b;a_56v8Xd~#H5A^u_BUtbSqK1XFe_% z+0WOLMRzwb?z6>w!pOw*`CC~dB-GXTA#@Sa=w~Fn6$*Rlyif z<8Lnb1A0QXF!l)z>pMtLfWXT?ief;=FAq`8Gj*5#NfZ$21$O@%B6=iZ zJW@`QMvafnFnbtPrQLM zZ^}%4@f%%Wv^YP@s5;xEb~_s6ii-6{U z%c|xY2-mhgY?X8viKA~YfC)04N9Ku~Skl7Sca9*|V{uJ@p$gM{5kh1gWhh-)umlGs z!-YLUaAr;r!czcz+p3*2+BE%8oy^C zbP4rwVzO{Xq1=&~Kpf_=ZkGYN(}N|*2kpGIlx6S-^%)|8h{A_bP*n62)Hreh6yBOF z8at$(e)&8w$CwbG7{uOM9@8V71skZSnlVW%%uZOIFzNby{nlbf&phTu%tyV@{(je6 zU0`{6DdP%an4w`|%4%w7F)QN_-+kGw_0h&y!uR#|Dor`e#rI5sCq_6~kg`PB^C*WP zdyZ|N)XI_}0MFo1*<*uUMMt>tw7*8+qyt6N_bn*_!3<)G{$>HJxRGwD+LxBmkvyn{pl literal 0 HcmV?d00001 diff --git a/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-6_00.png b/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-6_00.png new file mode 100644 index 0000000000000000000000000000000000000000..b0dc2d9ec56469ff3926698a704506acaf848283 GIT binary patch literal 22833 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 z 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 literal 0 HcmV?d00001 diff --git a/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-6_02.png b/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-6_02.png new file mode 100644 index 0000000000000000000000000000000000000000..a744f3e325bfc4c53733abbd226ba5eb1de93c80 GIT binary patch literal 15360 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 U7v+D%)40T`V~TP~M=sy`Uuv3#ga7~l literal 0 HcmV?d00001 diff --git a/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-8_00.png b/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-8_00.png new file mode 100644 index 0000000000000000000000000000000000000000..b0dc2d9ec56469ff3926698a704506acaf848283 GIT binary patch literal 22833 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 z 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 literal 0 HcmV?d00001 diff --git a/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-8_02.png b/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-8_02.png new file mode 100644 index 0000000000000000000000000000000000000000..a744f3e325bfc4c53733abbd226ba5eb1de93c80 GIT binary patch literal 15360 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 U7v+D%)40T`V~TP~M=sy`Uuv3#ga7~l literal 0 HcmV?d00001 diff --git a/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-8_03.png b/public/images/api/qiskit-addon-obp/qiskit_addon_obp-utils-visualization-8_03.png new file mode 100644 index 0000000000000000000000000000000000000000..41504523cc86e0996f01a547ab0d016d4efb8b7c GIT binary patch literal 21541 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 literal 0 HcmV?d00001 diff --git a/public/images/api/qiskit-addon-utils/qiskit_addon_utils-problem_generators-1.png b/public/images/api/qiskit-addon-utils/qiskit_addon_utils-problem_generators-1.png new file mode 100644 index 0000000000000000000000000000000000000000..5f4c10fafe52c3ee8cd3037fe793eab773520b88 GIT binary patch literal 27044 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 F2>_R@pfUge literal 0 HcmV?d00001 diff --git a/scripts/js/commands/checkOrphanPages.ts b/scripts/js/commands/checkOrphanPages.ts index 52175f5c327..672cf4652eb 100644 --- a/scripts/js/commands/checkOrphanPages.ts +++ b/scripts/js/commands/checkOrphanPages.ts @@ -51,10 +51,7 @@ async function main() { const existingUrls = await collectExistingUrls(dir); orphanPages.push( ...existingUrls.filter( - (file) => - !tocUrls.has(file) && - !ALLOWED_ORPHAN_URLS.has(file) && - !file.includes("api/qiskit-addon-"), + (file) => !tocUrls.has(file) && !ALLOWED_ORPHAN_URLS.has(file), ), ); } diff --git a/scripts/js/lib/links/ignores.ts b/scripts/js/lib/links/ignores.ts index d3c12918b54..670c029ecfb 100644 --- a/scripts/js/lib/links/ignores.ts +++ b/scripts/js/lib/links/ignores.ts @@ -332,7 +332,14 @@ const FILES_TO_IGNORES__EXPECTED: FilesToIgnores = mergeFilesToIgnores( _legacyQiskitSDKIssues(), ); -const FILES_TO_IGNORES__SHOULD_FIX: FilesToIgnores = {}; +const FILES_TO_IGNORES__SHOULD_FIX: FilesToIgnores = { + "docs/api/qiskit-addon-obp/utils-metadata-obp-metadata.mdx": [ + "utils-truncating#TruncationErrorBudget.p_norm", + ], + "docs/api/qiskit-addon-obp/utils-metadata-slice-metadata.mdx": [ + "utils-truncating#TruncationErrorBudget.p_norm", + ], +}; export const FILES_TO_IGNORES: FilesToIgnores = mergeFilesToIgnores( FILES_TO_IGNORES__EXPECTED,