qiskit 1.3.0b1__cp39-abi3-win32.whl → 1.3.0rc2__cp39-abi3-win32.whl

qiskit/circuit/library/__init__.py

@@ -36,7 +36,11 @@ For example, to append a multi-controlled CNOT:
    circuit.append(gate, [0, 1, 4, 2, 3])
    circuit.draw('mpl')
 
-The library is organized in several sections.
+The library is organized in several sections. The function
+:func:`.get_standard_gate_name_mapping` allows you to see the available standard gates and operations.
+
+.. autofunction:: get_standard_gate_name_mapping
+
 
 Standard gates
 ==============
@@ -56,7 +60,7 @@ For example:
     print(gate.power(1/2).to_matrix())  # √X gate
     print(gate.control(1).to_matrix())  # CX (controlled X) gate
 
-.. parsed-literal::
+.. code-block:: text
 
     [[0.+0.j 1.+0.j]
      [1.+0.j 0.+0.j]]
@@ -126,6 +130,7 @@ For example:
    ZGate
    GlobalPhaseGate
 
+
 Standard Directives
 ===================
 
@@ -152,15 +157,15 @@ set the amount of qubits involved at instantiation time.
 
 .. code-block::
 
-    from qiskit.circuit.library import Diagonal
+    from qiskit.circuit.library import DiagonalGate
 
-    diagonal = Diagonal([1, 1])
+    diagonal = DiagonalGate([1, 1j])
     print(diagonal.num_qubits)
 
-    diagonal = Diagonal([1, 1, 1, 1])
+    diagonal = DiagonalGate([1, 1, 1, -1])
     print(diagonal.num_qubits)
 
-.. parsed-literal::
+.. code-block:: text
 
     1
     2
@@ -181,6 +186,7 @@ set the amount of qubits involved at instantiation time.
    GRX
    GRY
    GRZ
+   MCMTGate
    MCPhaseGate
    MCXGate
    MCXGrayCode
@@ -210,9 +216,15 @@ or of a set of qubit states.
    :template: autosummary/class_no_inherited_members.rst
 
    AND
+   AndGate
    OR
+   OrGate
    XOR
+   BitwiseXorGate
+   random_bitwise_xor
    InnerProduct
+   InnerProductGate
+
 
 Basis Change Circuits
 =====================
@@ -268,6 +280,9 @@ Adders
    CDKMRippleCarryAdder
    VBERippleCarryAdder
    WeightedAdder
+   ModularAdderGate
+   HalfAdderGate
+   FullAdderGate
 
 Multipliers
 -----------
@@ -278,6 +293,7 @@ Multipliers
 
    HRSCumulativeMultiplier
    RGQFTMultiplier
+   MultiplierGate
 
 Comparators
 -----------
@@ -309,12 +325,16 @@ Other arithmetic functions
 Particular Quantum Circuits
 ===========================
 
+The following gates and quantum circuits define specific
+quantum circuits of interest:
+
 .. autosummary::
    :toctree: ../stubs/
    :template: autosummary/class_no_inherited_members.rst
 
    FourierChecking
    GraphState
+   GraphStateGate
    HiddenLinearFunction
    IQP
    QuantumVolume
@@ -325,10 +345,42 @@ Particular Quantum Circuits
    HamiltonianGate
    UnitaryOverlap
 
+For circuits that have a well-defined structure it is preferrable
+to use the following functions to construct them:
+
+.. autosummary::
+   :toctree: ../stubs/
+   :template: autosummary/class_no_inherited_members.rst
+
+   fourier_checking
+   hidden_linear_function
+   iqp
+   random_iqp
+   quantum_volume
+   phase_estimation
+   grover_operator
+   unitary_overlap
+
 
 N-local circuits
 ================
 
+The following functions return a parameterized :class:`.QuantumCircuit` to use as ansatz in
+a broad set of variational quantum algorithms:
+
+.. autosummary::
+   :toctree: ../stubs/
+   :template: autosummary/class_no_inherited_members.rst
+
+   n_local
+   efficient_su2
+   real_amplitudes
+   pauli_two_design
+   excitation_preserving
+   qaoa_ansatz
+   hamiltonian_variational_ansatz
+   evolved_operator_ansatz
+
 These :class:`~qiskit.circuit.library.BlueprintCircuit` subclasses are used
 as parameterized models (a.k.a. ansatzes or variational forms) in variational algorithms.
 They are heavily used in near-term algorithms in e.g. Chemistry, Physics or Optimization.
