qiskit 1.3.0b1__cp39-abi3-macosx_11_0_arm64.whl → 1.3.0rc1__cp39-abi3-macosx_11_0_arm64.whl

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

@@ -14,3 +14,4 @@
 
 from .hrs_cumulative_multiplier import HRSCumulativeMultiplier
 from .rg_qft_multiplier import RGQFTMultiplier
+from .multiplier import MultiplierGate

qiskit/circuit/library/arithmetic/multipliers/hrs_cumulative_multiplier.py

@@ -26,7 +26,7 @@ class HRSCumulativeMultiplier(Multiplier):
     the default adder is as follows (where ``Adder`` denotes the
     ``CDKMRippleCarryAdder``):
 
-    .. parsed-literal::
+    .. code-block:: text
 
           a_0: ────■─────────────────────────
                    │
@@ -59,6 +59,13 @@ class HRSCumulativeMultiplier(Multiplier):
     a series of shifted additions using one of the input registers while the qubits
     from the other input register act as control qubits for the adders.
 
+    .. seealso::
+
+        The :class:`.MultiplierGate` objects represents a multiplication, like this circuit class,
+        but allows 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 ``Multiplier=["cumulative_h18"]``.
+
     **References:**
 
     [1] Häner et al., Optimizing Quantum Circuits for Arithmetic, 2018.

qiskit/circuit/library/arithmetic/multipliers/multiplier.py

@@ -12,9 +12,10 @@
 
 """Compute the product of two equally sized qubit registers."""
 
-from typing import Optional
+from __future__ import annotations
 
-from qiskit.circuit import QuantumCircuit
+from qiskit.circuit import QuantumCircuit, Gate
+from qiskit.utils.deprecation import deprecate_func
 
 
 class Multiplier(QuantumCircuit):
@@ -45,10 +46,19 @@ class Multiplier(QuantumCircuit):
 
     """
 
+    @deprecate_func(
+        since="1.3",
+        additional_msg=(
+            "Use the MultiplierGate provided in qiskit.circuit.library.arithmetic instead. "
+            "For different multiplier implementations, see "
+            "https://docs.quantum.ibm.com/api/qiskit/synthesis.",
+        ),
+        pending=True,
+    )
     def __init__(
         self,
         num_state_qubits: int,
-        num_result_qubits: Optional[int] = None,
+        num_result_qubits: int | None = None,
         name: str = "Multiplier",
     ) -> None:
         """
@@ -99,3 +109,84 @@ class Multiplier(QuantumCircuit):
             The number of result qubits.
         """
         return self._num_result_qubits
+
+
+class MultiplierGate(Gate):
+    r"""Compute the product of two equally sized qubit registers into a new register.
+
+    For two input registers :math:`|a\rangle_n`, :math:`|b\rangle_n` with :math:`n` qubits each
+    and an output register with :math:`2n` qubits, a multiplier performs the following operation
+
+    .. math::
+
+        |a\rangle_n |b\rangle_n |0\rangle_{t} \mapsto |a\rangle_n |b\rangle_n |a \cdot b\rangle_t
+
+    where :math:`t` is the number of bits used to represent the result. To completely store the result
+    of the multiplication without overflow we need :math:`t = 2n` bits.
+
+    The quantum register :math:`|a\rangle_n` (analogously :math:`|b\rangle_n` and
+    output register)
+
+    .. 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,
+        num_result_qubits: int | None = None,
+        label: str | None = None,
+    ) -> None:
+        """
+        Args:
+            num_state_qubits: The number of qubits in each of the input registers.
+            num_result_qubits: The number of result qubits to limit the output to.
+                Default value is ``2 * num_state_qubits`` to represent any possible
+                result from the multiplication of the two inputs.
+            name: The name of the circuit.
+        Raises:
+            ValueError: If ``num_state_qubits`` is smaller than 1.
+            ValueError: If ``num_result_qubits`` is smaller than ``num_state_qubits``.
+            ValueError: If ``num_result_qubits`` is larger than ``2 * num_state_qubits``.
+        """
+        if num_state_qubits < 1:
+            raise ValueError("The number of state qubits must be at least 1.")
+
+        if num_result_qubits is None:
+            num_result_qubits = 2 * num_state_qubits
+        elif num_result_qubits < num_state_qubits or num_result_qubits > 2 * num_state_qubits:
+            raise ValueError(
+                f"num_result_qubits ({num_result_qubits}) must be in between num_state_qubits "
+                f"({num_state_qubits}) and 2 * num_state_qubits ({2 * num_state_qubits})"
+            )
+
+        super().__init__("Multiplier", 2 * num_state_qubits + num_result_qubits, [], label=label)
+
+        self._num_state_qubits = num_state_qubits
+        self._num_result_qubits = num_result_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
+
+    @property
+    def num_result_qubits(self) -> int:
+        """The number of result qubits to limit the output to.
+
+        Returns:
+            The number of result qubits.
+        """
+        return self._num_result_qubits

