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

qiskit/circuit/library/boolean_logic/quantum_and.py

@@ -1,6 +1,6 @@
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2020.
+# (C) Copyright IBM 2020, 2024.
 #
 # This code is licensed under the Apache License, Version 2.0. You may
 # obtain a copy of this license in the LICENSE.txt file in the root directory
@@ -11,11 +11,13 @@
 # that they have been altered from the originals.
 
 
-"""Implementations of boolean logic quantum circuits."""
+"""Boolean AND circuit and gate."""
+
 from __future__ import annotations
 
-from qiskit.circuit import QuantumRegister, QuantumCircuit, AncillaRegister
+from qiskit.circuit import QuantumRegister, QuantumCircuit, AncillaRegister, Gate
 from qiskit.circuit.library.standard_gates import MCXGate
+from qiskit.utils.deprecation import deprecate_func
 
 
 class AND(QuantumCircuit):
@@ -49,6 +51,11 @@ class AND(QuantumCircuit):
 
     """
 
+    @deprecate_func(
+        since="1.3",
+        additional_msg="Use qiskit.circuit.library.AndGate instead.",
+        pending=True,
+    )
     def __init__(
         self,
         num_variable_qubits: int,
@@ -58,7 +65,7 @@ class AND(QuantumCircuit):
         """Create a new logical AND circuit.
 
         Args:
-            num_variable_qubits: The qubits of which the OR is computed. The result will be written
+            num_variable_qubits: The qubits of which the AND is computed. The result will be written
                 into an additional result qubit.
             flags: A list of +1/0/-1 marking negations or omissions of qubits.
             mcx_mode: The mode to be used to implement the multi-controlled X gate.
@@ -95,3 +102,99 @@ class AND(QuantumCircuit):
 
         super().__init__(*circuit.qregs, name="and")
         self.compose(circuit.to_gate(), qubits=self.qubits, inplace=True)
+
+
+class AndGate(Gate):
+    r"""A gate representing the logical AND operation on a number of qubits.
+
+    For the AND operation the state :math:`|1\rangle` is interpreted as ``True``. The result
+    qubit is flipped, if the state of all variable qubits is ``True``. In this format, the AND
+    operation equals a multi-controlled X gate, which is controlled on all variable qubits.
+    Using a list of flags however, qubits can be skipped or negated. Practically, the flags
+    allow to skip controls or to apply pre- and post-X gates to the negated qubits.
+
+    The AndGate gate without special flags equals the multi-controlled-X gate:
+
+    .. plot::
+
+       from qiskit.circuit import QuantumCircuit
+       from qiskit.circuit.library import AndGate
+       from qiskit.visualization.library import _generate_circuit_library_visualization
+       circuit = QuantumCircuit(6)
+       circuit.append(AndGate(5), [0, 1, 2, 3, 4, 5])
+       _generate_circuit_library_visualization(circuit)
+
+    Using flags we can negate qubits or skip them. For instance, if we have 5 qubits and want to
+    return ``True`` if the first qubit is ``False`` and the last two are ``True`` we use the flags
+    ``[-1, 0, 0, 1, 1]``.
+
+    .. plot::
+
+       from qiskit.circuit import QuantumCircuit
+       from qiskit.circuit.library import AndGate
+       from qiskit.visualization.library import _generate_circuit_library_visualization
+       circuit = QuantumCircuit(6)
+       circuit.append(AndGate(5, flags=[-1, 0, 0, 1, 1]), [0, 1, 2, 3, 4, 5])
+       _generate_circuit_library_visualization(circuit)
+
+    """
+
+    def __init__(
+        self,
+        num_variable_qubits: int,
+        flags: list[int] | None = None,
+    ) -> None:
+        """
+        Args:
+            num_variable_qubits: The qubits of which the AND is computed. The result will be written
+                into an additional result qubit.
+            flags: A list of +1/0/-1 marking negations or omissions of qubits.
+        """
+        super().__init__("and", num_variable_qubits + 1, [])
+        self.num_variable_qubits = num_variable_qubits
+        self.flags = flags
+
+    def _define(self):
+        # add registers
+        qr_variable = QuantumRegister(self.num_variable_qubits, name="variable")
+        qr_result = QuantumRegister(1, name="result")
+
+        # determine the control qubits: all that have a nonzero flag
+        flags = self.flags or [1] * self.num_variable_qubits
+        control_qubits = [q for q, flag in zip(qr_variable, flags) if flag != 0]
+
+        # determine the qubits that need to be flipped (if a flag is < 0)
+        flip_qubits = [q for q, flag in zip(qr_variable, flags) if flag < 0]
+
+        # create the definition circuit
+        circuit = QuantumCircuit(qr_variable, qr_result, name="and")
+
+        if len(flip_qubits) > 0:
+            circuit.x(flip_qubits)
+        circuit.mcx(control_qubits, qr_result[:])
+        if len(flip_qubits) > 0:
+            circuit.x(flip_qubits)
+
+        self.definition = circuit
+
+    # pylint: disable=unused-argument
+    def inverse(self, annotated: bool = False):
+        r"""Return inverted AND gate (itself).
+
+        Args:
+            annotated: when set to ``True``, this is typically used to return an
+                :class:`.AnnotatedOperation` with an inverse modifier set instead of a concrete
+                :class:`.Gate`. However, for this class this argument is ignored as this gate
+                is self-inverse.
+
+        Returns:
+            AndGate: inverse gate (self-inverse).
+        """
+        return AndGate(self.num_variable_qubits, self.flags)
+
+    def __eq__(self, other):
+        return (
+            isinstance(other, AndGate)
+            and self.num_variable_qubits == other.num_variable_qubits
+            and self.flags == other.flags
+        )

