qiskit 1.3.0__cp39-abi3-macosx_11_0_arm64.whl

qiskit/circuit/library/boolean_logic/quantum_xor.py

@@ -0,0 +1,165 @@
+# This code is part of Qiskit.
+#
+# (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
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+
+"""Bitwise XOR circuit and gate."""
+
+from typing import Optional
+
+import numpy as np
+from qiskit.circuit import QuantumCircuit, Gate
+from qiskit.circuit.exceptions import CircuitError
+from qiskit.utils.deprecation import deprecate_func
+
+
+class XOR(QuantumCircuit):
+    """An n_qubit circuit for bitwise xor-ing the input with some integer ``amount``.
+
+    The ``amount`` is xor-ed in bitstring form with the input.
+
+    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,
+        amount: Optional[int] = None,
+        seed: Optional[int] = None,
+    ) -> None:
+        """Return a circuit implementing bitwise xor.
+
+        Args:
+            num_qubits: the width of circuit.
+            amount: the xor amount in decimal form.
+            seed: random seed in case a random xor is requested.
+
+        Raises:
+            CircuitError: if the xor bitstring exceeds available qubits.
+
+        Reference Circuit:
+            .. plot::
+
+               from qiskit.circuit.library import XOR
+               from qiskit.visualization.library import _generate_circuit_library_visualization
+               circuit = XOR(5, seed=42)
+               _generate_circuit_library_visualization(circuit)
+        """
+        circuit = QuantumCircuit(num_qubits, name="xor")
+
+        if amount is not None:
+            if len(bin(amount)[2:]) > num_qubits:
+                raise CircuitError("Bits in 'amount' exceed circuit width")
+        else:
+            rng = np.random.default_rng(seed)
+            amount = rng.integers(0, 2**num_qubits)
+
+        for i in range(num_qubits):
+            bit = amount & 1
+            amount = amount >> 1
+            if bit == 1:
+                circuit.x(i)
+
+        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

@@ -0,0 +1,57 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 2020.
+#
+# 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
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""
+Data-encoding circuits
+======================
+
+In machine learning, pattern recognition and image processing, a **data-encoding circuit**
+starts from an initial set of measured data and builds derived values (also known as
+**features**) intended to be informative and non-redundant, facilitating the subsequent
+learning and generalization steps, and in some cases leading to better human
+interpretations.
+
+A feature map is related to **dimensionality reduction**; it involves reducing the amount of
+resources required to describe a large set of data. When performing analysis of complex data,
+one of the major problems stems from the number of variables involved. Analysis with a large
+number of variables generally requires a large amount of memory and computation power, and may
+even cause a classification algorithm to overfit to training samples and generalize poorly to new
+samples.
+
+When the input data to an algorithm is too large to be processed and is suspected to be redundant
+(for example, the same measurement is provided in both pounds and kilograms), then it can be
+transformed into a reduced set of features, named a **feature vector**.
+
+The process of determining a subset of the initial features is called **feature selection**.
+The selected features are expected to contain the relevant information from the input data,
+so that the desired task can be performed by using the reduced representation instead
+of the complete initial data.
+
+"""
+
+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",
+    "Initialize",
+]

qiskit/circuit/library/data_preparation/_z_feature_map.py

@@ -0,0 +1,115 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 2020.
+#
+# 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
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Create a new first-order Pauli-Z expansion circuit."""
+
+from typing import Callable, Optional
+import numpy as np
+from qiskit.utils.deprecation import deprecate_func
+
+from .pauli_feature_map import PauliFeatureMap
+
+
+class ZFeatureMap(PauliFeatureMap):
+    """The first order Pauli Z-evolution circuit.
+
+    On 3 qubits and with 2 repetitions the circuit is represented by:
+
+    .. code-block:: text
+
+        ┌───┐┌─────────────┐┌───┐┌─────────────┐
+        ┤ 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
+    entangling gates.
+
+    Examples:
+
+        >>> prep = ZFeatureMap(3, reps=3, insert_barriers=True)
+        >>> 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.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,
+        reps: int = 2,
+        data_map_func: Optional[Callable[[np.ndarray], float]] = None,
+        parameter_prefix: str = "x",
+        insert_barriers: bool = False,
+        name: str = "ZFeatureMap",
+    ) -> None:
+        """Create a new first-order Pauli-Z expansion circuit.
+
+        Args:
+            feature_dimension: The number of features
+            reps: The number of repeated circuits. Defaults to 2, has a minimum value of 1.
+            data_map_func: A mapping function for data x which can be supplied to override the
+                default mapping from :meth:`self_product`.
+            parameter_prefix: The prefix used if default parameters are generated.
+            insert_barriers: If True, barriers are inserted in between the evolution instructions
+                and hadamard layers.
+
+        """
+        super().__init__(
+            feature_dimension=feature_dimension,
+            paulis=["Z"],
+            reps=reps,
+            data_map_func=data_map_func,
+            parameter_prefix=parameter_prefix,
+            insert_barriers=insert_barriers,
+            name=name,
+        )