qiskit/circuit/library/arithmetic/multipliers/rg_qft_multiplier.py

@@ -33,7 +33,7 @@ class RGQFTMultiplier(Multiplier):
     As an example, a circuit that performs a modular QFT multiplication on two 2-qubit
     sized input registers with an output register of 2 qubits, is as follows:
 
-    .. parsed-literal::
+    .. code-block:: text
 
           a_0: ────────────────────────────────────────■───────■──────■──────■────────────────
                                                        │       │      │      │
@@ -48,6 +48,13 @@ class RGQFTMultiplier(Multiplier):
         out_1: ┤1     ├─────────■───────────────■──────────────■─────────────■───────┤1      ├
                └──────┘                                                              └───────┘
 
+    .. seealso::
+
+        The :class:`.MultiplierGate` objects represents a multiplication, like this circuit class,
+        but allows 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 ``Multiplier=["qft_r17"]``.
+
     **References:**
 
     [1] Ruiz-Perez et al., Quantum arithmetic with the Quantum Fourier Transform, 2017.

qiskit/circuit/library/arithmetic/weighted_adder.py

@@ -45,7 +45,7 @@ class WeightedAdder(BlueprintCircuit):
     For an example where the state of 4 qubits is added into a sum register, the circuit can
     be schematically drawn as
 
-    .. parsed-literal::
+    .. code-block:: text
 
                    ┌────────┐
           state_0: ┤0       ├ | state_0 * weights[0]

qiskit/circuit/library/basis_change/qft.py

@@ -13,10 +13,10 @@
 """Define a Quantum Fourier Transform circuit (QFT) and a native gate (QFTGate)."""
 
 from __future__ import annotations
-import warnings
 import numpy as np
 
-from qiskit.circuit.quantumcircuit import QuantumCircuit, QuantumRegister, CircuitInstruction, Gate
+from qiskit.circuit.quantumcircuit import QuantumRegister, CircuitInstruction, Gate
+from qiskit.utils.deprecation import deprecate_func
 from ..blueprintcircuit import BlueprintCircuit
 
 
@@ -72,6 +72,14 @@ class QFT(BlueprintCircuit):
 
     """
 
+    @deprecate_func(
+        since="1.3",
+        additional_msg=(
+            "Use qiskit.circuit.library.QFTGate or qiskit.synthesis.qft.synth_qft_full instead, "
+            "for access to all previous arguments.",
+        ),
+        pending=True,
+    )
     def __init__(
         self,
         num_qubits: int | None = None,
@@ -232,22 +240,6 @@ class QFT(BlueprintCircuit):
         inverted._inverse = not self._inverse
         return inverted
 
-    def _warn_if_precision_loss(self):
-        """Issue a warning if constructing the circuit will lose precision.
-
-        If we need an angle smaller than ``pi * 2**-1022``, we start to lose precision by going into
-        the subnormal numbers.  We won't lose _all_ precision until an exponent of about 1075, but
-        beyond 1022 we're using fractional bits to represent leading zeros."""
-        max_num_entanglements = self.num_qubits - self.approximation_degree - 1
-        if max_num_entanglements > -np.finfo(float).minexp:  # > 1022 for doubles.
-            warnings.warn(
-                "precision loss in QFT."
-                f" The rotation needed to represent {max_num_entanglements} entanglements"
-                " is smaller than the smallest normal floating-point number.",
-                category=RuntimeWarning,
-                stacklevel=3,
-            )
-
     def _check_configuration(self, raise_on_failure: bool = True) -> bool:
         """Check if the current configuration is valid."""
         valid = True
@@ -255,7 +247,6 @@ class QFT(BlueprintCircuit):
             valid = False
             if raise_on_failure:
                 raise AttributeError("The number of qubits has not been set.")
-        self._warn_if_precision_loss()
         return valid
 
     def _build(self) -> None:
