From 29b8c600114ad525b2cc5eccacd809917b7f7288 Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Thu, 9 May 2024 22:40:26 -0400
Subject: [PATCH] Regenerate Qiskit 1.1.0rc1 (#1338)
This brings in the revamp of the header hierarchy + adding a missing
module to the index page.
---
docs/api/qiskit/dev/assembler.mdx | 8 +-
docs/api/qiskit/dev/circuit.mdx | 6 +-
docs/api/qiskit/dev/circuit_classical.mdx | 20 +--
docs/api/qiskit/dev/circuit_library.mdx | 10 +-
docs/api/qiskit/dev/classicalfunction.mdx | 18 +++
docs/api/qiskit/dev/converters.mdx | 152 ++++++++++--------
docs/api/qiskit/dev/index.mdx | 62 ++++---
docs/api/qiskit/dev/providers.mdx | 30 ++--
.../qiskit/dev/providers_basic_provider.mdx | 31 +---
.../qiskit/dev/providers_fake_provider.mdx | 2 +-
docs/api/qiskit/dev/providers_models.mdx | 2 +-
.../dev/qiskit.circuit.QuantumCircuit.mdx | 2 +-
.../qiskit/dev/qiskit.circuit.library.AND.mdx | 2 +-
...t.circuit.library.CDKMRippleCarryAdder.mdx | 2 +-
.../qiskit.circuit.library.QuantumVolume.mdx | 2 +-
...qiskit.circuit.library.RGQFTMultiplier.mdx | 2 +-
.../qiskit.circuit.library.RealAmplitudes.mdx | 2 +-
.../dev/qiskit.circuit.library.TwoLocal.mdx | 2 +-
.../qiskit.circuit.library.UnitaryOverlap.mdx | 2 +-
...it.circuit.library.VBERippleCarryAdder.mdx | 2 +-
.../qiskit/dev/qiskit.quantum_info.Pauli.mdx | 4 +-
.../dev/qiskit.synthesis.unitary.aqc.mdx | 10 +-
...ranspiler.passes.Commuting2qGateRouter.mdx | 6 +-
...skit.visualization.plot_circuit_layout.mdx | 12 +-
.../qiskit.visualization.plot_error_map.mdx | 2 +-
docs/api/qiskit/dev/qpy.mdx | 24 +--
docs/api/qiskit/dev/result.mdx | 4 +
docs/api/qiskit/dev/scheduler.mdx | 6 +-
docs/api/qiskit/dev/synthesis.mdx | 6 +-
docs/api/qiskit/dev/transpiler_passes.mdx | 4 +-
public/api/qiskit/dev/objects.inv | Bin 69949 -> 70005 bytes
public/images/api/qiskit/dev/circuit-3.png | Bin 7947 -> 9531 bytes
.../dev/providers_fake_provider-1_02.png | Bin 11439 -> 10966 bytes
public/images/api/qiskit/dev/pulse-2.png | Bin 10732 -> 10944 bytes
public/images/api/qiskit/dev/pulse-3.png | Bin 59375 -> 59802 bytes
public/images/api/qiskit/dev/pulse-4.png | Bin 19004 -> 18925 bytes
public/images/api/qiskit/dev/pulse-5.png | Bin 16358 -> 16261 bytes
public/images/api/qiskit/dev/pulse-6.png | Bin 11363 -> 11354 bytes
public/images/api/qiskit/dev/pulse-7.png | Bin 14012 -> 14079 bytes
.../dev/qiskit-circuit-ControlledGate-2.png | Bin 7240 -> 7180 bytes
...skit-circuit-library-PermutationGate-2.png | Bin 16100 -> 15921 bytes
...skit-circuit-library-PhaseEstimation-1.png | Bin 12197 -> 12207 bytes
...it-visualization-plot_circuit_layout-1.png | Bin 10381 -> 10094 bytes
.../qiskit-visualization-plot_error_map-1.png | Bin 49079 -> 49236 bytes
...qiskit-visualization-timeline_drawer-1.png | Bin 16008 -> 16070 bytes
...qiskit-visualization-timeline_drawer-2.png | Bin 8026 -> 8002 bytes
...qiskit-visualization-timeline_drawer-3.png | Bin 26833 -> 27461 bytes
.../images/api/qiskit/dev/transpiler-16.png | Bin 24800 -> 24950 bytes
.../images/api/qiskit/dev/transpiler-17.png | Bin 19005 -> 19211 bytes
49 files changed, 236 insertions(+), 201 deletions(-)
diff --git a/docs/api/qiskit/dev/assembler.mdx b/docs/api/qiskit/dev/assembler.mdx
index cff940fae72..f6e6bb4861c 100644
--- a/docs/api/qiskit/dev/assembler.mdx
+++ b/docs/api/qiskit/dev/assembler.mdx
@@ -18,7 +18,7 @@ python_api_name: qiskit.assembler
`qiskit.assembler`
-## Circuit Assembler
+## Functions
### assemble\_circuits
@@ -61,8 +61,6 @@ python_api_name: qiskit.assembler
```
-## Schedule Assembler
-
### assemble\_schedules
@@ -125,8 +123,6 @@ python_api_name: qiskit.assembler
```
-## Disassembler
-
### disassemble
@@ -172,7 +168,7 @@ python_api_name: qiskit.assembler
```
-## RunConfig
+## Classes
| | |
| -------------------------------------------------------------------------------------------------------------- | ---------------------------- |
diff --git a/docs/api/qiskit/dev/circuit.mdx b/docs/api/qiskit/dev/circuit.mdx
index 3249fd1fff7..aa970918b45 100644
--- a/docs/api/qiskit/dev/circuit.mdx
+++ b/docs/api/qiskit/dev/circuit.mdx
@@ -147,11 +147,7 @@ When mapping to hardware, virtual qubits must be assigned to *hardware qubits*.
-## API overview of
-
-
-
-`qiskit.circuit`
+## API overview of qiskit.circuit
All objects here are described in more detail, and in their greater context in the following sections. This section provides an overview of the API elements documented here.
diff --git a/docs/api/qiskit/dev/circuit_classical.mdx b/docs/api/qiskit/dev/circuit_classical.mdx
index 9bf96123c43..68b1babab30 100644
--- a/docs/api/qiskit/dev/circuit_classical.mdx
+++ b/docs/api/qiskit/dev/circuit_classical.mdx
@@ -943,15 +943,15 @@ Note that [`Uint`](#qiskit.circuit.classical.types.Uint "qiskit.circuit.classica
### Working with types
-There are some functions on these types exposed here as well. These are mostly expected to be used only in manipulations of the expression tree; users who are building expressions using the [user-facing construction interface](#circuit-classical-expressions-expr-construction) should not need to use these.
+There are some additional functions on these types documented in the subsequent sections. These are mostly expected to be used only in manipulations of the expression tree; users who are building expressions using the [user-facing construction interface](#circuit-classical-expressions-expr-construction) should not need to use these.
-#### Partial ordering of types
+### Partial ordering of types
The type system is equipped with a partial ordering, where $a < b$ is interpreted as “$a$ is a strict subtype of $b$”. Note that the partial ordering is a subset of the directed graph that describes the allowed explicit casting operations between types. The partial ordering defines when one type may be lossless directly interpreted as another.
The low-level interface to querying the subtyping relationship is the [`order()`](#qiskit.circuit.classical.types.order "qiskit.circuit.classical.types.order") function.
-##### order
+#### order
Get the ordering relationship between the two types as an enumeration value.
@@ -980,7 +980,7 @@ The low-level interface to querying the subtyping relationship is the [`order()`
The return value is an enumeration [`Ordering`](#qiskit.circuit.classical.types.Ordering "qiskit.circuit.classical.types.Ordering") that describes what, if any, subtyping relationship exists between the two types.
-##### Ordering
+#### Ordering
Enumeration listing the possible relations between two types. Types only have a partial ordering, so it’s possible for two types to have no sub-typing relationship.
@@ -990,7 +990,7 @@ The return value is an enumeration [`Ordering`](#qiskit.circuit.classical.types.
Some helper methods are then defined in terms of this low-level [`order()`](#qiskit.circuit.classical.types.order "qiskit.circuit.classical.types.order") primitive:
-##### is\_subtype
+#### is\_subtype
Does the relation $\text{left} \le \text{right}$ hold? If there is no ordering relation between the two types, then this returns `False`. If `strict`, then the equality is also forbidden.
@@ -1019,7 +1019,7 @@ Some helper methods are then defined in terms of this low-level [`order()`](#qis
[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")
-##### is\_supertype
+#### is\_supertype
Does the relation $\text{left} \ge \text{right}$ hold? If there is no ordering relation between the two types, then this returns `False`. If `strict`, then the equality is also forbidden.
@@ -1048,7 +1048,7 @@ Some helper methods are then defined in terms of this low-level [`order()`](#qis
[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")
-##### greater
+#### greater
Get the greater of the two types, assuming that there is an ordering relation between them. Technically, this is a slightly restricted version of the concept of the ‘meet’ of the two types in that the return value must be one of the inputs. In practice in the type system there is no concept of a ‘sum’ type, so the ‘meet’ exists if and only if there is an ordering between the two types, and is equal to the greater of the two types.
@@ -1076,11 +1076,11 @@ Some helper methods are then defined in terms of this low-level [`order()`](#qis
```
-#### Casting between types
+### Casting between types
It is common to need to cast values of one type to another type. The casting rules for this are embedded into the [`types`](https://docs.python.org/3/library/types.html#module-types "(in Python v3.12)") module. You can query the casting kinds using [`cast_kind()`](#qiskit.circuit.classical.types.cast_kind "qiskit.circuit.classical.types.cast_kind"):
-##### cast\_kind
+#### cast\_kind
Determine the sort of cast that is required to move from the left type to the right type.
@@ -1106,7 +1106,7 @@ It is common to need to cast values of one type to another type. The casting rul
The return values from this function are an enumeration explaining the types of cast that are allowed from the left type to the right type.
-##### CastKind
+#### CastKind
A return value indicating the type of cast that can occur from one type to another.
diff --git a/docs/api/qiskit/dev/circuit_library.mdx b/docs/api/qiskit/dev/circuit_library.mdx
index c19df7e505e..78306b93839 100644
--- a/docs/api/qiskit/dev/circuit_library.mdx
+++ b/docs/api/qiskit/dev/circuit_library.mdx
@@ -122,18 +122,14 @@ print(gate.control(1).to_matrix()) # CX (controlled X) gate
Directives are operations to the quantum stack that are meant to be interpreted by the backend or the transpiler. In general, the transpiler or backend might optionally ignore them if there is no implementation for them.
-| | |
-| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Barrier`(num\_qubits\[, label]) | A directive for circuit compilation to separate pieces of a circuit so that any optimizations or re-writes are constrained to only act between barriers. |
+* [`qiskit.circuit.Barrier`](circuit#qiskit.circuit.Barrier "qiskit.circuit.Barrier")
## Standard Operations
Operations are non-reversible changes in the quantum state of the circuit.
-| | |
-| -------------------------------------- | --------------------------------------------------------- |
-| `Measure`(\*args\[, \_force\_mutable]) | Quantum measurement in the computational basis. |
-| `Reset`(\*args\[, \_force\_mutable]) | Incoherently reset a qubit to the $\lvert0\rangle$ state. |
+* [`qiskit.circuit.Measure`](circuit#qiskit.circuit.Measure "qiskit.circuit.Measure")
+* [`qiskit.circuit.Reset`](circuit#qiskit.circuit.Reset "qiskit.circuit.Reset")
## Generalized Gates
diff --git a/docs/api/qiskit/dev/classicalfunction.mdx b/docs/api/qiskit/dev/classicalfunction.mdx
index 2283ac9ce87..ade7aed1495 100644
--- a/docs/api/qiskit/dev/classicalfunction.mdx
+++ b/docs/api/qiskit/dev/classicalfunction.mdx
@@ -67,6 +67,24 @@ The type `Int1` means the classical function will only operate at bit level.
Decorator for a classical function that returns a ClassicalFunction object.
+#### classical\_function
+
+
+ Parses and type checks the callable `func` to compile it into an `ClassicalFunction` that can be synthesized into a `QuantumCircuit`.
+
+ **Parameters**
+
+ **func** (*callable*) – A callable (with type hints) to compile into an `ClassicalFunction`.
+
+ **Returns**
+
+ An object that can synthesis into a QuantumCircuit (via `synth()` method).
+
+ **Return type**
+
+ [ClassicalFunction](qiskit.circuit.classicalfunction.ClassicalFunction "qiskit.circuit.classicalfunction.ClassicalFunction")
+
+
### ClassicalFunction
| | |
diff --git a/docs/api/qiskit/dev/converters.mdx b/docs/api/qiskit/dev/converters.mdx
index 75cf0e6fab2..708c1ee730f 100644
--- a/docs/api/qiskit/dev/converters.mdx
+++ b/docs/api/qiskit/dev/converters.mdx
@@ -18,6 +18,84 @@ python_api_name: qiskit.converters
`qiskit.converters`
+
+
+## QuantumCircuit -> circuit components
+
+### circuit\_to\_instruction
+
+
+ Build an [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") object from a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit").
+
+ The instruction is anonymous (not tied to a named quantum register), and so can be inserted into another circuit. The instruction will have the same string name as the circuit.
+
+ **Parameters**
+
+ * **circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – the input circuit.
+ * **parameter\_map** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – For parameterized circuits, a mapping from parameters in the circuit to parameters to be used in the instruction. If None, existing circuit parameters will also parameterize the instruction.
+ * **equivalence\_library** ([*EquivalenceLibrary*](qiskit.circuit.EquivalenceLibrary "qiskit.circuit.EquivalenceLibrary")) – Optional equivalence library where the converted instruction will be registered.
+ * **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Optional instruction label.
+
+ **Raises**
+
+ [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if parameter\_map is not compatible with circuit
+
+ **Returns**
+
+ an instruction equivalent to the action of the input circuit. Upon decomposition, this instruction will yield the components comprising the original circuit.
+
+ **Return type**
+
+ [qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction")
+
+ **Example**
+
+ ```python
+ from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit
+ from qiskit.converters import circuit_to_instruction
+
+ q = QuantumRegister(3, 'q')
+ c = ClassicalRegister(3, 'c')
+ circ = QuantumCircuit(q, c)
+ circ.h(q[0])
+ circ.cx(q[0], q[1])
+ circ.measure(q[0], c[0])
+ circ.rz(0.5, q[1]).c_if(c, 2)
+ circuit_to_instruction(circ)
+ ```
+
+
+### circuit\_to\_gate
+
+
+ Build a [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") object from a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit").
+
+ The gate is anonymous (not tied to a named quantum register), and so can be inserted into another circuit. The gate will have the same string name as the circuit.
+
+ **Parameters**
+
+ * **circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – the input circuit.
+ * **parameter\_map** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – For parameterized circuits, a mapping from parameters in the circuit to parameters to be used in the gate. If None, existing circuit parameters will also parameterize the Gate.
+ * **equivalence\_library** ([*EquivalenceLibrary*](qiskit.circuit.EquivalenceLibrary "qiskit.circuit.EquivalenceLibrary")) – Optional equivalence library where the converted gate will be registered.
+ * **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Optional gate label.
+
+ **Raises**
+
+ [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if circuit is non-unitary or if parameter\_map is not compatible with circuit
+
+ **Returns**
+
+ a Gate equivalent to the action of the input circuit. Upon decomposition, this gate will yield the components comprising the original circuit.
+
+ **Return type**
+
+ [Gate](qiskit.circuit.Gate "qiskit.circuit.Gate")
+
+
+
+
+## QuantumCircuit \<-> DagCircuit
+
### circuit\_to\_dag
@@ -102,75 +180,9 @@ python_api_name: qiskit.converters
![../\_images/converters-1.png](/images/api/qiskit/dev/converters-1.png)
-### circuit\_to\_instruction
-
-
- Build an [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") object from a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit").
-
- The instruction is anonymous (not tied to a named quantum register), and so can be inserted into another circuit. The instruction will have the same string name as the circuit.
-
- **Parameters**
-
- * **circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – the input circuit.
- * **parameter\_map** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – For parameterized circuits, a mapping from parameters in the circuit to parameters to be used in the instruction. If None, existing circuit parameters will also parameterize the instruction.
- * **equivalence\_library** ([*EquivalenceLibrary*](qiskit.circuit.EquivalenceLibrary "qiskit.circuit.EquivalenceLibrary")) – Optional equivalence library where the converted instruction will be registered.
- * **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Optional instruction label.
-
- **Raises**
-
- [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if parameter\_map is not compatible with circuit
-
- **Returns**
-
- an instruction equivalent to the action of the input circuit. Upon decomposition, this instruction will yield the components comprising the original circuit.
-
- **Return type**
-
- [qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction")
-
- **Example**
-
- ```python
- from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit
- from qiskit.converters import circuit_to_instruction
-
- q = QuantumRegister(3, 'q')
- c = ClassicalRegister(3, 'c')
- circ = QuantumCircuit(q, c)
- circ.h(q[0])
- circ.cx(q[0], q[1])
- circ.measure(q[0], c[0])
- circ.rz(0.5, q[1]).c_if(c, 2)
- circuit_to_instruction(circ)
- ```
-
-
-### circuit\_to\_gate
-
-
- Build a [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") object from a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit").
-
- The gate is anonymous (not tied to a named quantum register), and so can be inserted into another circuit. The gate will have the same string name as the circuit.
-
- **Parameters**
-
- * **circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – the input circuit.
- * **parameter\_map** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – For parameterized circuits, a mapping from parameters in the circuit to parameters to be used in the gate. If None, existing circuit parameters will also parameterize the Gate.
- * **equivalence\_library** ([*EquivalenceLibrary*](qiskit.circuit.EquivalenceLibrary "qiskit.circuit.EquivalenceLibrary")) – Optional equivalence library where the converted gate will be registered.
- * **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Optional gate label.
-
- **Raises**
-
- [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if circuit is non-unitary or if parameter\_map is not compatible with circuit
-
- **Returns**
+
- a Gate equivalent to the action of the input circuit. Upon decomposition, this gate will yield the components comprising the original circuit.
-
- **Return type**
-
- [Gate](qiskit.circuit.Gate "qiskit.circuit.Gate")
-
+## QuantumCircuit \<-> DagDependency
### dagdependency\_to\_circuit
@@ -209,6 +221,10 @@ python_api_name: qiskit.converters
[DAGDependency](qiskit.dagcircuit.DAGDependency "qiskit.dagcircuit.DAGDependency")
+
+
+## DagCircuit \<-> DagDependency
+
### dag\_to\_dagdependency
diff --git a/docs/api/qiskit/dev/index.mdx b/docs/api/qiskit/dev/index.mdx
index 673a3f67032..a00706cc213 100644
--- a/docs/api/qiskit/dev/index.mdx
+++ b/docs/api/qiskit/dev/index.mdx
@@ -10,38 +10,60 @@ python_api_name: qiskit
# API Reference
+Circuit construction:
+
* [Quantum circuit model (`qiskit.circuit`)](circuit)
-* [Circuit Library (`qiskit.circuit.library`)](circuit_library)
* [Classical expressions (`qiskit.circuit.classical`)](circuit_classical)
-* [Singleton instructions (`qiskit.circuit.singleton`)](circuit_singleton)
-* [Compilation Routines (`qiskit.compiler`)](compiler)
-* [Visualizations (`qiskit.visualization`)](visualization)
* [ClassicalFunction compiler (`qiskit.circuit.classicalfunction`)](classicalfunction)
+* [Circuit Library (`qiskit.circuit.library`)](circuit_library)
+* [Singleton instructions (`qiskit.circuit.singleton`)](circuit_singleton)
+
+Quantum information:
+
+* [Quantum Information (`qiskit.quantum_info`)](quantum_info)
+
+Transpilation:
+
* [Circuit Converters (`qiskit.converters`)](converters)
-* [Circuit and Schedule Assembler (`qiskit.assembler`)](assembler)
* [DAG Circuits (`qiskit.dagcircuit`)](dagcircuit)
* [Passmanager (`qiskit.passmanager`)](passmanager)
+* [Circuit Synthesis (`qiskit.synthesis`)](synthesis)
+* [Approximate Quantum Compiler (`qiskit.synthesis.unitary.aqc`)](qiskit.synthesis.unitary.aqc)
+* [Transpiler (`qiskit.transpiler`)](transpiler)
+* [Transpiler Passes (`qiskit.transpiler.passes`)](transpiler_passes)
+* [Synthesis Plugins (`qiskit.transpiler.passes.synthesis.plugin`)](transpiler_synthesis_plugins)
+* [Preset Passmanagers (`qiskit.transpiler.preset_passmanagers`)](transpiler_preset)
+* [Transpiler Stage Plugin Interface (`qiskit.transpiler.preset_passmanagers.plugin`)](transpiler_plugins)
+
+Primitives and providers:
+
+* [Primitives (`qiskit.primitives`)](primitives)
* [Providers Interface (`qiskit.providers`)](providers)
-* [Writing a New Backend](providers#writing-a-new-backend)
-* [Migrating between Backend API Versions](providers#migrating-between-backend-api-versions)
* [BasicProvider: Python-based Simulators (`qiskit.providers.basic_provider`)](providers_basic_provider)
* [Fake Provider (`qiskit.providers.fake_provider`)](providers_fake_provider)
* [Backend Objects (`qiskit.providers.models`)](providers_models)
-* [Pulse (`qiskit.pulse`)](pulse)
-* [Circuit Scheduler (`qiskit.scheduler`)](scheduler)
-* [Circuit Synthesis (`qiskit.synthesis`)](synthesis)
-* [Primitives (`qiskit.primitives`)](primitives)
+
+Results and visualizations:
+
+* [Experiment Results (`qiskit.result`)](result)
+* [Visualizations (`qiskit.visualization`)](visualization)
+
+Serialization:
+
* [OpenQASM 2 (`qiskit.qasm2`)](qasm2)
* [OpenQASM 3 (`qiskit.qasm3`)](qasm3)
-* [Qobj (`qiskit.qobj`)](qobj)
* [QPY serialization (`qiskit.qpy`)](qpy)
-* [Quantum Information (`qiskit.quantum_info`)](quantum_info)
-* [Experiment Results (`qiskit.result`)](result)
-* [Transpiler (`qiskit.transpiler`)](transpiler)
-* [Transpiler Passes (`qiskit.transpiler.passes`)](transpiler_passes)
-* [Preset Passmanagers (`qiskit.transpiler.preset_passmanagers`)](transpiler_preset)
-* [Transpiler Stage Plugin Interface (`qiskit.transpiler.preset_passmanagers.plugin`)](transpiler_plugins)
-* [Synthesis Plugins (`qiskit.transpiler.passes.synthesis.plugin`)](transpiler_synthesis_plugins)
-* [Utilities (`qiskit.utils`)](utils)
+
+Pulse-level programming:
+
+* [Pulse (`qiskit.pulse`)](pulse)
+* [Circuit Scheduler (`qiskit.scheduler`)](scheduler)
+
+Other:
+
+* [Circuit and Schedule Assembler (`qiskit.assembler`)](assembler)
+* [Compilation Routines (`qiskit.compiler`)](compiler)
* [Top-level exceptions (`qiskit.exceptions`)](exceptions)
+* [Qobj (`qiskit.qobj`)](qobj)
+* [Utilities (`qiskit.utils`)](utils)
diff --git a/docs/api/qiskit/dev/providers.mdx b/docs/api/qiskit/dev/providers.mdx
index f78eaadea77..0f7ddfa3338 100644
--- a/docs/api/qiskit/dev/providers.mdx
+++ b/docs/api/qiskit/dev/providers.mdx
@@ -115,7 +115,7 @@ It’s worth pointing out that Qiskit’s version support policy doesn’t mean
Set the error message.
-# Writing a New Backend
+## Writing a New Backend
If you have a quantum device or simulator that you would like to integrate with Qiskit you will need to write a backend. A provider is a collection of backends and will provide Qiskit with a method to get available [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") objects. The [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") object provides both information describing a backend and its operation for the [`transpiler`](transpiler#module-qiskit.transpiler "qiskit.transpiler") so that circuits can be compiled to something that is optimized and can execute on the backend. It also provides the [`run()`](qiskit.providers.BackendV2#run "qiskit.providers.BackendV2.run") method which can run the [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") objects and/or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects. This enables users and other Qiskit APIs to get results from executing circuits on devices in a standard fashion regardless of how the backend is implemented. At a high level the basic steps for writing a provider are:
@@ -131,7 +131,7 @@ For a simple example of a provider, see the [qiskit-aqt-provider](https://github
-## Provider
+### Provider
A provider class serves a single purpose: to get backend objects that enable executing circuits on a device or simulator. The expectation is that any required credentials and/or authentication will be handled in the initialization of a provider object. The provider object will then provide a list of backends, and methods to filter and acquire backends (using the provided credentials if required). An example provider class looks like:
@@ -158,7 +158,7 @@ Ensure that any necessary information for authentication (if required) are prese
-## Backend
+### Backend
The backend classes are the core to the provider. These classes are what provide the interface between Qiskit and the hardware or simulator that will execute circuits. This includes providing the necessary information to describe a backend to the compiler so that it can embed and optimize any circuit for the backend. There are 4 required things in every backend object: a [`target`](qiskit.providers.BackendV2#target "qiskit.providers.BackendV2.target") property to define the model of the backend for the compiler, a [`max_circuits`](qiskit.providers.BackendV2#max_circuits "qiskit.providers.BackendV2.max_circuits") property to define a limit on the number of circuits the backend can execute in a single batch job (if there is no limit `None` can be used), a [`run()`](qiskit.providers.BackendV2#run "qiskit.providers.BackendV2.run") method to accept job submissions, and a [`_default_options`](qiskit.providers.BackendV2#_default_options "qiskit.providers.BackendV2._default_options") method to define the user configurable options and their default values. For example, a minimum working example would be something like:
@@ -228,7 +228,9 @@ class Mybackend(Backend):
return MyJob(self. job_handle, job_json, circuit)
```
-### Transpiler Interface
+
+
+### Backend’s Transpiler Interface
The key piece of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") object is how it describes itself to the compiler. This is handled with the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") class which defines a model of a backend for the transpiler. A backend object will need to return a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object from the [`target`](qiskit.providers.BackendV2#target "qiskit.providers.BackendV2.target") attribute which the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function will use as its model of a backend target for compilation.
@@ -330,7 +332,9 @@ This snippet of a backend implementation will now have the [`transpile()`](compi
This way if these two compilation steps are **required** for running or providing efficient output on `Mybackend` the transpiler will be able to perform these custom steps without any manual user input.
-### Run Method
+
+
+### Backend.run Method
Of key importance is the [`run()`](qiskit.providers.BackendV2#run "qiskit.providers.BackendV2.run") method, which is used to actually submit circuits to a device or simulator. The run method handles submitting the circuits to the backend to be executed and returning a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. Depending on the type of backend this typically involves serializing the circuit object into the API format used by a backend. For example, on IBM backends from the `qiskit-ibm-provider` package this involves converting from a quantum circuit and options into a [`qpy`](qpy#module-qiskit.qpy "qiskit.qpy") payload embedded in JSON and submitting that to the IBM Quantum API. Since every backend interface is different (and in the case of the local simulators serialization may not be needed) it is expected that the backend’s [`run`](qiskit.providers.BackendV2#run "qiskit.providers.BackendV2.run") method will handle this conversion.
@@ -352,9 +356,7 @@ def run(self, circuits. **kwargs):
return MyJob(self. job_handle, job_json, circuit)
```
-
-
-### Options
+### Backend Options
There are often several options for a backend that control how a circuit is run. The typical example of this is something like the number of `shots` which is how many times the circuit is to be executed. The options available for a backend are defined using an [`Options`](qiskit.providers.Options "qiskit.providers.Options") object. This object is initially created by the [`_default_options`](qiskit.providers.BackendV2#_default_options "qiskit.providers.BackendV2._default_options") method of a Backend class. The default options returns an initialized [`Options`](qiskit.providers.Options "qiskit.providers.Options") object with all the default values for all the options a backend supports. For example, if the backend supports only supports `shots` the [`_default_options`](qiskit.providers.BackendV2#_default_options "qiskit.providers.BackendV2._default_options") method would look like:
@@ -372,9 +374,9 @@ self.options.set_validator("shots", (1, 4096))
you can refer to the [`set_validator()`](qiskit.providers.Options#set_validator "qiskit.providers.Options.set_validator") documentation for a full list of validation options.
-
+
-## Job
+### Job
The output from the [`run`](qiskit.providers.BackendV2#run "qiskit.providers.BackendV2.run") method is a [`JobV1`](qiskit.providers.JobV1 "qiskit.providers.JobV1") object. Each provider is expected to implement a custom job subclass that defines the behavior for the provider. There are 2 types of jobs depending on the backend’s execution method, either a sync or async. By default jobs are considered async and the expectation is that it represents a handle to the async execution of the circuits submitted with `Backend.run()`. An async job object provides users the ability to query the status of the execution, cancel a running job, and block until the execution is finished. The [`result`](qiskit.providers.JobV1#result "qiskit.providers.JobV1.result") is the primary user facing method which will block until the execution is complete and then will return a [`Result`](qiskit.result.Result "qiskit.result.Result") object with results of the job.
@@ -459,17 +461,13 @@ class MySyncJob(Job):
return JobStatus.DONE
```
-## Primitives
+### Primitives
While not directly part of the provider interface, the [`qiskit.primitives`](primitives#module-qiskit.primitives "qiskit.primitives") module is tightly coupled with providers. Specifically the primitive interfaces, such as `BaseSampler` and `BaseEstimator`, are designed to enable provider implementations to provide custom implementations which are optimized for the provider’s backends. This can include customizations like circuit transformations, additional pre- and post-processing, batching, caching, error mitigation, etc. The concept of the [`qiskit.primitives`](primitives#module-qiskit.primitives "qiskit.primitives") module is to explicitly enable this as the primitive objects are higher level abstractions to produce processed higher level outputs (such as probability distributions and expectation values) that abstract away the mechanics of getting the best result efficiently, to concentrate on higher level applications using these outputs.
For example, if your backends were well suited to leverage [mthree](https://github.com/Qiskit-Partners/mthree/) measurement mitigation to improve the quality of the results, you could implement a provider-specific [`Sampler`](qiskit.primitives.Sampler "qiskit.primitives.Sampler") implementation that leverages the `M3Mitigation` class internally to run the circuits and return quasi-probabilities directly from mthree in the result. Doing this would enable algorithms to get the best results with mitigation applied directly from your backends. You can refer to the documentation in [`qiskit.primitives`](primitives#module-qiskit.primitives "qiskit.primitives") on how to write custom implementations. Also the built-in implementations: [`Sampler`](qiskit.primitives.Sampler "qiskit.primitives.Sampler"), [`Estimator`](qiskit.primitives.Estimator "qiskit.primitives.Estimator"), [`BackendSampler`](qiskit.primitives.BackendSampler "qiskit.primitives.BackendSampler"), and [`BackendEstimator`](qiskit.primitives.BackendEstimator "qiskit.primitives.BackendEstimator") can serve as references/models on how to implement these as well.
-# Migrating between Backend API Versions
-
-
-
-## BackendV1 -> BackendV2
+## Migrating from BackendV1 to BackendV2
The [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") class re-defined user access for most properties of a backend to make them work with native Qiskit data structures and have flatter access patterns. However this means when using a provider that upgrades from [`BackendV1`](qiskit.providers.BackendV1 "qiskit.providers.BackendV1") to [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") existing access patterns will need to be adjusted. It is expected for existing providers to deprecate the old access where possible to provide a graceful migration, but eventually users will need to adjust code. The biggest change to adapt to in [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") is that most of the information accessible about a backend is contained in its [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object and the backend’s attributes often query its [`target`](qiskit.providers.BackendV2#target "qiskit.providers.BackendV2.target") attribute to return information, however in many cases the attributes only provide a subset of information the target can contain. For example, `backend.coupling_map` returns a [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") constructed from the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") accessible in the [`target`](qiskit.providers.BackendV2#target "qiskit.providers.BackendV2.target") attribute, however the target may contain instructions that operate on more than two qubits (which can’t be represented in a [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")) or has instructions that only operate on a subset of qubits (or two qubit links for a two qubit instruction) which won’t be detailed in the full coupling map returned by [`coupling_map`](qiskit.providers.BackendV2#coupling_map "qiskit.providers.BackendV2.coupling_map"). So depending on your use case it might be necessary to look deeper than just the equivalent access with [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2").
diff --git a/docs/api/qiskit/dev/providers_basic_provider.mdx b/docs/api/qiskit/dev/providers_basic_provider.mdx
index eb5dc6f06c2..4054b9af33a 100644
--- a/docs/api/qiskit/dev/providers_basic_provider.mdx
+++ b/docs/api/qiskit/dev/providers_basic_provider.mdx
@@ -26,27 +26,12 @@ from qiskit.providers.basic_provider import BasicProvider
backend = BasicProvider().get_backend('basic_simulator')
```
-## Simulators
-
-| | |
-| ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
-| [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator")(\[provider, target]) | Python implementation of a basic (non-efficient) quantum simulator. |
-
-## Provider
-
-| | |
-| ------------------------------------------------------------------------------------------------------------------ | ----------------------------- |
-| [`BasicProvider`](qiskit.providers.basic_provider.BasicProvider "qiskit.providers.basic_provider.BasicProvider")() | Provider for test simulators. |
-
-## Job Class
-
-| | |
-| --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
-| [`BasicProviderJob`](qiskit.providers.basic_provider.BasicProviderJob "qiskit.providers.basic_provider.BasicProviderJob")(backend, job\_id, result) | BasicProviderJob class. |
-
-## Exceptions
-
-| | |
-| ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- |
-| [`BasicProviderError`](qiskit.providers.basic_provider.BasicProviderError "qiskit.providers.basic_provider.BasicProviderError")(\*message) | Base class for errors raised by the Basic Provider. |
+## Classes
+
+| | |
+| --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator")(\[provider, target]) | Python implementation of a basic (non-efficient) quantum simulator. |
+| [`BasicProvider`](qiskit.providers.basic_provider.BasicProvider "qiskit.providers.basic_provider.BasicProvider")() | Provider for test simulators. |
+| [`BasicProviderJob`](qiskit.providers.basic_provider.BasicProviderJob "qiskit.providers.basic_provider.BasicProviderJob")(backend, job\_id, result) | BasicProviderJob class. |
+| [`BasicProviderError`](qiskit.providers.basic_provider.BasicProviderError "qiskit.providers.basic_provider.BasicProviderError")(\*message) | Base class for errors raised by the Basic Provider. |
diff --git a/docs/api/qiskit/dev/providers_fake_provider.mdx b/docs/api/qiskit/dev/providers_fake_provider.mdx
index 32e80976b8e..60b83fa3b06 100644
--- a/docs/api/qiskit/dev/providers_fake_provider.mdx
+++ b/docs/api/qiskit/dev/providers_fake_provider.mdx
@@ -22,7 +22,7 @@ python_api_name: qiskit.providers.fake_provider
The fake provider module in Qiskit contains fake (simulated) backend classes useful for testing the transpiler and other backend-facing functionality.
-## Example Usage
+### Example Usage
Here is an example of using a simulated backend for transpilation and running.
diff --git a/docs/api/qiskit/dev/providers_models.mdx b/docs/api/qiskit/dev/providers_models.mdx
index d707ddeb624..3f4f7b13266 100644
--- a/docs/api/qiskit/dev/providers_models.mdx
+++ b/docs/api/qiskit/dev/providers_models.mdx
@@ -20,7 +20,7 @@ python_api_name: qiskit.providers.models
Qiskit schema-conformant objects used by the backends and providers.
-## Backend Objects
+## Classes
| | |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
diff --git a/docs/api/qiskit/dev/qiskit.circuit.QuantumCircuit.mdx b/docs/api/qiskit/dev/qiskit.circuit.QuantumCircuit.mdx
index ec24327c5c0..4cfa2058d03 100644
--- a/docs/api/qiskit/dev/qiskit.circuit.QuantumCircuit.mdx
+++ b/docs/api/qiskit/dev/qiskit.circuit.QuantumCircuit.mdx
@@ -153,7 +153,7 @@ python_api_name: qiskit.circuit.QuantumCircuit
### instances
-
+
### layout
diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.AND.mdx b/docs/api/qiskit/dev/qiskit.circuit.library.AND.mdx
index aede3273d58..4a05cb65fbb 100644
--- a/docs/api/qiskit/dev/qiskit.circuit.library.AND.mdx
+++ b/docs/api/qiskit/dev/qiskit.circuit.library.AND.mdx
@@ -75,7 +75,7 @@ python_api_name: qiskit.circuit.library.AND
### instances
-
+
### layout
diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.CDKMRippleCarryAdder.mdx b/docs/api/qiskit/dev/qiskit.circuit.library.CDKMRippleCarryAdder.mdx
index dca1d3fbf82..3aaeb23313f 100644
--- a/docs/api/qiskit/dev/qiskit.circuit.library.CDKMRippleCarryAdder.mdx
+++ b/docs/api/qiskit/dev/qiskit.circuit.library.CDKMRippleCarryAdder.mdx
@@ -121,7 +121,7 @@ python_api_name: qiskit.circuit.library.CDKMRippleCarryAdder
### instances
-
+
### layout
diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.QuantumVolume.mdx b/docs/api/qiskit/dev/qiskit.circuit.library.QuantumVolume.mdx
index d14981c6f12..370f75a9be8 100644
--- a/docs/api/qiskit/dev/qiskit.circuit.library.QuantumVolume.mdx
+++ b/docs/api/qiskit/dev/qiskit.circuit.library.QuantumVolume.mdx
@@ -83,7 +83,7 @@ python_api_name: qiskit.circuit.library.QuantumVolume
### instances
-
+
### layout
diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.RGQFTMultiplier.mdx b/docs/api/qiskit/dev/qiskit.circuit.library.RGQFTMultiplier.mdx
index e30e97a3a1f..08141971733 100644
--- a/docs/api/qiskit/dev/qiskit.circuit.library.RGQFTMultiplier.mdx
+++ b/docs/api/qiskit/dev/qiskit.circuit.library.RGQFTMultiplier.mdx
@@ -84,7 +84,7 @@ python_api_name: qiskit.circuit.library.RGQFTMultiplier
### instances
-
+
### layout
diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.RealAmplitudes.mdx b/docs/api/qiskit/dev/qiskit.circuit.library.RealAmplitudes.mdx
index eba87296d5a..62a528449b7 100644
--- a/docs/api/qiskit/dev/qiskit.circuit.library.RealAmplitudes.mdx
+++ b/docs/api/qiskit/dev/qiskit.circuit.library.RealAmplitudes.mdx
@@ -192,7 +192,7 @@ python_api_name: qiskit.circuit.library.RealAmplitudes
### instances
-
+
### layout
diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.TwoLocal.mdx b/docs/api/qiskit/dev/qiskit.circuit.library.TwoLocal.mdx
index 9fe75fcf131..58f3c27c21d 100644
--- a/docs/api/qiskit/dev/qiskit.circuit.library.TwoLocal.mdx
+++ b/docs/api/qiskit/dev/qiskit.circuit.library.TwoLocal.mdx
@@ -204,7 +204,7 @@ python_api_name: qiskit.circuit.library.TwoLocal
### instances
-
+
### layout
diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.UnitaryOverlap.mdx b/docs/api/qiskit/dev/qiskit.circuit.library.UnitaryOverlap.mdx
index 964bae92ae4..1d094e21faf 100644
--- a/docs/api/qiskit/dev/qiskit.circuit.library.UnitaryOverlap.mdx
+++ b/docs/api/qiskit/dev/qiskit.circuit.library.UnitaryOverlap.mdx
@@ -102,7 +102,7 @@ $$
### instances
-
+
### layout
diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.VBERippleCarryAdder.mdx b/docs/api/qiskit/dev/qiskit.circuit.library.VBERippleCarryAdder.mdx
index 18a64ec6b49..28d3977a4d2 100644
--- a/docs/api/qiskit/dev/qiskit.circuit.library.VBERippleCarryAdder.mdx
+++ b/docs/api/qiskit/dev/qiskit.circuit.library.VBERippleCarryAdder.mdx
@@ -93,7 +93,7 @@ python_api_name: qiskit.circuit.library.VBERippleCarryAdder
### instances
-
+
### layout
diff --git a/docs/api/qiskit/dev/qiskit.quantum_info.Pauli.mdx b/docs/api/qiskit/dev/qiskit.quantum_info.Pauli.mdx
index 9e59b0267c1..5f06ff8f702 100644
--- a/docs/api/qiskit/dev/qiskit.quantum_info.Pauli.mdx
+++ b/docs/api/qiskit/dev/qiskit.quantum_info.Pauli.mdx
@@ -88,13 +88,13 @@ $$
For example
```python
- p = Pauli('-iXYZ')
+ P = Pauli('-iXYZ')
print('P[0] =', repr(P[0]))
print('P[1] =', repr(P[1]))
print('P[2] =', repr(P[2]))
print('P[:] =', repr(P[:]))
- print('P[::-1] =, repr(P[::-1]))
+ print('P[::-1] =', repr(P[::-1]))
```
Initialize the Pauli.
diff --git a/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.mdx b/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.mdx
index 6fa514a6271..dd3162bb2ba 100644
--- a/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.mdx
+++ b/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.mdx
@@ -10,11 +10,9 @@ python_api_name: qiskit.synthesis.unitary.aqc
-# qiskit.synthesis.unitary.aqc
-
-## Approximate Quantum Compiler
+# Approximate Quantum Compiler
@@ -22,7 +20,7 @@ python_api_name: qiskit.synthesis.unitary.aqc
Implementation of Approximate Quantum Compiler as described in the paper \[1].
-### Interface
+## Interface
The main public interface of this module is reached by passing `unitary_synthesis_method='aqc'` to [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile"). This will swap the synthesis method to use `AQCSynthesisPlugin`. The individual classes are:
@@ -36,7 +34,7 @@ The main public interface of this module is reached by passing `unitary_synthesi
| [`DefaultCNOTUnitObjective`](qiskit.synthesis.unitary.aqc.DefaultCNOTUnitObjective "qiskit.synthesis.unitary.aqc.DefaultCNOTUnitObjective")(num\_qubits, cnots) | A naive implementation of the objective function based on CNOT units. |
| [`FastCNOTUnitObjective`](qiskit.synthesis.unitary.aqc.FastCNOTUnitObjective "qiskit.synthesis.unitary.aqc.FastCNOTUnitObjective")(num\_qubits, cnots) | Implementation of objective function and gradient calculator, which is similar to `DefaultCNOTUnitObjective` but several times faster. |
-### Mathematical Detail
+## Mathematical Detail
We are interested in compiling a quantum circuit, which we formalize as finding the best circuit representation in terms of an ordered gate sequence of a target unitary matrix $U\in U(d)$, with some additional hardware constraints. In particular, we look at representations that could be constrained in terms of hardware connectivity, as well as gate depth, and we choose a gate basis in terms of CNOT and rotation gates. We recall that the combination of CNOT and rotation gates is universal in $SU(d)$ and therefore it does not limit compilation.
@@ -127,7 +125,7 @@ Now `approximate_circuit` is a circuit that approximates the target unitary to a
This uses a helper function, [`make_cnot_network`](#qiskit.synthesis.unitary.aqc.make_cnot_network "qiskit.synthesis.unitary.aqc.make_cnot_network").
-#### make\_cnot\_network
+### make\_cnot\_network
Generates a network consisting of building blocks each containing a CNOT gate and possibly some single-qubit ones. This network models a quantum operator in question. Note, each building block has 2 input and outputs corresponding to a pair of qubits. What we actually return here is a chain of indices of qubit pairs shared by every building block in a row.
diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.Commuting2qGateRouter.mdx b/docs/api/qiskit/dev/qiskit.transpiler.passes.Commuting2qGateRouter.mdx
index f736e5a94f1..8cb12073e7b 100644
--- a/docs/api/qiskit/dev/qiskit.transpiler.passes.Commuting2qGateRouter.mdx
+++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.Commuting2qGateRouter.mdx
@@ -8,7 +8,7 @@ python_api_name: qiskit.transpiler.passes.Commuting2qGateRouter
# Commuting2qGateRouter
-
+
Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass")
A class to swap route one or more commuting gates to the coupling map.
@@ -127,7 +127,7 @@ python_api_name: qiskit.transpiler.passes.Commuting2qGateRouter
### run
-
+
Run the pass by decomposing the nodes it applies on.
**Parameters**
@@ -151,7 +151,7 @@ python_api_name: qiskit.transpiler.passes.Commuting2qGateRouter
### swap\_decompose
-
+
Take an instance of `Commuting2qBlock` and map it to the coupling map.
The mapping is done with the swap strategy.
diff --git a/docs/api/qiskit/dev/qiskit.visualization.plot_circuit_layout.mdx b/docs/api/qiskit/dev/qiskit.visualization.plot_circuit_layout.mdx
index b9da79588ee..5741b941f02 100644
--- a/docs/api/qiskit/dev/qiskit.visualization.plot_circuit_layout.mdx
+++ b/docs/api/qiskit/dev/qiskit.visualization.plot_circuit_layout.mdx
@@ -10,14 +10,22 @@ python_api_name: qiskit.visualization.plot_circuit_layout
# qiskit.visualization.plot\_circuit\_layout
-
+
Plot the layout of a circuit transpiled for a given target backend.
**Parameters**
* **circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – Input quantum circuit.
+
* **backend** ([*Backend*](qiskit.providers.Backend "qiskit.providers.Backend")) – Target backend.
- * **view** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Layout view: either ‘virtual’ or ‘physical’.
+
+ * **view** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) –
+
+ How to label qubits in the layout. Options:
+
+ * `"virtual"`: Label each qubit with the index of the virtual qubit that mapped to it.
+ * `"physical"`: Label each qubit with the index of the physical qubit that it corresponds to on the device.
+
* **qubit\_coordinates** (*Sequence*) – An optional sequence input (list or array being the most common) of 2d coordinates for each qubit. The length of the sequence must match the number of qubits on the backend. The sequence should be the planar coordinates in a 0-based square grid where each qubit is located.
**Returns**
diff --git a/docs/api/qiskit/dev/qiskit.visualization.plot_error_map.mdx b/docs/api/qiskit/dev/qiskit.visualization.plot_error_map.mdx
index b23a66a377c..5b04931d035 100644
--- a/docs/api/qiskit/dev/qiskit.visualization.plot_error_map.mdx
+++ b/docs/api/qiskit/dev/qiskit.visualization.plot_error_map.mdx
@@ -10,7 +10,7 @@ python_api_name: qiskit.visualization.plot_error_map
# qiskit.visualization.plot\_error\_map
-
+
Plots the error map of a given backend.
**Parameters**
diff --git a/docs/api/qiskit/dev/qpy.mdx b/docs/api/qiskit/dev/qpy.mdx
index 00626bd45a8..f10c435f19e 100644
--- a/docs/api/qiskit/dev/qpy.mdx
+++ b/docs/api/qiskit/dev/qpy.mdx
@@ -20,7 +20,7 @@ python_api_name: qiskit.qpy
QPY is a binary serialization format for [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") and [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") objects that is designed to be cross-platform, Python version agnostic, and backwards compatible moving forward. QPY should be used if you need a mechanism to save or copy between systems a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") or [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") that preserves the full Qiskit object structure (except for custom attributes defined outside of Qiskit code). This differs from other serialization formats like [OpenQASM](https://github.com/openqasm/openqasm) (2.0 or 3.0) which has a different abstraction model and can result in a loss of information contained in the original circuit (or is unable to represent some aspects of the Qiskit objects) or Python’s [pickle](https://docs.python.org/3/library/pickle.html) which will preserve the Qiskit object exactly but will only work for a single Qiskit version (it is also [potentially insecure](https://docs.python.org/3/library/pickle.html#module-pickle)).
-## Using QPY
+## Basic Usage
Using QPY is defined to be straightforward and mirror the user API of the serializers in Python’s standard library, `pickle` and `json`. There are 2 user facing functions: [`qiskit.qpy.dump()`](#qiskit.qpy.dump "qiskit.qpy.dump") and [`qiskit.qpy.load()`](#qiskit.qpy.load "qiskit.qpy.load") which are used to dump QPY data to a file object and load circuits from QPY data in a file object respectively. For example:
@@ -53,9 +53,9 @@ and then loading that file will return a list with all the circuits
>
> twenty\_new\_bells = qpy.load(fd)
-### API documentation
+## API documentation
-#### load
+### load
Load a QPY binary file
@@ -100,7 +100,7 @@ and then loading that file will return a list with all the circuits
[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") | [*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock")]
-#### dump
+### dump
Write QPY binary data to a file
@@ -164,7 +164,7 @@ and then loading that file will return a list with all the circuits
These functions will raise a custom subclass of [`QiskitError`](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") if they encounter problems during serialization or deserialization.
-#### QpyError
+### QpyError
Errors raised by the qpy module.
@@ -174,7 +174,7 @@ These functions will raise a custom subclass of [`QiskitError`](exceptions#qiski
When a lower-than-maximum target QPY version is set for serialization, but the object to be serialized contains features that cannot be represented in that format, a subclass of [`QpyError`](#qiskit.qpy.QpyError "qiskit.qpy.QpyError") is raised:
-#### UnsupportedFeatureForVersion
+### UnsupportedFeatureForVersion
QPY error raised when the target dump version is too low for a feature that is present in the object to be serialized.
@@ -186,7 +186,7 @@ When a lower-than-maximum target QPY version is set for serialization, but the o
* **target** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the version of QPY that is being used in the serialization.
-#### qiskit.qpy.QPY\_VERSION
+### qiskit.qpy.QPY\_VERSION
The current QPY format version as of this release. This is the default value of the `version` keyword argument on [`qpy.dump()`](#qiskit.qpy.dump "qiskit.qpy.dump") and also the upper bound for accepted values for the same argument. This is also the upper bond on the versions supported by [`qpy.load()`](#qiskit.qpy.load "qiskit.qpy.load").
@@ -196,7 +196,7 @@ When a lower-than-maximum target QPY version is set for serialization, but the o
[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")
-#### qiskit.qpy.QPY\_COMPATIBILITY\_VERSION
+### qiskit.qpy.QPY\_COMPATIBILITY\_VERSION
The current minimum compatibility QPY format version. This is the minimum version that [`qpy.dump()`](#qiskit.qpy.dump "qiskit.qpy.dump") will accept for the `version` keyword argument. [`qpy.load()`](#qiskit.qpy.load "qiskit.qpy.load") will be able to load all released format versions of QPY (up until `QPY_VERSION`).
@@ -206,7 +206,7 @@ When a lower-than-maximum target QPY version is set for serialization, but the o
[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")
-### QPY Compatibility
+## QPY Compatibility
The QPY format is designed to be backwards compatible moving forward. This means you should be able to load a QPY with any newer Qiskit version than the one that generated it. However, loading a QPY file with an older Qiskit version is not supported and may not work.
@@ -214,13 +214,13 @@ For example, if you generated a QPY file using qiskit-terra 0.18.1 you could loa
If a feature being loaded is deprecated in the corresponding qiskit release, QPY will raise a [`QPYLoadingDeprecatedFeatureWarning`](#qiskit.qpy.QPYLoadingDeprecatedFeatureWarning "qiskit.qpy.QPYLoadingDeprecatedFeatureWarning") informing of the deprecation period and how the feature will be internally handled.
-#### QPYLoadingDeprecatedFeatureWarning
+### QPYLoadingDeprecatedFeatureWarning
Visible deprecation warning for QPY loading functions without a stable point in the call stack.
-#### QPY format version history
+### QPY format version history
If you’re planning to load a QPY file between different Qiskit versions knowing which versions were available in a given release are useful. As the QPY is backwards compatible but not forwards compatible you need to ensure a given QPY format version was released in the release you’re calling [`load()`](#qiskit.qpy.load "qiskit.qpy.load") with. The following table lists the QPY versions that were supported in every Qiskit (and qiskit-terra prior to Qiskit 1.0.0) release going back to the introduction of QPY in qiskit-terra 0.18.0.
@@ -329,7 +329,7 @@ The EXPR\_VAR variable has gained a new type code and payload, in addition to th
Notably, this new type-code indexes into pre-defined variables from the circuit header, rather than redefining the variable again in each location it is used.
-#### Changes to EXPRESSION
+### Changes to EXPRESSION
The EXPRESSION type code has a new possible entry, `i`, corresponding to [`expr.Index`](circuit_classical#qiskit.circuit.classical.expr.Index "qiskit.circuit.classical.expr.Index") nodes.
diff --git a/docs/api/qiskit/dev/result.mdx b/docs/api/qiskit/dev/result.mdx
index 1b7700e277d..0c65b7ac2c5 100644
--- a/docs/api/qiskit/dev/result.mdx
+++ b/docs/api/qiskit/dev/result.mdx
@@ -18,12 +18,16 @@ python_api_name: qiskit.result
`qiskit.result`
+## Core classes
+
| | |
| ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| [`Result`](qiskit.result.Result "qiskit.result.Result")(backend\_name, backend\_version, ...\[, ...]) | Model for Results. |
| [`ResultError`](qiskit.result.ResultError "qiskit.result.ResultError")(error) | Exceptions raised due to errors in result output. |
| [`Counts`](qiskit.result.Counts "qiskit.result.Counts")(data\[, time\_taken, creg\_sizes, ...]) | A class to store a counts result from a circuit execution. |
+## Marginalization
+
### marginal\_counts
diff --git a/docs/api/qiskit/dev/scheduler.mdx b/docs/api/qiskit/dev/scheduler.mdx
index 116883c93ca..7e91c9d6086 100644
--- a/docs/api/qiskit/dev/scheduler.mdx
+++ b/docs/api/qiskit/dev/scheduler.mdx
@@ -20,6 +20,8 @@ python_api_name: qiskit.scheduler
A circuit scheduler compiles a circuit program to a pulse program.
+## Core API
+
### ScheduleConfig
@@ -64,9 +66,7 @@ A circuit scheduler compiles a circuit program to a pulse program.
[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule")
-
-
-Pulse scheduling methods.
+## Pulse scheduling methods
### as\_soon\_as\_possible
diff --git a/docs/api/qiskit/dev/synthesis.mdx b/docs/api/qiskit/dev/synthesis.mdx
index 51312c4ad5f..f644d9ea739 100644
--- a/docs/api/qiskit/dev/synthesis.mdx
+++ b/docs/api/qiskit/dev/synthesis.mdx
@@ -765,11 +765,7 @@ $$
1. Shende, Bullock, Markov, *Synthesis of Quantum Logic Circuits*, [arXiv:0406176 \[quant-ph\]](https://arxiv.org/abs/quant-ph/0406176)
-The Approximate Quantum Compiler is available here:
-
-| | |
-| --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
-| [`qiskit.synthesis.unitary.aqc`](qiskit.synthesis.unitary.aqc#module-qiskit.synthesis.unitary.aqc "qiskit.synthesis.unitary.aqc") | Approximate Quantum Compiler (qiskit.synthesis.unitary.aqc) |
+The Approximate Quantum Compiler is available as the module [`qiskit.synthesis.unitary.aqc`](qiskit.synthesis.unitary.aqc#module-qiskit.synthesis.unitary.aqc "qiskit.synthesis.unitary.aqc").
## One-Qubit Synthesis
diff --git a/docs/api/qiskit/dev/transpiler_passes.mdx b/docs/api/qiskit/dev/transpiler_passes.mdx
index 55f2ca89c5b..6b3d78bee8d 100644
--- a/docs/api/qiskit/dev/transpiler_passes.mdx
+++ b/docs/api/qiskit/dev/transpiler_passes.mdx
@@ -154,7 +154,9 @@ The synthesis transpiler plugin documentation can be found in the [`qiskit.trans
| [`HLSConfig`](qiskit.transpiler.passes.HLSConfig "qiskit.transpiler.passes.HLSConfig")(\[use\_default\_on\_unspecified, ...]) | The high-level-synthesis config allows to specify a list of "methods" used by [`HighLevelSynthesis`](qiskit.transpiler.passes.HighLevelSynthesis "qiskit.transpiler.passes.HighLevelSynthesis") transformation pass to synthesize different types of higher-level objects. |
| [`SolovayKitaev`](qiskit.transpiler.passes.SolovayKitaev "qiskit.transpiler.passes.SolovayKitaev")(\*args, \*\*kwargs) | Approximately decompose 1q gates to a discrete basis using the Solovay-Kitaev algorithm. |
-## Post Layout (Post transpile qubit selection)
+## Post Layout
+
+These are post qubit selection.
| | |
| ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
diff --git a/public/api/qiskit/dev/objects.inv b/public/api/qiskit/dev/objects.inv
index 657e75c788dcea8dae66bae702ae1c4631bead94..d18b6c15f5cab6e36604e351cc35fbd72016c7e2 100644
GIT binary patch
delta 59761
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
m`go0@%__VS~8
zNdZsy4;93b43i+|t8wyqxFbFp1inZw0T~o{VBhBE8ReGK=H=mmJK3K50Eo)qS<#J=
z9mF3W82;tXp&m@X#XO4%3m&lYm&R>5gl(fo3{lw(5X2zsNnK#k5W-+#7L34#?6ke=
z_1&Mphn8Esv7K<6mPnRVr71#@GzpptR>-2^&9qS02u)XqmN#EctjZ98HA6QHt&~}C
zUGDI;U=9l9l#?dz`Gvu7#Yn4QCIn|V*af)>UN3oI;(19s`Zvtz^E98lfZtizDpD{b
ze@2KvP5l3SPg0Gp3c!`=9I;IjGEQ^-lr8T@yR$s^|9mI3BD3%7!f=c!&?@shqHzaG^{OzQ9ON=L95C*Soo`$C2wN#ixL&?TY
z+^z=dR`31gQ(yWq5`I(K93p;sc`{hxq5P6J??O7ytv45_C{7uJxa`0e?Qvg#1%Go0
zArj_+3|Qi9`DJyGo3Pes@;6-Tj}s~wi*to>$#JI5bltVZjNbB5pbV%&G7d@f##Jy+
zE~3KNg>EIYb6|AgYef=!MrUR%Y7Ir?Cf98QVfGtY#UldwsrOhUTceE|K2mdCvsb0T
zz1QJVHdh#++F#gz`Sfq^;K`9u;L!A=S!WK>^joBWIo9(2mdeWqc!yIo(N`om>QM
z0|_ig;(gEA=&kLRRGWbg{NBPWeOyh`%*1=U$T2{BB+@$d(0Je_fNw^5*e4{h4#U7Z
zDc|zMRCD8$^D!Rpf&=k|o$htmdg&{e%Qpa=)7fLqWCH7VW=!LU9UR;OBOHn#cwO)r
zZm!9aMfFEObtYQ?4ut2@o*4n1Mt2OCsQ%5mtEX-HAeFMtFV!)&b1b
zu3^an1`PietLK~$5HZg`skSic7ex_7mnO_6>r_~HTgXejNEV`N@GLOAC>Pdj@$Z@}
z?=~#-F$P$>e=R?LGi`M1Aww7sSn|;#|A|_PbTjKmgc9Rp{62acn&)OB2!db(r@Vc&
zbDIl5Ws;8xgXHEj;#@gG`AhsWCK4Fn;{)e;JfiA`HrtI2WFSGo>Kj+76f`l(%TM$3
z#h-dpB!-Oz{QCnn&Bb`ucP
zI`Z-EwI0|q$qU6k2}_b!=@
zz87abA3O004EkNJND#31M`b*cOolD>D%k=V@^`sVuXPzD#_iK8l)UcToIrhTo
z3X(1R3x9uM`kG2|Fo>;jCfv$|rM)n0g4OLN9g9oO^2d+#1&B#oCA4qznI=Efl+&ep
zCk`#|W7VVJG(={lNn$ex3s+Dkq)N6pD6?R#m2hY_N?Ggm8fF3L76h3Bu=Hg4K{G9G
z#TIw#U{)*wd^vFB)VWD`<@_>D(bs<_DESDJyMwElQrK25pmW`L1#wCq2)XhLOx@kE+}4`kZhy%A5~tMH
z-_~BT!#d`KDZoWWPSl#n8O4oN#EqStAzclz)w-cgXd!BY3i1TKEfN^d?$9*mkq`Yk
z-Vae1&cA;-tEK?{;vAwOQqeO97egLb-j~ZdK0f{*7ykeP4tzY@zfYkWVsu$%$1PCo7WXj3AC$ecX0F+2K+b7Msf4f}&1Jm_axLZZy)sqq-+B*`L0_3}|pX
zZfS1a96%-G)mO|QXrG?fTw|j=k?&EtsLU!~z6rP-QeiP;$sDj&bIUH8%ts%%lTk9i|<)8^QuEipjyE+
z8OIUeGwBr=`=e+jKOS^GI5U@I^U|t6*>X{lfaQI63*^v1qm_o1qxe9hlY-XGV1J{X
zq*jA?f1{b8Rsm@H7du|{_KY1JF8t!9M$0~8kfk1}Rs&Qo8z*A*Uf)(a8*KIGewWP?
zUh5{Ln~n8rwK4b>4#CI2*=^eitT&JN>9A;iFVLYl6050}wqf7#FYfYc?11B6oW<2w
z0P$T#D@Qs3-oXwsrEO~Fcx;`+{uWXy3ktV|h1F@EG6;OLqh}ab6hT-`1Ub@`8lUlS
zLgh8iw%DMPV-kxqVb_erC@L71pO4f6&);5=qz_UeNQqsTIx|z>VgHTBQ{H8nUto7$
zqM1Mk{|m_;!ZZsem-H0+Yo153-{46aAkAzxWwbTSHM<{2
zM<{fF7Fvwfre%S1>92lRfYx-VC~>$H!Z&K}DpIW(bFqsw%+|v|t{NtmKCA#Z0LFxt
zUs2K!rNA#rhylSC-bW|4;H5i?+sT6He)@pt~L0}d3xtZag!(`mJxf_NNWv$L67E^=HZCTIbp9vQ4|5W8;rktFHCKC!4hY`oZp`vJ?9zI+W
zK0tx^&Yh!Ii5!RyNx`X5IpipktC7zTC0K75Itd#|=mDvCIz7j@6C5T3pt8tXx#222
zF4g%954pePW9jeu?|?@Y$KR-6#Zi(UhPh4nb1^=kb1ilL1;6%1L>NR1up-JX-4b#m
zLPzQbCvm(y(_99({TU43%I9a+eI_;C(?o%a_=gXJe;CmSG~K<|0|m2>wE+?VJ@_)<
zwm}h?gtGCUH7}u@Bo2)H
zV`&7EIqDBq(3n3m2uA#o1|IJfF8*k*u%Yi?<71BW8Xf2L3r6{w3mD@Kno7=7VMKz_
zeI(*F3)aX!QsiL!=8ftTIxway43ZIDp#sPAiBLG2PmHXwd}Q6HcYmVB-P=JF%wS<;
zphJa`KoBU5Bv_a*5{ZI@kqQkFMl#mOJ(2+9_Jl7PwI?2CpDh`&XD(KUT|b{BES*`1
z;I{FgyX`C8fztt+1q#gz4pd7dK+u@@L4rny1_~x8J6JGT!NzCv@`47N7HNkDD>Ha7
zIOzbwMOVe~RX8C(n19d+`OSwDRA^K=Ll>;zLT8}^43kL^WSEp#prI4Xf(@OS6L4tk
zyof*}C8Gk3h#whfWKeXV5lSKijS`F!G*V8appnthg3cp|7<4{C$1R8)3{Iri9uDKR
zj|pDIo)g?%H)tNGw~9MYZ`Y7^$5{tHiCiu9O{7BR4uMvS#D753^04QNkkulegeWYY
zeJ87hHl8RyxX+q$AHnTCqbkJJ%?LVnzOJITz7EKab+FX}3t{cmjmBwOtEl6&rrQ}^
zXOXPp4Q8rL^^(wAY;H^n93`)(L|j@t0
z&?aDiUp7OsyRjJ^?7=23N#`}Of&JD*26tH#Lw~5ZnqZk7)dWr}XQHUuhs>Dxqmc*v
zVa$@MK1^()*aDHL)6TZZo)Jl#uqbr6F5UDGqeFRUvJ0CHbaYlFR>4qfzOIu7)ebTs!v)$l0p(K?d9
z>yC%@mOo_oHT;&l!T=!mEw?t1^?%b5vFhh*{_u!bP+uB>-D9Uhuu|ICj&;Km%qG~Mlzyv<3rZF17DnVTy?
z07~mXa>&x^EH-cb4~+P$C5C*HNFSqCaf6fzu6K>AxW3T@H~N)TWXEE{y9BvfLVuAa
zk=<(DYwzCH?x(tIBhsWUlAX0IL^sLFSdGG22;1UtYQ#_t*#_JGe&2K%*^zCRANTn&
zORDo-S)A+UpM2_5x?|gv*`fHJCG(CHDMHgtes9`Pa@X&F;p5b4*-o`T6?gwhre9Mi
zPib{{r6nodZyZTV_xsE1b5$3I>wmVz=38Uf>I^*=o~z9~HXq*pc6I&l+jdM?>~Rqz_#x{U4Quf=54aRy8Q=j^yO;v@s;B;
zd&1zysVHl<**Yz&jAOMsA5P|Mk-ubx6`go1@6)eFV_#iSkiPl}0V_5HynnAA1L%s0
z0lqJ+Uc*yyZAq|>Pc2lZ78^ddDc-?)AuTyzr091{Zu6=Ko0nAfA3SFb+9
z_Xob==Jw{dtJ}Amw)aZ9e}5TWm&3->Ie1D|SW!c2p;}mtAXMEE6oL8*Q0P_`#oRE7
z#_gtX+Snw0yRsXv7ql;D0C{>K$J=R3ChEiCW)-6-kD`fJ^nR)Ng{xa?etp^YN7rdL
zgKUKofnq_B%loo8Gy&Y!xnJF7aWPwjk=r1ggFBYjQM-xv5B;q9`+qt+_@3G-7lr|z
z+cfb$xP?tUxrH2f^e;mT@ji1`z+;F$Wm`7xQ|%K!wHRS()yEH*(^VXeoP
zLsDgFI8F^IW_0DK9Di`Vs0{8Z`O*xcO6|=fNad@TfCUN-RFdD=TU7x*s=@+n{%Q*i
zCez>DW?%&bN0JE(dAPthGX6Q-br_{W5R8W-dIkd*eb8VZFczW*5JyQ0it*^c=;6Re
ztAHFk?1I?)Cq@omF;T^Ut%E&mc$vag1q>Rlq9hojZjcef#eaa-2ryn~_4bb}-8pZn
z^p~aKkos_#`76Z5LDq{*}D6jyS6QbXkPGtHkR;q78>Os#6OQBsL=5Vv(q^&MM
z*MPp_ri5W&)PHAUkaUrFr{;Mni2_aNcf}WQJK>guC(l-#*|QlB$wF4bG(=|!wqH-w
zZX*y4As8&%Xh6#)W6=;Q=q=G|Z3d*xh9jbr{&9HovunEc^nCec{qGM&y33CbH`%Go
zwoSX*4YT2Yq~)>sy|uj2VA&wa_2-Z4tK0X#zW?z4_J7~Wzutb`y#M^kS{icOGD@GG
z-D@s((ch2N`P9wEj}P>&DF2m})ljR1xohdgE~PGXFl%zv1M=R5m)uz|4vMjy4+yU{
z8$4*M5xSN`jLJQy$NGFo^5cD>H)Z7yt~Raw`SSYH=i8h7G24~S-FyDBG~8vn`%jS{
z-GPtK=zn4~0`S{CIz^T7@JAyE|M;Kt!?1SDVHnLIj-el7z@MHG|FF?w>AiL
z!F;K^0(zm@k5lSCpwACI*Z}DH@pP`6p!!hp7!*5zCGg>wpF;okD*)d7cDujJz2CM6
zC}vZT=;K|;P!3^W*4#}(8uSPLM
zc-lRd{9$x9^Kd-oWH`|j@fzd7!(&dx3@ut+>>-7=Xl+?P6dZLlP(-lNp}{dmhew1K
z9e*McQFLJbK%&9vwq1c$)|CxFfuTr?&ihSe&4u!J}h|
z7PCsWCk(DDNg&k>teQZ>u_&bTF|Wr1+5ot*xF3@lvNW)Cq|(5$0+a?6h)Wt&FdS*{
zf>B6=ga;oDSTN>jz~E4$!6G7z7LC#AmVe<+x610eN$%kXoyz+m(XgjM3r9OG7Bl>4
zF`=lV$HoJJ9+(>cTU315Z!yWyz5s^%A`h4|2K<5^@e9t7Ul3z{!5Q=mdekp?!+wE`
z`vpAk7sSY4aEAVZ82byx;9rDC{{kKUi}3hgFam&ri~tH|2v9&VK!FDV1r-GpoPRK&
zpyPl74+IJ-5-6CVKmo-91wR-lplG1rh64o_4-|MnP*4#;!3qfqDkdm6K|w)B1qCN8
zD2TYA;06W-5E&GV(4Zh=gF+A-6mWD(4E!^!fAAj>cUe`ZcaWw=*uew>PC{2ShTs$9
zhQ=Vt4++5!5d5bE{3i(x#!3^eKVF(33x-Gnanp#0#!e$-IDQ&YyB$^VJn@LFSs@JG
zeOP{YV-uDid%Ew90dCy&7DCUDSz0F3YA}<>utpfs8E%azJio2s>GshmK0tCSNoxk9NDFrs^vAROV3
z1gt23ga;!15uZQ)K?5I{L`;~WL}J9mlZg>Fm{5$ca8fa%5{bo#%Z^)+s6`mF;1P=;
zUcsUjL9BvBD%Ep);A=CQY=4!30_U)-2|6?*8wtW$*@Rl~V-9*t-I=i$ugNC9K$J}Op4J8Vc;caIuDtl
z=~Sn*Y!9qV@G)7Zvw!U&*0Q)u@A7?K=NY$m({0&oSU?$|3PL@B
zE`1ER(Eg_ZGJmiEN3UWBUQLup!M}hT5ITIop=uDu2SZ4;s!krn@8}ZDL
z1)~Z3P45eV>lFmG(v;-Fz&3l)gyIw&ld>yW&0TnAKO4Z!<~836quOoz40
z_8IKnP&kMOMlwB~KbGmi3bfq>;+YN!n>gyRLbFB#8n#_=fD3I?9Pq$+tH%pQTpb=K
z=ISu%sB6Hjva*ITyTW0-E?b8I`_dsq^!utFG4OHK0LS{WY5=7^tD2!1(bxnXj(^8G
zXjVkl0Ru5vhYWv{)5C_o#TfvxFt0}o1$rGC9_n>~!C&D9*-Fh_P9_)IO1bd;}dddR(!$)C$J{a;Oy0a
zipQBfDiUd8U$*psVfTLGKtDr3AAj5s!@^@Z8
zCh2}JB%AF?)~2&7N>-f>78J6ezTmowsV9CNu`+;>gA(I_%*q4?Y#7gvnr=*wca4`kQWLjcOT^!x?3{@6E>I9+qx!GCAhh=C3KAxow
z*i@!A;4-qc0hr9#I^-_)O7a>_1v+rWh{Er~FfM^=MKK(UW8VP!Z}=X{^z_J}a+;Hz
z{0y=ugR;nuf}Kfr1YkDVF@Nwf$_}2)Dtll&v+Pl+?6O1UWtbf>nPqmstW2}R1+vW!
znVk`K=tx%B!;fw=ura^$pIqG5f`sM8z)%3p$&NczIz#Sp;WHr=XyQ-^4V{zEj_7nw
z+oSXH+8!OrZ9DYyF@HL9pa%mA_Xn@V(be#i2k6V8znq&ipgekR<$v^)q@eofF8z^L
zNm+m!jA!c$hc(8So%cZ3Y%=v$B*U>N4;<{SJcOF=haQOo-5ZhkxE2+BN{l-G&*z^^
z@YceOyxFGvwETRc8sk(h3ej$SkTm>;`f-4~gLsjJu$E5jP+Aw5g#pSZ>Ay!nr
zI#)o$8vORLI5D52Gl8(%=&0g5KiFXuU~FX&98lSDqAY`h2(=6rB;GOz{6Uw7jYeJ?
zdLaDL!3(bB0)K&+hK#M#=-8pP8Ur1S^>p}Pz^CC4r-fJC+L`TO7JOKx5wM>-|8f}}HY;&qLT4%&4dM&z#Zkm0+=!&rmSdB}Aborkj)qZ85VF*=iI
zO-83=tjieOyo^XECDS5}ij^B_L_mV1G3g-<@1dCC%zvrZj6i_38^FR%sNCtHVQAk;$Ath&BN~a*!rVN_=aN6hh+}?9C!#J>|DwEt??yrG|CjfN(LK0n!Rv-g9&tP(dCmT!_VQ2^GKV6c?7wG4myO~WbPBT
z>6c)yY>+!aFn;(LZt6F7W%qn{j2#B{_t(Mkz?v0}CfE>$Sdtk`V=
z2Y=!=g#nA%6!1{IHsPYj$*9nQV`VgGI1HSTLm{9FT(RmR9Qw_;$jN~kuK(~r6&DUC
zCtxC!oRQ%$a)u^C$Qc_BA7^YLbX2kVVWUcehKv&<`_>wj5WKU-!BJmE8f=6?yE445Z$cCb8gAc68k!w!-s8Zbb1Gr_^J
zn~n&KXHGaMo_UCXc*2H*;R%`ugcW4Y0g*ZbeMY3lB#2f@ELvel@)H3V#hXlc1aC4?
z(fiB=Z37tv^X6%A5=kT2}20ACzP#NenV`f29jDHzF
zm|o<^tU8s$dVM&(n2VBN_>Q&NhT5;DqQl*Rf*$G)W@vbuk^)U^Qqs`z)JVmrQX`cC
zN{v+TKx#DO;;GRL9ZZcBXf!oakOQfa0$lJKU|_$Kf(oYsGcb_~%-EbAEebxppGD<>
zPVUs;11ES|$h82w2GRN0C^EdiM}LPWcK0Y8+%S2j0m9^&hP4w#Ap!QGC@kQ<4Fx~A
zYePZC_iQNO;V5zjhxcnJ*u-uP6C*m#zyI@W>C>#Ye
z)u3@PqA-n!jKUNad>LQmpce7ZjR(N@14FSO2p)m;<*DdvL`56p*$k-RsAj}u
zMl>Tf6wS;WcqB6uP*Kc?jz=&fHW9sid$oB!G)UzzK_3cXw6ZkZwDS;ZAFAcWY>Chm
z?P*zcqHc5y){RbOS_6#t`Ei&0eAS-Prc@oy>97Y_n?5=_oPY%fjel#h0vI@Y)<_6Z
z>m*OpMmHYEQ)q9SNr8U{VUh&DgwScU*U#f&z4^N7-AmqU?@dr_p>_;gl&xtg{h~L&
z-b{Oh5*zk(8t>4T9@G7El~49>91sm={uQ*&+dD|_RYADmRZTqmT8LAdDCT1TM4+GW$)WvTJ>SE
zYEG2);FZNTtE#ABVBSH+wS1b7=yM(MxDuZ6*ksGQ_9khi$#Xp$A&y18Q@R!*%q}}t
zO%*BMQwo6|v+|HPE$A45aT;YBV?SkoLXh!y!)OtKRDbE)^o1zOR4W&u+CCogUERFo
zet9I920~R^7sWA&h%LLyh!S&$(2TNui|rfi|R0!xNRKUi*Yx&Pk+k#o^S2fmu+p<-P~fCJ!C(qN@{H`
zOdAjMcAuqX@Uc6zzL*cgvw^{Y&~`592Xf=b*>lpV4mD3
zQh(}5C-n?U%f5YT2%{_L!D)JvU3Q<2u}~07DeFUfENY;#`(hr9^J(YVd!&O54hqy3_h{T2Kj7=%Fx+ngykjY5ILVxze
zBwyNL2kQmxq9ho%AG83lj?m_%dP1AX-4!~J!+oIx*wq=@xIk}cV|%+p8$aA1+R&~J
z(MIL;h&Bh^CEAQspJ=nVJ4G9rUHf3oADf1iHQC$zq|e@ki
zL?wD^C$h7vw$Y)!+9n8e)(#G5)PLy@bscnc&}q|>gM`iF86|9Na+t8OJ>$gJX=%ef
zI1GPxn_b?e+rP4QuUC4=!j;+^TxbRaXnSK=nUW5Y$-K167^3?UoG)YAox43Y^NJ<5)*=Xn%e?Zf4AW
zY_pTTAH`A71nJwbHSxa!Xa3b8u~Lo@dJbg$D|Xtivve~!p@4eDkEo~0tNhiv;?(OQ
zEgzbYdaraS%5H#RwfevPW`Abj!ZMz_9ms5&jcdC4Doe_Kjwd-x^F-mr^Ob1zTw&c#
zYgP_!WW{+EvE;1yv2SO%94-*^$t&4}vS+|wfg^r@HqtI}&I1Qud$oPccGEq$;|7Z9
zw~jp&)88&P!@sVJ<9)83oip1z4Y!?v*M6k}P^=F4z6Y%?(<*6Sdw$^
zU~vePny(JoI_9gxRKvgAcOi$FW>W{(hdjG2i+Z>i$XiEBu^vi+4pije
zv-exY-u^fh$L!c{kZTQAfn6Gb#4E%y4c3c;2&^6lPq3CgAG0s*D$d(hqBp~CL!!C(
zY;gF?Bx#0{eUgM9#$$akSu+^B&vYso-(bsTOVTD)JUymW7Q?HcFg%#Ha|fHHkJ;GX
z4bYwQ{Z1VM_)n`tIJld5dXvGuJ0d-O{%4b*XWwtk9ns$B4w$h>`j5I>MQoGw)Z~Ic
z^7+FwlODbu1JCnclRmx|e=fQ{^w+kZ28V5*4Gs?u+aBxSuw*&e4s8E>AqI4WPX?+4F2w;Iw9>~
z8({k*d*0&%n%{~;arw_*_GDk@wZ8c4mpzxRjG`-#fRGYhe`_Kn^GVfBX}SkhOvY5Eu)qCcyw$!)8T28U+yQ?DA?`W_8w=yR7^broyKjaGG!MO!PDIair+%`i
zJ9wy_Wb)0CtwfV#Gtbkmo7XX?n^vs(rWvm4a^2}Ac#`{-erx1@1p=7$}HPGM?vhkwxfC|^}=pJ|1h=J`CrPAMNS*9;^vJp_Q0&y
zDt6jy_Ta}4g?cx~*6wUzB}fP6XB;|G<>~|cjSczBe`Wf#)po;#3I;dGDCI7%zFY@0
z9qh^>^{ELV{$Q?kl1;9bWHzqa!S3YJNkGmbA+(_
z({y#Skk$o4l8)I77n(iH>bbjzBGaz$p*Y$!
zyh_ehCVDQ#8fWxgd_uAr_n)}Sugl_;mE)yElk~+P1&st+`R|h%#v%eQj*~scC`|88
zbAhRsrrAir>ve26#}zvs%%*Pk%{ySgjusSh|D`b#TrmpZPe-OSn*5%3*~BOYn#X4x
zNeozvq*uprwVretLCdDzSpHCpR%P_!GW`hA-E1E?B
zx%wNE7Q)Q2NdEldH&`0xoBhO37IP
z2a}}9@B#a?mCAbo2Vc{&%(L>>lNZcJ0Zo%$%&G$aypsyeK?42OlTFQa0WXuo%{>Lz
zeX;$EvjxsT0Rf(~M$bJ01ij0DWV46SRsny%{rN}sydOiU9A1R?8Vd+{%JZQh^7DEi
z)}YrLju1m`#i%jl98;2B7ja#By`jYE<%SjNr6y$RWfo}F>jN&>eZI@q^Zno0>Y#1K
zp1fKamv+b@v~&;awJNBE_b-Xvz%fm&f+JfX0hQKv&blMSzHoTS**C6j{AT1
z-t<56`tjs`LDv-0!lQ?UcDY||}JXr7uhQ$$EQmsmqOFGoI>12M|6++d1E
zcLvvs&Pz!}XMt6slMn*YIRx6!*%*JaU@gpJtMbw%dER>b5{vP|mH6eB;iJ~zMGNqZ
z)pyC#JHGB7x9BceaesH-?}vfoYQHbG_&4lsOD+{t4K4^s7*1}vMx1`I~S)@{GRq7&n5e5IaKP22^H{#e=mOnd?iD~
zZ4B&-7#6yNL4N(hqBk$ZUb-N?Z-IB!g7B6F)&&dEcPj|5RcOts_s8zuD_9ki0SL_3
z#Au01Vq%I?#Kg)Kgi0T)2h|CI941$IYM59NF-#mREld=E6eb3t5+*KK2>_(-2qw@c1G7p6xf!$NDit)$A~1k?@pl+avmRu!>dg
z@PMOrw<|G$wFWxs4X_d@dP51(%MDA?
zOHGK=%Pf$o*9V4RWygFn&-RQy&{KGd=b}e<#-7*t0*7=ib24Y#ah#GfIHL~U6r8rX
z&=H$a=W6y_=3hPC
zWvcPAWNA7OB}3B`H)@h{*!LAWBqGd
zmU$DJLh^81a;bQ7aY7)nadV61j{;b@OvmgUyeXkk&-ucmT`RVkLj1YcUDrYjNTdJ|AwgV^x&z
z(rsOU(WGU>AYe+^u!baTGRh@vva=-Ya3e~>4rjO$HeF&!*kmUqY;xfOGN~v5nM@J^
znVhhI#uf8lx_fpo{g^g5{N-=}RdRlfJ(yvCq1ZE6S(-H|0m+(tV#S)=9KkxAh|#OV
z6{cKGhj4$jn%tCFO(s~YCJ`Z3lSiOblTj+v%jciZNnIpApMT1T6?>eOf9y#RKu8>=
zXZ8^&K~I)ay8I{<%Dn~qfY>8Zg06~t2j0;rK_8_32J48Fpa=0iitwlu17(vRPWw!`
zJX<1m8zjPkDA8MJ0^!>pEhT>2yNC|J>E?o+fYX23xQ@VfS=<@e-Z47_+ZSo4V7tQW
z7;I1CI|th*b_a2FJQhviY{%*mW-AVbO!JdDN8~eSw5n%*iHtQzme8%{j!>wxQ+#F4
z{HPRXHn#R=GEi(YSA@D|R<@k3_xXMEK6bp!d$!_G$mBGcbL2F0M$2jDm&i$TWC=NG
z?g)S7G&{wY)69>`X=Y=~X(j{ZG;>ABX=a7xv`%+7**<-SR5TR^0C}1jtq`e93}S^$
zY#d>zv@v>6$(b^kT)6>RggvvtV*dK)_1uVmJ?Hx!_>H{NkV(Xox(fjjy^~oaf2RkGj=+EE
ziMUH}dc)})eD1__6F#Sy9fs32yz6j!L3JWdPPjX9QW71DlablQIC-JY#>p<|cAOsI
z9nd#%5A==O1$~R}gT6^Sp>NCeLf>M$p>NCfL*Jr1qHizJ6Mb8#EBY4M7kv|TMo!i;
ztD1M5CEGH|k5wJxfCYz+w$Gxr=qud*S
zV!PbYuk!+JUDEvy{7ZDggBS9yc<^PZ4tekg@0PPe@jYXGy=j=h;LQG3vxR@USe;GY
zd+E%q4$E>Os*kc9;dV>9JB*%4XC^xzod?&oPD4pqXOSpI=VOZGCQl!VrX_R}Q@>`-
zYsfxkX>~3$hHL^L5e`VC4l1bkw45byE^X0U%fWXGB_oZ7a0I!P~Jf#Bk|`6D%N`@)yH)2VocJ6#hA
z+jfwvXWJJ{#x^rky*4o73qRu-Ffk1T&fMwTg?Od=^0
z0~eOX9w{%&6TZk?F2zgD<(NotmU~>;S)O3xvv`>jv}hqATC8F@TKo)AHkMcSbyg0e
zV)sc%exEZgo1-w~^jy6L!7$;5{fSU;*f*Y(NhjkpO}fe!ci3T$%EP|Vau0jL(0$ku
zvI7YFA?gXj9>HD0CcS?vvk%jycBK5(@)#^n)`}q_VU4k{C`>96^%e+>&@9if3WTL$Zel(3eIVZEpx*0GXUOI5Mv
z31cnP#+oIMb+kg(LXp5H8PBB=NP#NQ(~D=0I4!VGE!K#m6(D~+t$22V+3ulJif43Q
zYe!Bep0TBEoOdemrpcr}e`v}cx7g={ngIyRZ0Cw4)YMfbd23f$Sqdxmag%VO