qiskit/circuit/library/data_preparation/_zz_feature_map.py

@@ -0,0 +1,150 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 2020.
+#
+# 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
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Second-order Pauli-Z expansion circuit."""
+
+from typing import Callable, List, Union, Optional, Dict, Tuple
+import numpy as np
+from qiskit.utils.deprecation import deprecate_func
+from .pauli_feature_map import PauliFeatureMap
+
+
+class ZZFeatureMap(PauliFeatureMap):
+    r"""Second-order Pauli-Z evolution circuit.
+
+    For 3 qubits and 1 repetition and linear entanglement the circuit is represented by:
+
+    .. code-block:: text
+
+        ┌───┐┌────────────────┐
+        ┤ H ├┤ P(2.0*φ(x[0])) ├──■───────────────────────────■───────────────────────────────────
+        ├───┤├────────────────┤┌─┴─┐┌─────────────────────┐┌─┴─┐
+        ┤ H ├┤ P(2.0*φ(x[1])) ├┤ X ├┤ P(2.0*φ(x[0],x[1])) ├┤ X ├──■───────────────────────────■──
+        ├───┤├────────────────┤└───┘└─────────────────────┘└───┘┌─┴─┐┌─────────────────────┐┌─┴─┐
+        ┤ H ├┤ P(2.0*φ(x[2])) ├─────────────────────────────────┤ X ├┤ P(2.0*φ(x[1],x[2])) ├┤ X ├
+        └───┘└────────────────┘                                 └───┘└─────────────────────┘└───┘
+
+    where :math:`\varphi` is a classical non-linear function, which defaults to :math:`\varphi(x) = x`
+    if and :math:`\varphi(x,y) = (\pi - x)(\pi - y)`.
+
+    Examples:
+
+    .. code-block::
+
+         from qiskit.circuit.library import ZZFeatureMap
+         prep = ZZFeatureMap(2, reps=1)
+         print(prep.decompose())
+
+    .. code-block:: text
+
+              ┌───┐┌─────────────┐
+         q_0: ┤ H ├┤ P(2.0*x[0]) ├──■──────────────────────────────────────■──
+              ├───┤├─────────────┤┌─┴─┐┌────────────────────────────────┐┌─┴─┐
+         q_1: ┤ H ├┤ P(2.0*x[1]) ├┤ X ├┤ P(2.0*(pi - x[0])*(pi - x[1])) ├┤ X ├
+              └───┘└─────────────┘└───┘└────────────────────────────────┘└───┘
+
+    .. code-block::
+
+         from qiskit.circuit.library import EfficientSU2
+         classifier = ZZFeatureMap(3).compose(EfficientSU2(3))
+         classifier.num_parameters
+
+    .. code-block:: text
+
+         27
+
+    .. code-block::
+
+         classifier.parameters  # 'x' for the data preparation, 'θ' for the SU2 parameters
+
+    .. code-block:: text
+
+         ParameterView([
+             ParameterVectorElement(x[0]), ParameterVectorElement(x[1]),
+             ParameterVectorElement(x[2]), ParameterVectorElement(θ[0]),
+             ParameterVectorElement(θ[1]), ParameterVectorElement(θ[2]),
+             ParameterVectorElement(θ[3]), ParameterVectorElement(θ[4]),
+             ParameterVectorElement(θ[5]), ParameterVectorElement(θ[6]),
+             ParameterVectorElement(θ[7]), ParameterVectorElement(θ[8]),
+             ParameterVectorElement(θ[9]), ParameterVectorElement(θ[10]),
+             ParameterVectorElement(θ[11]), ParameterVectorElement(θ[12]),
+             ParameterVectorElement(θ[13]), ParameterVectorElement(θ[14]),
+             ParameterVectorElement(θ[15]), ParameterVectorElement(θ[16]),
+             ParameterVectorElement(θ[17]), ParameterVectorElement(θ[18]),
+             ParameterVectorElement(θ[19]), ParameterVectorElement(θ[20]),
+             ParameterVectorElement(θ[21]), ParameterVectorElement(θ[22]),
+             ParameterVectorElement(θ[23])
+         ])
+
+    .. code-block::
+
+         classifier.count_ops()
+
+    .. code-block:: text
+
+        OrderedDict([('ZZFeatureMap', 1), ('EfficientSU2', 1)])
+
+    """
+
+    @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,
+        reps: int = 2,
+        entanglement: Union[
+            str,
+            Dict[int, List[Tuple[int]]],
+            Callable[[int], Union[str, Dict[int, List[Tuple[int]]]]],
+        ] = "full",
+        data_map_func: Optional[Callable[[np.ndarray], float]] = None,
+        parameter_prefix: str = "x",
+        insert_barriers: bool = False,
+        name: str = "ZZFeatureMap",
+    ) -> None:
+        """Create a new second-order Pauli-Z expansion.
+
+        Args:
+            feature_dimension: Number of features.
+            reps: The number of repeated circuits, has a min. value of 1.
+            entanglement: Specifies the entanglement structure. Refer to
+                :class:`~qiskit.circuit.library.PauliFeatureMap` for detail.
+            data_map_func: A mapping function for data x.
+            parameter_prefix: The prefix used if default parameters are generated.
+            insert_barriers: If True, barriers are inserted in between the evolution instructions
+                and hadamard layers.
+
+        Raises:
+            ValueError: If the feature dimension is smaller than 2.
+        """
+        if feature_dimension < 2:
+            raise ValueError(
+                "The ZZFeatureMap contains 2-local interactions and cannot be "
+                f"defined for less than 2 qubits. You provided {feature_dimension}."
+            )
+
+        super().__init__(
+            feature_dimension=feature_dimension,
+            reps=reps,
+            entanglement=entanglement,
+            paulis=["Z", "ZZ"],
+            data_map_func=data_map_func,
+            parameter_prefix=parameter_prefix,
+            insert_barriers=insert_barriers,
+            name=name,
+        )

qiskit/circuit/library/data_preparation/initializer.py

@@ -0,0 +1,107 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017.
+#
+# 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
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""
+Initialize qubit registers to desired arbitrary state.
+"""
+
+from __future__ import annotations
+from collections.abc import Sequence
+import typing
+
+from qiskit.circuit.quantumcircuit import QuantumCircuit
+from qiskit.circuit.quantumregister import QuantumRegister
+from qiskit.circuit.instruction import Instruction
+from qiskit.circuit.library.generalized_gates import Isometry
+from .state_preparation import StatePreparation
+
+if typing.TYPE_CHECKING:
+    from qiskit.quantum_info.states.statevector import Statevector
+
+_EPS = 1e-10  # global variable used to chop very small numbers to zero
+
+
+class Initialize(Instruction):
+    """Complex amplitude initialization.
+
+    Class that initializes some flexible collection of qubit registers, implemented by calling
+    the :class:`~.library.StatePreparation` class.
+    Note that ``Initialize`` is an :class:`~.circuit.Instruction` and not a :class:`.Gate` since it
+    contains a reset instruction, which is not unitary.
+
+    The initial state is prepared based on the :class:`~.library.Isometry` synthesis described in [1].
+
+    References:
+        1. Iten et al., Quantum circuits for isometries (2016).
+           `Phys. Rev. A 93, 032318
+           <https://journals.aps.org/pra/abstract/10.1103/PhysRevA.93.032318>`__.
+
+    """
+
+    def __init__(
+        self,
+        params: Statevector | Sequence[complex] | str | int,
+        num_qubits: int | None = None,
+        normalize: bool = False,
+    ) -> None:
+        r"""
+        Args:
+            params: The state to initialize to, can be either of the following.
+
+                * Statevector or vector of complex amplitudes to initialize to.
+                * Labels of basis states of the Pauli eigenstates Z, X, Y. See
+                  :meth:`.Statevector.from_label`. Notice the order of the labels is reversed with
+                  respect to the qubit index to be applied to. Example label '01' initializes the
+                  qubit zero to :math:`|1\rangle` and the qubit one to :math:`|0\rangle`.
+                * An integer that is used as a bitmap indicating which qubits to initialize to
+                  :math:`|1\rangle`. Example: setting params to 5 would initialize qubit 0 and qubit
+                  2 to :math:`|1\rangle` and qubit 1 to :math:`|0\rangle`.
+
+            num_qubits: This parameter is only used if params is an int. Indicates the total
+                number of qubits in the `initialize` call. Example: `initialize` covers 5 qubits
+                and params is 3. This allows qubits 0 and 1 to be initialized to :math:`|1\rangle`
+                and the remaining 3 qubits to be initialized to :math:`|0\rangle`.
+            normalize: Whether to normalize an input array to a unit vector.
+        """
+        self._stateprep = StatePreparation(params, num_qubits, normalize=normalize)
+
+        super().__init__("initialize", self._stateprep.num_qubits, 0, self._stateprep.params)
+
+    def _define(self):
+        q = QuantumRegister(self.num_qubits, "q")
+        initialize_circuit = QuantumCircuit(q, name="init_def")
+        initialize_circuit.reset(q)
+        initialize_circuit.append(self._stateprep, q)
+        self.definition = initialize_circuit
+
+    def gates_to_uncompute(self) -> QuantumCircuit:
+        """Call to create a circuit with gates that take the desired vector to zero.
+
+        Returns:
+            QuantumCircuit: circuit to take ``self.params`` vector to :math:`|{00\\ldots0}\\rangle`
+        """
+
+        isom = Isometry(self.params, 0, 0)
+        return isom._gates_to_uncompute()
+
+    @property
+    def params(self):
+        """Return initialize params."""
+        return self._stateprep.params
+
+    @params.setter
+    def params(self, parameters: Statevector | Sequence[complex] | str | int) -> None:
+        """Set initialize params."""
+        self._stateprep.params = parameters
+
+    def broadcast_arguments(self, qargs, cargs):
+        return self._stateprep.broadcast_arguments(qargs, cargs)