@@ -270,25 +261,16 @@ class QFT(BlueprintCircuit):
         if num_qubits == 0:
             return
 
-        circuit = QuantumCircuit(*self.qregs, name=self.name)
-        for j in reversed(range(num_qubits)):
-            circuit.h(j)
-            num_entanglements = max(0, j - max(0, self.approximation_degree - (num_qubits - j - 1)))
-            for k in reversed(range(j - num_entanglements, j)):
-                # Use negative exponents so that the angle safely underflows to zero, rather than
-                # using a temporary variable that overflows to infinity in the worst case.
-                lam = np.pi * (2.0 ** (k - j))
-                circuit.cp(lam, j, k)
-
-            if self.insert_barriers:
-                circuit.barrier()
-
-        if self._do_swaps:
-            for i in range(num_qubits // 2):
-                circuit.swap(i, num_qubits - i - 1)
-
-        if self._inverse:
-            circuit = circuit.inverse()
+        from qiskit.synthesis.qft import synth_qft_full
+
+        circuit = synth_qft_full(
+            num_qubits,
+            do_swaps=self._do_swaps,
+            insert_barriers=self._insert_barriers,
+            approximation_degree=self._approximation_degree,
+            inverse=self._inverse,
+            name=self.name,
+        )
 
         wrapped = circuit.to_instruction() if self.insert_barriers else circuit.to_gate()
         self.compose(wrapped, qubits=self.qubits, inplace=True)

qiskit/circuit/library/blueprintcircuit.py

@@ -94,6 +94,12 @@ class BlueprintCircuit(QuantumCircuit, ABC):
 
     @property
     def data(self):
+        """The circuit data (instructions and context).
+
+        Returns:
+            QuantumCircuitData: a list-like object containing the :class:`.CircuitInstruction`\\ s
+            for each instruction.
+        """
         if not self._is_built:
             self._build()
         return super().data
@@ -110,12 +116,70 @@ class BlueprintCircuit(QuantumCircuit, ABC):
 
     @property
     def num_parameters(self) -> int:
+        """The number of parameter objects in the circuit."""
         if not self._is_built:
             self._build()
         return super().num_parameters
 
     @property
     def parameters(self) -> ParameterView:
+        """The parameters defined in the circuit.
+
+        This attribute returns the :class:`.Parameter` objects in the circuit sorted
+        alphabetically. Note that parameters instantiated with a :class:`.ParameterVector`
+        are still sorted numerically.
+
+        Examples:
+
+            The snippet below shows that insertion order of parameters does not matter.
+
+            .. code-block:: python
+
+                >>> from qiskit.circuit import QuantumCircuit, Parameter
+                >>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant")
+                >>> circuit = QuantumCircuit(1)
+                >>> circuit.rx(b, 0)
+                >>> circuit.rz(elephant, 0)
+                >>> circuit.ry(a, 0)
+                >>> circuit.parameters  # sorted alphabetically!
+                ParameterView([Parameter(a), Parameter(b), Parameter(elephant)])
+
+            Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers.
+            The literal "10" comes before "2" in strict alphabetical sorting.
+
+            .. code-block:: python
+
+                >>> from qiskit.circuit import QuantumCircuit, Parameter
+                >>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")]
+                >>> circuit = QuantumCircuit(1)
+                >>> circuit.u(*angles, 0)
+                >>> circuit.draw()
+                   ┌─────────────────────────────┐
+                q: ┤ U(angle_1,angle_2,angle_10) ├
+                   └─────────────────────────────┘
+                >>> circuit.parameters
+                ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)])
+
+            To respect numerical sorting, a :class:`.ParameterVector` can be used.
+
+            .. code-block:: python
+
+                >>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector
+                >>> x = ParameterVector("x", 12)
+                >>> circuit = QuantumCircuit(1)
+                >>> for x_i in x:
+                ...     circuit.rx(x_i, 0)
+                >>> circuit.parameters
+                ParameterView([
+                    ParameterVectorElement(x[0]), ParameterVectorElement(x[1]),
+                    ParameterVectorElement(x[2]), ParameterVectorElement(x[3]),
+                    ..., ParameterVectorElement(x[11])
+                ])
+
+
+        Returns:
+            The sorted :class:`.Parameter` objects in the circuit.
+        """
         if not self._is_built:
             self._build()
         return super().parameters

qiskit/circuit/library/boolean_logic/__init__.py

@@ -12,7 +12,7 @@
 
 """The Boolean logic circuit library."""
 
-from .quantum_and import AND
-from .quantum_or import OR
-from .quantum_xor import XOR
-from .inner_product import InnerProduct
+from .quantum_and import AND, AndGate
+from .quantum_or import OR, OrGate
+from .quantum_xor import XOR, BitwiseXorGate, random_bitwise_xor
+from .inner_product import InnerProduct, InnerProductGate

qiskit/circuit/library/boolean_logic/inner_product.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,10 +11,11 @@
 # that they have been altered from the originals.
 
 
-"""InnerProduct circuit."""
+"""InnerProduct circuit and gate."""
 
 
-from qiskit.circuit import QuantumRegister, QuantumCircuit
+from qiskit.circuit import QuantumRegister, QuantumCircuit, Gate
+from qiskit.utils.deprecation import deprecate_func
 
 
 class InnerProduct(QuantumCircuit):
@@ -32,7 +33,7 @@ class InnerProduct(QuantumCircuit):
     where the inner product of the top and bottom registers is 1. Otherwise it keeps
     the input intact.
 
-    .. parsed-literal::
+    .. code-block:: text
 
 
         q0_0: ─■──────────
@@ -61,6 +62,11 @@ class InnerProduct(QuantumCircuit):
            _generate_circuit_library_visualization(circuit)
     """
 
+    @deprecate_func(
+        since="1.3",
+        additional_msg="Use qiskit.circuit.library.InnerProductGate instead.",
+        pending=True,
+    )
     def __init__(self, num_qubits: int) -> None:
         """Return a circuit to compute the inner product of 2 n-qubit registers.
 
@@ -76,3 +82,74 @@ class InnerProduct(QuantumCircuit):
 
         super().__init__(*inner.qregs, name="inner_product")
         self.compose(inner.to_gate(), qubits=self.qubits, inplace=True)
+
+
+class InnerProductGate(Gate):
+    r"""A 2n-qubit Boolean function that computes the inner product of
+    two n-qubit vectors over :math:`F_2`.
+
+    This implementation is a phase oracle which computes the following transform.
+
+    .. math::
+
+        \mathcal{IP}_{2n} : F_2^{2n} \rightarrow {-1, 1}
+        \mathcal{IP}_{2n}(x_1, \cdots, x_n, y_1, \cdots, y_n) = (-1)^{x.y}
+
+    The corresponding unitary is a diagonal, which induces a -1 phase on any inputs
+    where the inner product of the top and bottom registers is 1. Otherwise, it keeps
+    the input intact.
+
+    .. parsed-literal::
+
+
+        q0_0: ─■──────────
+               │
+        q0_1: ─┼──■───────
+               │  │
+        q0_2: ─┼──┼──■────
+               │  │  │
+        q0_3: ─┼──┼──┼──■─
+               │  │  │  │
+        q1_0: ─■──┼──┼──┼─
+                  │  │  │
+        q1_1: ────■──┼──┼─
+                     │  │
+        q1_2: ───────■──┼─
+                        │
+        q1_3: ──────────■─
+
+
+    Reference Circuit:
+        .. plot::
+
+           from qiskit.circuit import QuantumCircuit
+           from qiskit.circuit.library import InnerProductGate
+           from qiskit.visualization.library import _generate_circuit_library_visualization
+           circuit = QuantumCircuit(8)
+           circuit.append(InnerProductGate(4), [0, 1, 2, 3, 4, 5, 6, 7])
+           _generate_circuit_library_visualization(circuit)
+    """
+
+    def __init__(
+        self,
+        num_qubits: int,
+    ) -> None:
+        """
+        Args:
+            num_qubits: width of top and bottom registers (half total number of qubits).
+        """
+        super().__init__("inner_product", 2 * num_qubits, [])
+
+    def _define(self):
+        num_qubits = self.num_qubits // 2
+        qr_a = QuantumRegister(num_qubits, name="x")
+        qr_b = QuantumRegister(num_qubits, name="y")
+
+        circuit = QuantumCircuit(qr_a, qr_b, name="inner_product")
+        for i in range(num_qubits):
+            circuit.cz(qr_a[i], qr_b[i])
+
+        self.definition = circuit
+
+    def __eq__(self, other):
+        return isinstance(other, InnerProductGate) and self.num_qubits == other.num_qubits

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
+        )