qiskit/circuit/library/boolean_logic/quantum_or.py

@@ -1,6 +1,6 @@
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2020.
+# (C) Copyright IBM 2020, 2024.
 #
 # This code is licensed under the Apache License, Version 2.0. You may
 # obtain a copy of this license in the LICENSE.txt file in the root directory
@@ -11,12 +11,14 @@
 # that they have been altered from the originals.
 
 
-"""Implementations of boolean logic quantum circuits."""
+"""Boolean OR circuit and gate."""
+
 from __future__ import annotations
 from typing import List, Optional
 
-from qiskit.circuit import QuantumRegister, QuantumCircuit, AncillaRegister
+from qiskit.circuit import QuantumRegister, QuantumCircuit, AncillaRegister, Gate
 from qiskit.circuit.library.standard_gates import MCXGate
+from qiskit.utils.deprecation import deprecate_func
 
 
 class OR(QuantumCircuit):
@@ -50,6 +52,11 @@ class OR(QuantumCircuit):
 
     """
 
+    @deprecate_func(
+        since="1.3",
+        additional_msg="Use qiskit.circuit.library.OrGate instead.",
+        pending=True,
+    )
     def __init__(
         self,
         num_variable_qubits: int,
@@ -96,3 +103,100 @@ class OR(QuantumCircuit):
 
         super().__init__(*circuit.qregs, name="or")
         self.compose(circuit.to_gate(), qubits=self.qubits, inplace=True)
+
+
+class OrGate(Gate):
+    r"""A gate representing the logical OR operation on a number of qubits.
+
+    For the OR operation the state :math:`|1\rangle` is interpreted as ``True``. The result
+    qubit is flipped, if the state of any variable qubit is ``True``. The OR is implemented using
+    a multi-open-controlled X gate (i.e. flips if the state is :math:`|0\rangle`) and
+    applying an X gate on the result qubit.
+    Using a list of flags, qubits can be skipped or negated.
+
+    The OrGate gate without special flags:
+
+    .. plot::
+
+       from qiskit.circuit import QuantumCircuit
+       from qiskit.circuit.library import OrGate
+       from qiskit.visualization.library import _generate_circuit_library_visualization
+       circuit = QuantumCircuit(6)
+       circuit.append(OrGate(5), [0, 1, 2, 3, 4, 5])
+       _generate_circuit_library_visualization(circuit)
+
+    Using flags we can negate qubits or skip them. For instance, if we have 5 qubits and want to
+    return ``True`` if the first qubit is ``False`` or one of the last two are ``True`` we use the
+    flags ``[-1, 0, 0, 1, 1]``.
+
+    .. plot::
+
+       from qiskit.circuit import QuantumCircuit
+       from qiskit.circuit.library import OrGate
+       from qiskit.visualization.library import _generate_circuit_library_visualization
+       circuit = QuantumCircuit(6)
+       circuit.append(OrGate(5, flags=[-1, 0, 0, 1, 1]), [0, 1, 2, 3, 4, 5])
+       _generate_circuit_library_visualization(circuit)
+
+    """
+
+    def __init__(
+        self,
+        num_variable_qubits: int,
+        flags: list[int] | None = None,
+    ) -> None:
+        """
+        Args:
+            num_variable_qubits: The qubits of which the AND is computed. The result will be written
+                into an additional result qubit.
+            flags: A list of +1/0/-1 marking negations or omissions of qubits.
+        """
+        super().__init__("and", num_variable_qubits + 1, [])
+        self.num_variable_qubits = num_variable_qubits
+        self.flags = flags
+
+    def _define(self):
+        # add registers
+        qr_variable = QuantumRegister(self.num_variable_qubits, name="variable")
+        qr_result = QuantumRegister(1, name="result")
+
+        # determine the control qubits: all that have a nonzero flag
+        flags = self.flags or [1] * self.num_variable_qubits
+        control_qubits = [q for q, flag in zip(qr_variable, flags) if flag != 0]
+
+        # determine the qubits that need to be flipped (if a flag is > 0)
+        flip_qubits = [q for q, flag in zip(qr_variable, flags) if flag > 0]
+
+        # create the definition circuit
+        circuit = QuantumCircuit(qr_variable, qr_result, name="or")
+
+        circuit.x(qr_result)
+        if len(flip_qubits) > 0:
+            circuit.x(flip_qubits)
+        circuit.mcx(control_qubits, qr_result[:])
+        if len(flip_qubits) > 0:
+            circuit.x(flip_qubits)
+
+        self.definition = circuit
+
+    # pylint: disable=unused-argument
+    def inverse(self, annotated: bool = False):
+        r"""Return inverted OR gate (itself).
+
+        Args:
+            annotated: when set to ``True``, this is typically used to return an
+                :class:`.AnnotatedOperation` with an inverse modifier set instead of a concrete
+                :class:`.Gate`. However, for this class this argument is ignored as this gate
+                is self-inverse.
+
+        Returns:
+            OrGate: inverse gate (self-inverse).
+        """
+        return OrGate(self.num_variable_qubits, self.flags)
+
+    def __eq__(self, other):
+        return (
+            isinstance(other, OrGate)
+            and self.num_variable_qubits == other.num_variable_qubits
+            and self.flags == other.flags
+        )

qiskit/circuit/library/boolean_logic/quantum_xor.py

@@ -1,6 +1,6 @@
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2020.
+# (C) Copyright IBM 2020, 2024.
 #
 # This code is licensed under the Apache License, Version 2.0. You may
 # obtain a copy of this license in the LICENSE.txt file in the root directory
@@ -11,13 +11,14 @@
 # that they have been altered from the originals.
 
 
-"""XOR circuit."""
+"""Bitwise XOR circuit and gate."""
 
 from typing import Optional
 
 import numpy as np
-from qiskit.circuit import QuantumCircuit
+from qiskit.circuit import QuantumCircuit, Gate
 from qiskit.circuit.exceptions import CircuitError
+from qiskit.utils.deprecation import deprecate_func
 
 
 class XOR(QuantumCircuit):
@@ -28,6 +29,12 @@ class XOR(QuantumCircuit):
     This circuit can also represent addition by ``amount`` over the finite field GF(2).
     """
 