@@ -350,6 +402,17 @@ They are heavily used in near-term algorithms in e.g. Chemistry, Physics or Opti
 Data encoding circuits
 ======================
 
+The following functions return a parameterized :class:`.QuantumCircuit` to use as data
+encoding circuits in a series of variational quantum algorithms:
+
+.. autosummary::
+   :toctree: ../stubs/
+   :template: autosummary/class_no_inherited_members.rst
+
+   pauli_feature_map
+   z_feature_map
+   zz_feature_map
+
 These :class:`~qiskit.circuit.library.BlueprintCircuit` encode classical
 data in quantum states and are used as feature maps for classification.
 
@@ -360,6 +423,17 @@ data in quantum states and are used as feature maps for classification.
    PauliFeatureMap
    ZFeatureMap
    ZZFeatureMap
+
+
+Data preparation circuits
+=========================
+
+The following operations are used for state preparation:
+
+.. autosummary::
+   :toctree: ../stubs/
+   :template: autosummary/class_no_inherited_members.rst
+
    StatePreparation
    Initialize
 
@@ -500,6 +574,7 @@ from .generalized_gates import (
     Permutation,
     PermutationGate,
     GMS,
+    MCMTGate,
     MSGate,
     GR,
     GRX,
@@ -520,12 +595,21 @@ from .pauli_evolution import PauliEvolutionGate
 from .hamiltonian_gate import HamiltonianGate
 from .boolean_logic import (
     AND,
+    AndGate,
     OR,
+    OrGate,
     XOR,
+    BitwiseXorGate,
+    random_bitwise_xor,
     InnerProduct,
+    InnerProductGate,
 )
 from .basis_change import QFT, QFTGate
 from .arithmetic import (
+    ModularAdderGate,
+    HalfAdderGate,
+    FullAdderGate,
+    MultiplierGate,
     FunctionalPauliRotations,
     LinearPauliRotations,
     PiecewiseLinearPauliRotations,
@@ -545,28 +629,40 @@ from .arithmetic import (
 )
 
 from .n_local import (
+    n_local,
     NLocal,
     TwoLocal,
+    pauli_two_design,
     PauliTwoDesign,
+    real_amplitudes,
     RealAmplitudes,
+    efficient_su2,
     EfficientSU2,
+    hamiltonian_variational_ansatz,
+    evolved_operator_ansatz,
     EvolvedOperatorAnsatz,
+    excitation_preserving,
     ExcitationPreserving,
+    qaoa_ansatz,
     QAOAAnsatz,
 )
 from .data_preparation import (
+    z_feature_map,
+    zz_feature_map,
+    pauli_feature_map,
     PauliFeatureMap,
     ZFeatureMap,
     ZZFeatureMap,
     StatePreparation,
     Initialize,
 )
-from .quantum_volume import QuantumVolume
-from .fourier_checking import FourierChecking
-from .graph_state import GraphState
-from .hidden_linear_function import HiddenLinearFunction
-from .iqp import IQP
-from .phase_estimation import PhaseEstimation
-from .grover_operator import GroverOperator
+from .quantum_volume import QuantumVolume, quantum_volume
+from .fourier_checking import FourierChecking, fourier_checking
+from .graph_state import GraphState, GraphStateGate
+from .hidden_linear_function import HiddenLinearFunction, hidden_linear_function
+from .iqp import IQP, iqp, random_iqp
+from .phase_estimation import PhaseEstimation, phase_estimation
+from .grover_operator import GroverOperator, grover_operator
 from .phase_oracle import PhaseOracle
-from .overlap import UnitaryOverlap
+from .overlap import UnitaryOverlap, unitary_overlap
+from .standard_gates import get_standard_gate_name_mapping

qiskit/circuit/library/arithmetic/__init__.py

@@ -21,7 +21,14 @@ from .polynomial_pauli_rotations import PolynomialPauliRotations
 from .weighted_adder import WeightedAdder
 from .quadratic_form import QuadraticForm
 from .linear_amplitude_function import LinearAmplitudeFunction
-from .adders import VBERippleCarryAdder, CDKMRippleCarryAdder, DraperQFTAdder
+from .adders import (
+    VBERippleCarryAdder,
+    CDKMRippleCarryAdder,
+    DraperQFTAdder,
+    ModularAdderGate,
+    HalfAdderGate,
+    FullAdderGate,
+)
 from .piecewise_chebyshev import PiecewiseChebyshev
-from .multipliers import HRSCumulativeMultiplier, RGQFTMultiplier
+from .multipliers import HRSCumulativeMultiplier, RGQFTMultiplier, MultiplierGate
 from .exact_reciprocal import ExactReciprocal

qiskit/circuit/library/arithmetic/adders/__init__.py

@@ -15,3 +15,4 @@
 from .cdkm_ripple_carry_adder import CDKMRippleCarryAdder
 from .draper_qft_adder import DraperQFTAdder
 from .vbe_ripple_carry_adder import VBERippleCarryAdder
+from .adder import ModularAdderGate, HalfAdderGate, FullAdderGate

qiskit/circuit/library/arithmetic/adders/adder.py

@@ -12,13 +12,16 @@
 
 """Compute the sum of two equally sized qubit registers."""
 
-from qiskit.circuit import QuantumCircuit
+from __future__ import annotations
+
+from qiskit.circuit import QuantumCircuit, Gate
+from qiskit.utils.deprecation import deprecate_func
 
 
 class Adder(QuantumCircuit):
     r"""Compute the sum of two equally sized qubit registers.
 
-    For two registers :math:`|a\rangle_n` and :math:|b\rangle_n` with :math:`n` qubits each, an
+    For two registers :math:`|a\rangle_n` and :math:`|b\rangle_n` with :math:`n` qubits each, an
     adder performs the following operation
 
     .. math::
@@ -39,6 +42,16 @@ class Adder(QuantumCircuit):
 
     """
 
+    @deprecate_func(
+        since="1.3",
+        additional_msg=(
+            "Use the adder gates provided in qiskit.circuit.library.arithmetic instead. "
+            "The gate type depends on the adder kind: fixed, half, full are represented by "
+            "ModularAdderGate, HalfAdderGate, FullAdderGate, respectively. For different adder "
+            "implementations, see https://docs.quantum.ibm.com/api/qiskit/synthesis.",
+        ),
+        pending=True,
+    )
     def __init__(self, num_state_qubits: int, name: str = "Adder") -> None:
         """
         Args:
@@ -56,3 +69,142 @@ class Adder(QuantumCircuit):
             The number of state qubits.
         """
         return self._num_state_qubits
+
+
+class HalfAdderGate(Gate):
+    r"""Compute the sum of two equally-sized qubit registers, including a carry-out bit.
+
+    For two registers :math:`|a\rangle_n` and :math:`|b\rangle_n` with :math:`n` qubits each, an
+    adder performs the following operation
+
+    .. math::
+
+        |a\rangle_n |b\rangle_n \mapsto |a\rangle_n |a + b\rangle_{n + 1}.
+
+    The quantum register :math:`|a\rangle_n` (and analogously :math:`|b\rangle_n`)
+
+    .. math::
+
+        |a\rangle_n = |a_0\rangle \otimes \cdots \otimes |a_{n - 1}\rangle,
+
+    for :math:`a_i \in \{0, 1\}`, is associated with the integer value
+
+    .. math::
+
+        a = 2^{0}a_{0} + 2^{1}a_{1} + \cdots + 2^{n - 1}a_{n - 1}.
+
+    """
+
+    def __init__(self, num_state_qubits: int, label: str | None = None) -> None:
+        """
+        Args:
+            num_state_qubits: The number of qubits in each of the registers.
+            name: The name of the circuit.
+        """
+        if num_state_qubits < 1:
+            raise ValueError("Need at least 1 state qubit.")
+
+        super().__init__("HalfAdder", 2 * num_state_qubits + 1, [], label=label)
+        self._num_state_qubits = num_state_qubits
+
+    @property
+    def num_state_qubits(self) -> int:
+        """The number of state qubits, i.e. the number of bits in each input register.
+
+        Returns:
+            The number of state qubits.
+        """
+        return self._num_state_qubits
+
+
+class ModularAdderGate(Gate):
+    r"""Compute the sum modulo :math:`2^n` of two :math:`n`-sized qubit registers.
+
+    For two registers :math:`|a\rangle_n` and :math:`|b\rangle_n` with :math:`n` qubits each, an
+    adder performs the following operation
+
+    .. math::
+
+        |a\rangle_n |b\rangle_n \mapsto |a\rangle_n |a + b \text{ mod } 2^n\rangle_n.
+
+    The quantum register :math:`|a\rangle_n` (and analogously :math:`|b\rangle_n`)
+
+    .. math::
+
+        |a\rangle_n = |a_0\rangle \otimes \cdots \otimes |a_{n - 1}\rangle,
+
+    for :math:`a_i \in \{0, 1\}`, is associated with the integer value
+
+    .. math::
+
+        a = 2^{0}a_{0} + 2^{1}a_{1} + \cdots + 2^{n - 1}a_{n - 1}.
+
+    """
+
+    def __init__(self, num_state_qubits: int, label: str | None = None) -> None:
+        """
+        Args:
+            num_state_qubits: The number of qubits in each of the registers.
+            name: The name of the circuit.
+        """
+        if num_state_qubits < 1:
+            raise ValueError("Need at least 1 state qubit.")
+
+        super().__init__("ModularAdder", 2 * num_state_qubits, [], label=label)
+        self._num_state_qubits = num_state_qubits
+
+    @property
+    def num_state_qubits(self) -> int:
+        """The number of state qubits, i.e. the number of bits in each input register.
+
+        Returns:
+            The number of state qubits.
+        """
+        return self._num_state_qubits
+
+
+class FullAdderGate(Gate):
+    r"""Compute the sum of two :math:`n`-sized qubit registers, including carry-in and -out bits.
+
+    For two registers :math:`|a\rangle_n` and :math:`|b\rangle_n` with :math:`n` qubits each, an
+    adder performs the following operation
+
+    .. math::
+
+        |c_{\text{in}}\rangle_1 |a\rangle_n |b\rangle_n
+        \mapsto |a\rangle_n |c_{\text{in}} + a + b \rangle_{n + 1}.
+
+    The quantum register :math:`|a\rangle_n` (and analogously :math:`|b\rangle_n`)
+
+    .. math::
+
+        |a\rangle_n = |a_0\rangle \otimes \cdots \otimes |a_{n - 1}\rangle,
+
+    for :math:`a_i \in \{0, 1\}`, is associated with the integer value
+
+    .. math::
+
+        a = 2^{0}a_{0} + 2^{1}a_{1} + \cdots + 2^{n - 1}a_{n - 1}.
+
+    """
+
+    def __init__(self, num_state_qubits: int, label: str | None = None) -> None:
+        """
+        Args:
+            num_state_qubits: The number of qubits in each of the registers.
+            name: The name of the circuit.
+        """
+        if num_state_qubits < 1:
+            raise ValueError("Need at least 1 state qubit.")
+
+        super().__init__("FullAdder", 2 * num_state_qubits + 2, [], label=label)
+        self._num_state_qubits = num_state_qubits
+
+    @property
+    def num_state_qubits(self) -> int:
+        """The number of state qubits, i.e. the number of bits in each input register.
+
+        Returns:
+            The number of state qubits.
+        """
+        return self._num_state_qubits

qiskit/circuit/library/arithmetic/adders/cdkm_ripple_carry_adder.py

@@ -12,8 +12,7 @@
 
 """Compute the sum of two qubit registers using ripple-carry approach."""
 
-from qiskit.circuit import QuantumCircuit, QuantumRegister, AncillaRegister
-
+from qiskit.synthesis.arithmetic import adder_ripple_c04
 from .adder import Adder
 
 
@@ -23,7 +22,7 @@ class CDKMRippleCarryAdder(Adder):
     As an example, a ripple-carry adder circuit that performs addition on two 3-qubit sized
     registers with a carry-in bit (``kind="full"``) is as follows:
 
-    .. parsed-literal::
+    .. code-block:: text
 
                 ┌──────┐                                     ┌──────┐
          cin_0: ┤2     ├─────────────────────────────────────┤2     ├
@@ -54,7 +53,7 @@ class CDKMRippleCarryAdder(Adder):
 
     The circuit diagram for the fixed-point adder (``kind="fixed"``) on 3-qubit sized inputs is
 
-    .. parsed-literal::
+    .. code-block:: text
 
                 ┌──────┐┌──────┐                ┌──────┐┌──────┐
            a_0: ┤0     ├┤2     ├────────────────┤2     ├┤0     ├
@@ -75,6 +74,21 @@ class CDKMRippleCarryAdder(Adder):
     It has one less qubit than the full-adder since it doesn't have the carry-out, but uses
     a helper qubit instead of the carry-in, so it only has one less qubit, not two.
 
+    .. seealso::
+
+        The following generic gate objects perform additions, like this circuit class,
+        but allow the compiler to select the optimal decomposition based on the context.
+        Specific implementations can be set via the :class:`.HLSConfig`, e.g. this circuit
+        can be chosen via ``Adder=["ripple_c04"]``.
+
+        :class:`.ModularAdderGate`: A generic inplace adder, modulo :math:`2^n`. This
+            is functionally equivalent to ``kind="fixed"``.
+
+        :class:`.AdderGate`: A generic inplace adder. This
+            is functionally equivalent to ``kind="half"``.
+
+        :class:`.FullAdderGate`: A generic inplace adder, with a carry-in bit. This
+            is functionally equivalent to ``kind="full"``.
 
     **References:**
 
@@ -102,58 +116,8 @@ class CDKMRippleCarryAdder(Adder):
         Raises:
             ValueError: If ``num_state_qubits`` is lower than 1.
         """
-        if num_state_qubits < 1:
-            raise ValueError("The number of qubits must be at least 1.")
-
         super().__init__(num_state_qubits, name=name)
+        circuit = adder_ripple_c04(num_state_qubits, kind)
 
-        if kind == "full":
-            qr_c = QuantumRegister(1, name="cin")
-            self.add_register(qr_c)
-        else:
-            qr_c = AncillaRegister(1, name="help")
-
-        qr_a = QuantumRegister(num_state_qubits, name="a")
-        qr_b = QuantumRegister(num_state_qubits, name="b")
-        self.add_register(qr_a, qr_b)
-
-        if kind in ["full", "half"]:
-            qr_z = QuantumRegister(1, name="cout")
-            self.add_register(qr_z)
-
-        if kind != "full":
-            self.add_register(qr_c)
-
-        # build carry circuit for majority of 3 bits in-place
-        # corresponds to MAJ gate in [1]
-        qc_maj = QuantumCircuit(3, name="MAJ")
-        qc_maj.cx(0, 1)
-        qc_maj.cx(0, 2)
-        qc_maj.ccx(2, 1, 0)
-        maj_gate = qc_maj.to_gate()
-
-        # build circuit for reversing carry operation
-        # corresponds to UMA gate in [1]
-        qc_uma = QuantumCircuit(3, name="UMA")
-        qc_uma.ccx(2, 1, 0)
-        qc_uma.cx(0, 2)
-        qc_uma.cx(2, 1)
-        uma_gate = qc_uma.to_gate()
-
-        circuit = QuantumCircuit(*self.qregs, name=name)
-
-        # build ripple-carry adder circuit
-        circuit.append(maj_gate, [qr_a[0], qr_b[0], qr_c[0]])
-
-        for i in range(num_state_qubits - 1):
-            circuit.append(maj_gate, [qr_a[i + 1], qr_b[i + 1], qr_a[i]])
-
-        if kind in ["full", "half"]:
-            circuit.cx(qr_a[-1], qr_z[0])
-
-        for i in reversed(range(num_state_qubits - 1)):
-            circuit.append(uma_gate, [qr_a[i + 1], qr_b[i + 1], qr_a[i]])
-
-        circuit.append(uma_gate, [qr_a[0], qr_b[0], qr_c[0]])
-
+        self.add_register(*circuit.qregs)
         self.append(circuit.to_gate(), self.qubits)

qiskit/circuit/library/arithmetic/adders/draper_qft_adder.py

@@ -31,7 +31,7 @@ class DraperQFTAdder(Adder):
     As an example, a non-fixed_point QFT adder circuit that performs addition on two 2-qubit sized
     registers is as follows:
 
-    .. parsed-literal::
+    .. code-block:: text
 
          a_0:   ─────────■──────■────────────────────────■────────────────
                          │      │                        │
@@ -44,6 +44,19 @@ class DraperQFTAdder(Adder):
         cout_0: ┤2     ├────────────────────────■────────■───────┤2      ├
                 └──────┘                                         └───────┘
 
+    .. seealso::
+
+        The following generic gate objects perform additions, like this circuit class,
+        but allow the compiler to select the optimal decomposition based on the context.
+        Specific implementations can be set via the :class:`.HLSConfig`, e.g. this
+        circuit can be chosen via ``Adder=["qft_d00"]``.
+
+        :class:`.ModularAdderGate`: A generic inplace adder, modulo :math:`2^n`. This
+            is functionally equivalent to ``kind="fixed"``.
+
+        :class:`.AdderGate`: A generic inplace adder. This
+            is functionally equivalent to ``kind="half"``.
+
     **References:**
 
     [1] T. G. Draper, Addition on a Quantum Computer, 2000.