+    @deprecate_func(
+        since="1.3",
+        additional_msg="Instead, for xor-ing with a specified amount, use BitwiseXorGate,"
+        "and for xor-ing with a random amount, use random_bitwise_xor.",
+        pending=True,
+    )
     def __init__(
         self,
         num_qubits: int,
@@ -69,3 +76,90 @@ class XOR(QuantumCircuit):
 
         super().__init__(*circuit.qregs, name="xor")
         self.compose(circuit.to_gate(), qubits=self.qubits, inplace=True)
+
+
+class BitwiseXorGate(Gate):
+    """An n-qubit gate for bitwise xor-ing the input with some integer ``amount``.
+
+    The ``amount`` is xor-ed in bitstring form with the input.
+
+    This gate can also represent addition by ``amount`` over the finite field GF(2).
+
+    Reference Circuit:
+
+    .. plot::
+
+       from qiskit.circuit import QuantumCircuit
+       from qiskit.circuit.library import BitwiseXorGate
+       from qiskit.visualization.library import _generate_circuit_library_visualization
+       circuit = QuantumCircuit(5)
+       circuit.append(BitwiseXorGate(5, amount=12), [0, 1, 2, 3, 4])
+       _generate_circuit_library_visualization(circuit)
+
+    """
+
+    def __init__(
+        self,
+        num_qubits: int,
+        amount: int,
+    ) -> None:
+        """
+        Args:
+            num_qubits: the width of circuit.
+            amount: the xor amount in decimal form.
+
+        Raises:
+            CircuitError: if the xor bitstring exceeds available qubits.
+        """
+        if len(bin(amount)[2:]) > num_qubits:
+            raise CircuitError("Bits in 'amount' exceed circuit width")
+
+        super().__init__("xor", num_qubits, [])
+        self.amount = amount
+
+    def _define(self):
+        circuit = QuantumCircuit(self.num_qubits, name="xor")
+        amount = self.amount
+        for i in range(self.num_qubits):
+            bit = amount & 1
+            amount = amount >> 1
+            if bit == 1:
+                circuit.x(i)
+
+        self.definition = circuit
+
+    def __eq__(self, other):
+        return (
+            isinstance(other, BitwiseXorGate)
+            and self.num_qubits == other.num_qubits
+            and self.amount == other.amount
+        )
+
+    # pylint: disable=unused-argument
+    def inverse(self, annotated: bool = False):
+        r"""Return inverted BitwiseXorGate gate (itself).
+
+        Args:
+            annotated: when set to ``True``, this is typically used to return an
+                :class:`.AnnotatedOperation` with an inverse modifier set instead of a concrete
+                :class:`.Gate`. However, for this class this argument is ignored as this gate
+                is self-inverse.
+
+        Returns:
+            BitwiseXorGate: inverse gate (self-inverse).
+        """
+        return BitwiseXorGate(self.num_qubits, self.amount)
+
+
+def random_bitwise_xor(num_qubits: int, seed: int) -> BitwiseXorGate:
+    """
+    Create a random BitwiseXorGate.
+
+    Args:
+        num_qubits: the width of circuit.
+        seed: random seed in case a random xor is requested.
+    """
+
+    rng = np.random.default_rng(seed)
+    amount = rng.integers(0, 2**num_qubits)
+    return BitwiseXorGate(num_qubits, amount)

qiskit/circuit/library/data_preparation/__init__.py

@@ -38,15 +38,18 @@ of the complete initial data.
 
 """
 
-from .pauli_feature_map import PauliFeatureMap
-from .z_feature_map import ZFeatureMap
-from .zz_feature_map import ZZFeatureMap
+from .pauli_feature_map import PauliFeatureMap, pauli_feature_map, z_feature_map, zz_feature_map
+from ._z_feature_map import ZFeatureMap
+from ._zz_feature_map import ZZFeatureMap
 from .state_preparation import StatePreparation, UniformSuperpositionGate
 from .initializer import Initialize
 
 __all__ = [
+    "pauli_feature_map",
     "PauliFeatureMap",
+    "z_feature_map",
     "ZFeatureMap",
+    "zz_feature_map",
     "ZZFeatureMap",
     "StatePreparation",
     "UniformSuperpositionGate",

qiskit/circuit/library/data_preparation/{z_feature_map.py → _z_feature_map.py}

@@ -14,6 +14,7 @@
 
 from typing import Callable, Optional
 import numpy as np
+from qiskit.utils.deprecation import deprecate_func
 
 from .pauli_feature_map import PauliFeatureMap
 
@@ -23,15 +24,15 @@ class ZFeatureMap(PauliFeatureMap):
 
     On 3 qubits and with 2 repetitions the circuit is represented by:
 
-    .. parsed-literal::
+    .. code-block:: text
 
-        ┌───┐┌──────────────┐┌───┐┌──────────────┐
-        ┤ H ├┤ U1(2.0*x[0]) ├┤ H ├┤ U1(2.0*x[0]) ├
-        ├───┤├──────────────┤├───┤├──────────────┤
-        ┤ H ├┤ U1(2.0*x[1]) ├┤ H ├┤ U1(2.0*x[1]) ├
-        ├───┤├──────────────┤├───┤├──────────────┤
-        ┤ H ├┤ U1(2.0*x[2]) ├┤ H ├┤ U1(2.0*x[2]) ├
-        └───┘└──────────────┘└───┘└──────────────┘
+        ┌───┐┌─────────────┐┌───┐┌─────────────┐
+        ┤ H ├┤ P(2.0*x[0]) ├┤ H ├┤ P(2.0*x[0]) ├
+        ├───┤├─────────────┤├───┤├─────────────┤
+        ┤ H ├┤ U(2.0*x[1]) ├┤ H ├┤ P(2.0*x[1]) ├
+        ├───┤├─────────────┤├───┤├─────────────┤
+        ┤ H ├┤ P(2.0*x[2]) ├┤ H ├┤ P(2.0*x[2]) ├
+        └───┘└─────────────┘└───┘└─────────────┘
 
     This is a sub-class of :class:`~qiskit.circuit.library.PauliFeatureMap` where the Pauli
     strings are fixed as `['Z']`. As a result the first order expansion will be a circuit without
@@ -40,38 +41,48 @@ class ZFeatureMap(PauliFeatureMap):
     Examples:
 
         >>> prep = ZFeatureMap(3, reps=3, insert_barriers=True)
-        >>> print(prep)
-             ┌───┐ ░ ┌──────────────┐ ░ ┌───┐ ░ ┌──────────────┐ ░ ┌───┐ ░ ┌──────────────┐
-        q_0: ┤ H ├─░─┤ U1(2.0*x[0]) ├─░─┤ H ├─░─┤ U1(2.0*x[0]) ├─░─┤ H ├─░─┤ U1(2.0*x[0]) ├
-             ├───┤ ░ ├──────────────┤ ░ ├───┤ ░ ├──────────────┤ ░ ├───┤ ░ ├──────────────┤
-        q_1: ┤ H ├─░─┤ U1(2.0*x[1]) ├─░─┤ H ├─░─┤ U1(2.0*x[1]) ├─░─┤ H ├─░─┤ U1(2.0*x[1]) ├
-             ├───┤ ░ ├──────────────┤ ░ ├───┤ ░ ├──────────────┤ ░ ├───┤ ░ ├──────────────┤
-        q_2: ┤ H ├─░─┤ U1(2.0*x[2]) ├─░─┤ H ├─░─┤ U1(2.0*x[2]) ├─░─┤ H ├─░─┤ U1(2.0*x[2]) ├
-             └───┘ ░ └──────────────┘ ░ └───┘ ░ └──────────────┘ ░ └───┘ ░ └──────────────┘
+        >>> print(prep.decompose())
+             ┌───┐ ░ ┌─────────────┐ ░ ┌───┐ ░ ┌─────────────┐ ░ ┌───┐ ░ ┌─────────────┐
+        q_0: ┤ H ├─░─┤ P(2.0*x[0]) ├─░─┤ H ├─░─┤ P(2.0*x[0]) ├─░─┤ H ├─░─┤ P(2.0*x[0]) ├
+             ├───┤ ░ ├─────────────┤ ░ ├───┤ ░ ├─────────────┤ ░ ├───┤ ░ ├─────────────┤
+        q_1: ┤ H ├─░─┤ P(2.0*x[1]) ├─░─┤ H ├─░─┤ P(2.0*x[1]) ├─░─┤ H ├─░─┤ P(2.0*x[1]) ├
+             ├───┤ ░ ├─────────────┤ ░ ├───┤ ░ ├─────────────┤ ░ ├───┤ ░ ├─────────────┤
+        q_2: ┤ H ├─░─┤ P(2.0*x[2]) ├─░─┤ H ├─░─┤ P(2.0*x[2]) ├─░─┤ H ├─░─┤ P(2.0*x[2]) ├
+             └───┘ ░ └─────────────┘ ░ └───┘ ░ └─────────────┘ ░ └───┘ ░ └─────────────┘
 
         >>> data_map = lambda x: x[0]*x[0] + 1  # note: input is an array
         >>> prep = ZFeatureMap(3, reps=1, data_map_func=data_map)
-        >>> print(prep)
-             ┌───┐┌───────────────────────┐
-        q_0: ┤ H ├┤ U1(2.0*x[0]**2 + 2.0) ├
-             ├───┤├───────────────────────┤
-        q_1: ┤ H ├┤ U1(2.0*x[1]**2 + 2.0) ├
-             ├───┤├───────────────────────┤
-        q_2: ┤ H ├┤ U1(2.0*x[2]**2 + 2.0) ├
-             └───┘└───────────────────────┘
-
-        >>> classifier = ZFeatureMap(3, reps=1) + RY(3, reps=1)
-        >>> print(classifier)
-             ┌───┐┌──────────────┐┌──────────┐      ┌──────────┐
-        q_0: ┤ H ├┤ U1(2.0*x[0]) ├┤ RY(θ[0]) ├─■──■─┤ RY(θ[3]) ├────────────
-             ├───┤├──────────────┤├──────────┤ │  │ └──────────┘┌──────────┐
-        q_1: ┤ H ├┤ U1(2.0*x[1]) ├┤ RY(θ[1]) ├─■──┼──────■──────┤ RY(θ[4]) ├
-             ├───┤├──────────────┤├──────────┤    │      │      ├──────────┤
-        q_2: ┤ H ├┤ U1(2.0*x[2]) ├┤ RY(θ[2]) ├────■──────■──────┤ RY(θ[5]) ├
-             └───┘└──────────────┘└──────────┘                  └──────────┘
+        >>> print(prep.decompose())
+             ┌───┐┌──────────────────────┐
+        q_0: ┤ H ├┤ P(2.0*x[0]**2 + 2.0) ├
+             ├───┤├──────────────────────┤
+        q_1: ┤ H ├┤ P(2.0*x[1]**2 + 2.0) ├
+             ├───┤├──────────────────────┤
+        q_2: ┤ H ├┤ P(2.0*x[2]**2 + 2.0) ├
+             └───┘└──────────────────────┘
+
+        >>> from qiskit.circuit.library import TwoLocal
+        >>> ry = TwoLocal(3, "ry", "cz", reps=1)
+        >>> classifier = ZFeatureMap(3, reps=1) + ry
+        >>> print(classifier.decompose())
+             ┌───┐┌─────────────┐┌──────────┐      ┌──────────┐
+        q_0: ┤ H ├┤ P(2.0*x[0]) ├┤ RY(θ[0]) ├─■──■─┤ RY(θ[3]) ├────────────
+             ├───┤├─────────────┤├──────────┤ │  │ └──────────┘┌──────────┐
+        q_1: ┤ H ├┤ P(2.0*x[1]) ├┤ RY(θ[1]) ├─■──┼──────■──────┤ RY(θ[4]) ├
+             ├───┤├─────────────┤├──────────┤    │      │      ├──────────┤
+        q_2: ┤ H ├┤ P(2.0*x[2]) ├┤ RY(θ[2]) ├────■──────■──────┤ RY(θ[5]) ├
+             └───┘└─────────────┘└──────────┘                  └──────────┘
 
     """
 
+    @deprecate_func(
+        since="1.3",
+        additional_msg=(
+            "Use the z_feature_map function as a replacement. Note that this will no longer "
+            "return a BlueprintCircuit, but just a plain QuantumCircuit."
+        ),
+        pending=True,
+    )
     def __init__(
         self,
         feature_dimension: int,