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

qiskit/circuit/library/data_preparation/pauli_feature_map.py

@@ -11,17 +11,316 @@
 # that they have been altered from the originals.
 
 """The Pauli expansion circuit module."""
-from typing import Optional, Callable, List, Union, Sequence, Dict, Tuple
+
+from __future__ import annotations
+
+from collections.abc import Sequence, Mapping
+from typing import Optional, Callable, List, Union, Dict, Tuple
 from functools import reduce
 import numpy as np
 
 from qiskit.circuit import QuantumCircuit
-from qiskit.circuit import Parameter, ParameterVector
+from qiskit.circuit import Parameter, ParameterVector, ParameterExpression
 from qiskit.circuit.library.standard_gates import HGate
+from qiskit.utils.deprecation import deprecate_func
+from qiskit._accelerate.circuit_library import pauli_feature_map as _fast_map
 
 from ..n_local.n_local import NLocal
 
 
+def _normalize_entanglement(
+    entanglement: str | Mapping[int, Sequence[Sequence[int]]]
+) -> str | dict[int, list[tuple[int]]]:
+    if isinstance(entanglement, str):
+        return entanglement
+
+    return {
+        num_paulis: [tuple(connections) for connections in ent]
+        for num_paulis, ent in entanglement.items()
+    }
+
+
+def pauli_feature_map(
+    feature_dimension: int,
+    reps: int = 2,
+    entanglement: (
+        str
+        | Mapping[int, Sequence[Sequence[int]]]
+        | Callable[[int], str | Mapping[int, Sequence[Sequence[int]]]]
+    ) = "full",
+    alpha: float = 2.0,
+    paulis: list[str] | None = None,
+    data_map_func: Callable[[Parameter], ParameterExpression] | None = None,
+    parameter_prefix: str = "x",
+    insert_barriers: bool = False,
+    name: str = "PauliFeatureMap",
+) -> QuantumCircuit:
+    r"""The Pauli expansion circuit.
+
+    The Pauli expansion circuit is a data encoding circuit that transforms input data
+    :math:`\vec{x} \in \mathbb{R}^n`, where :math:`n` is the ``feature_dimension``, as
+
+    .. math::
+
+        U_{\Phi(\vec{x})}=\exp\left(i\sum_{S \in \mathcal{I}}
+        \phi_S(\vec{x})\prod_{i\in S} P_i\right).
+
+    Here, :math:`S` is a set of qubit indices that describes the connections in the feature map,
+    :math:`\mathcal{I}` is a set containing all these index sets, and
+    :math:`P_i \in \{I, X, Y, Z\}`. Per default the data-mapping
+    :math:`\phi_S` is
+
+    .. math::
+
+        \phi_S(\vec{x}) = \begin{cases}
+            x_i \text{ if } S = \{i\} \\
+            \prod_{j \in S} (\pi - x_j) \text{ if } |S| > 1
+            \end{cases}.
+
+    The possible connections can be set using the ``entanglement`` and ``paulis`` arguments.
+    For example, for single-qubit :math:`Z` rotations and two-qubit :math:`YY` interactions
+    between all qubit pairs, we can set::
+
+
+        circuit = pauli_feature_map(..., paulis=["Z", "YY"], entanglement="full")
+
+    which will produce blocks of the form
+
+    .. code-block:: text
+
+        ┌───┐┌─────────────┐┌──────────┐                                            ┌───────────┐
+        ┤ H ├┤ P(2.0*x[0]) ├┤ RX(pi/2) ├──■──────────────────────────────────────■──┤ RX(-pi/2) ├
+        ├───┤├─────────────┤├──────────┤┌─┴─┐┌────────────────────────────────┐┌─┴─┐├───────────┤
+        ┤ H ├┤ P(2.0*x[1]) ├┤ RX(pi/2) ├┤ X ├┤ P(2.0*(pi - x[0])*(pi - x[1])) ├┤ X ├┤ RX(-pi/2) ├
+        └───┘└─────────────┘└──────────┘└───┘└────────────────────────────────┘└───┘└───────────┘
+
+    The circuit contains ``reps`` repetitions of this transformation.
+
+    Please refer to :func:`.z_feature_map` for the case of single-qubit Pauli-:math:`Z` rotations
+    and to :func:`.zz_feature_map` for the single- and two-qubit Pauli-:math:`Z` rotations.
+
+    Examples:
+
+        >>> prep = pauli_feature_map(2, reps=1, paulis=["ZZ"])
+        >>> print(prep)
+             ┌───┐
+        q_0: ┤ H ├──■──────────────────────────────────────■──
+             ├───┤┌─┴─┐┌────────────────────────────────┐┌─┴─┐
+        q_1: ┤ H ├┤ X ├┤ P(2.0*(pi - x[0])*(pi - x[1])) ├┤ X ├
+             └───┘└───┘└────────────────────────────────┘└───┘
+
+        >>> prep = pauli_feature_map(2, reps=1, paulis=["Z", "XX"])
+        >>> print(prep)
+             ┌───┐┌─────────────┐┌───┐                                            ┌───┐
+        q_0: ┤ H ├┤ P(2.0*x[0]) ├┤ H ├──■──────────────────────────────────────■──┤ H ├
+             ├───┤├─────────────┤├───┤┌─┴─┐┌────────────────────────────────┐┌─┴─┐├───┤
+        q_1: ┤ H ├┤ P(2.0*x[1]) ├┤ H ├┤ X ├┤ P(2.0*(pi - x[0])*(pi - x[1])) ├┤ X ├┤ H ├
+             └───┘└─────────────┘└───┘└───┘└────────────────────────────────┘└───┘└───┘
+
+        >>> prep = pauli_feature_map(2, reps=1, paulis=["ZY"])
+        >>> print(prep)
+             ┌───┐┌──────────┐                                            ┌───────────┐
+        q_0: ┤ H ├┤ RX(pi/2) ├──■──────────────────────────────────────■──┤ RX(-pi/2) ├
+             ├───┤└──────────┘┌─┴─┐┌────────────────────────────────┐┌─┴─┐└───────────┘
+        q_1: ┤ H ├────────────┤ X ├┤ P(2.0*(pi - x[0])*(pi - x[1])) ├┤ X ├─────────────
+             └───┘            └───┘└────────────────────────────────┘└───┘
+
+        >>> from qiskit.circuit.library import EfficientSU2
+        >>> prep = pauli_feature_map(3, reps=3, paulis=["Z", "YY", "ZXZ"])
+        >>> wavefunction = EfficientSU2(3)
+        >>> classifier = prep.compose(wavefunction)
+        >>> classifier.num_parameters
+        27
+        >>> classifier.count_ops()
+        OrderedDict([('cx', 39), ('rx', 36), ('u1', 21), ('h', 15), ('ry', 12), ('rz', 12)])
+
+    References:
+
+    [1] Havlicek et al. Supervised learning with quantum enhanced feature spaces,
+    `Nature 567, 209-212 (2019) <https://www.nature.com/articles/s41586-019-0980-2>`__.
+    """
+    # create parameter vector used in the Pauli feature map
+    parameters = ParameterVector(parameter_prefix, feature_dimension)
+
+    # the Rust implementation expects the entanglement to be a str or list[tuple[int]] (or the
+    # callable to return these types), therefore we normalize the entanglement here
+    if callable(entanglement):
+        normalized = lambda offset: _normalize_entanglement(entanglement(offset))
+    else:
+        normalized = _normalize_entanglement(entanglement)
+
+    # construct from Rust
+    circuit = QuantumCircuit._from_circuit_data(
+        _fast_map(
+            feature_dimension,
+            paulis=paulis,
+            entanglement=normalized,
+            reps=reps,
+            parameters=parameters,
+            data_map_func=data_map_func,
+            alpha=alpha,
+            insert_barriers=insert_barriers,
+        ),
+        name=name,
+    )
+
+    return circuit
+
+
+def z_feature_map(
+    feature_dimension: int,
+    reps: int = 2,
+    entanglement: (
+        str | Sequence[Sequence[int]] | Callable[[int], str | Sequence[Sequence[int]]]
+    ) = "full",
+    alpha: float = 2.0,
+    data_map_func: Callable[[Parameter], ParameterExpression] | None = None,
+    parameter_prefix: str = "x",
+    insert_barriers: bool = False,
+    name: str = "ZFeatureMap",
+) -> QuantumCircuit:
+    """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 = z_feature_map(3, reps=3, insert_barriers=True)
+        >>> print(prep)
+             ┌───┐ ░ ┌─────────────┐ ░ ┌───┐ ░ ┌─────────────┐ ░ ┌───┐ ░ ┌─────────────┐
+        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 = z_feature_map(3, reps=1, data_map_func=data_map)
+        >>> print(prep)
+             ┌───┐┌──────────────────────┐
+        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).decompose()
+        >>> classifier = z_feature_map(3, reps=1) + ry
+        >>> print(classifier)
+             ┌───┐┌─────────────┐┌──────────┐      ┌──────────┐
+        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]) ├
+             └───┘└─────────────┘└──────────┘                  └──────────┘
+
+    """
+    return pauli_feature_map(
+        feature_dimension=feature_dimension,
+        reps=reps,
+        entanglement=entanglement,
+        alpha=alpha,
+        paulis=["z"],
+        data_map_func=data_map_func,
+        parameter_prefix=parameter_prefix,
+        insert_barriers=insert_barriers,
+        name=name,
+    )
+
+
+def zz_feature_map(
+    feature_dimension: int,
+    reps: int = 2,
+    entanglement: (
+        str | Sequence[Sequence[int]] | Callable[[int], str | Sequence[Sequence[int]]]
+    ) = "full",
+    alpha: float = 2.0,
+    data_map_func: Callable[[Parameter], ParameterExpression] | None = None,
+    parameter_prefix: str = "x",
+    insert_barriers: bool = False,
+    name: str = "ZZFeatureMap",
+) -> QuantumCircuit:
+    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:
+
+        >>> from qiskit.circuit.library import ZZFeatureMap
+        >>> prep = zz_feature_map(2, reps=1)
+        >>> print(prep)
+             ┌───┐┌─────────────┐
+        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 ├
+             └───┘└─────────────┘└───┘└────────────────────────────────┘└───┘
+
+        >>> from qiskit.circuit.library import EfficientSU2
+        >>> classifier = zz_feature_map(3) + EfficientSU2(3)
+        >>> classifier.num_parameters
+        15
+        >>> classifier.parameters  # 'x' for the data preparation, 'θ' for the SU2 parameters
+        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])
+        ])
+    """
+    return pauli_feature_map(
+        feature_dimension=feature_dimension,
+        reps=reps,
+        entanglement=entanglement,
+        alpha=alpha,
+        paulis=["z", "zz"],
+        data_map_func=data_map_func,
+        parameter_prefix=parameter_prefix,
+        insert_barriers=insert_barriers,
+        name=name,
+    )
+
+
 class PauliFeatureMap(NLocal):
     r"""The Pauli Expansion circuit.
 
@@ -54,13 +353,13 @@ class PauliFeatureMap(NLocal):
 
     which will produce blocks of the form
 
-    .. parsed-literal::
+    .. code-block:: text
 
-        ┌───┐┌──────────────┐┌──────────┐                                             ┌───────────┐
-        ┤ H ├┤ U1(2.0*x[0]) ├┤ RX(pi/2) ├──■───────────────────────────────────────■──┤ RX(-pi/2) ├
-        ├───┤├──────────────┤├──────────┤┌─┴─┐┌─────────────────────────────────┐┌─┴─┐├───────────┤
-        ┤ H ├┤ U1(2.0*x[1]) ├┤ RX(pi/2) ├┤ X ├┤ U1(2.0*(pi - x[0])*(pi - x[1])) ├┤ X ├┤ RX(-pi/2) ├
-        └───┘└──────────────┘└──────────┘└───┘└─────────────────────────────────┘└───┘└───────────┘
+        ┌───┐┌─────────────┐┌──────────┐                                            ┌───────────┐
+        ┤ H ├┤ P(2.0*x[0]) ├┤ RX(pi/2) ├──■──────────────────────────────────────■──┤ RX(-pi/2) ├
+        ├───┤├─────────────┤├──────────┤┌─┴─┐┌────────────────────────────────┐┌─┴─┐├───────────┤
+        ┤ H ├┤ P(2.0*x[1]) ├┤ RX(pi/2) ├┤ X ├┤ P(2.0*(pi - x[0])*(pi - x[1])) ├┤ X ├┤ RX(-pi/2) ├
+        └───┘└─────────────┘└──────────┘└───┘└────────────────────────────────┘└───┘└───────────┘
 
     The circuit contains ``reps`` repetitions of this transformation.
 
@@ -70,28 +369,28 @@ class PauliFeatureMap(NLocal):
     Examples:
 
         >>> prep = PauliFeatureMap(2, reps=1, paulis=['ZZ'])
-        >>> print(prep)
+        >>> print(prep.decompose())
              ┌───┐
-        q_0: ┤ H ├──■───────────────────────────────────────■──
-             ├───┤┌─┴─┐┌─────────────────────────────────┐┌─┴─┐
-        q_1: ┤ H ├┤ X ├┤ U1(2.0*(pi - x[0])*(pi - x[1])) ├┤ X ├
-             └───┘└───┘└─────────────────────────────────┘└───┘
+        q_0: ┤ H ├──■──────────────────────────────────────■──
+             ├───┤┌─┴─┐┌────────────────────────────────┐┌─┴─┐
+        q_1: ┤ H ├┤ X ├┤ P(2.0*(pi - x[0])*(pi - x[1])) ├┤ X ├
+             └───┘└───┘└────────────────────────────────┘└───┘
 
         >>> prep = PauliFeatureMap(2, reps=1, paulis=['Z', 'XX'])
-        >>> print(prep)
-             ┌───┐┌──────────────┐┌───┐                                             ┌───┐
-        q_0: ┤ H ├┤ U1(2.0*x[0]) ├┤ H ├──■───────────────────────────────────────■──┤ H ├
-             ├───┤├──────────────┤├───┤┌─┴─┐┌─────────────────────────────────┐┌─┴─┐├───┤
-        q_1: ┤ H ├┤ U1(2.0*x[1]) ├┤ H ├┤ X ├┤ U1(2.0*(pi - x[0])*(pi - x[1])) ├┤ X ├┤ H ├
-             └───┘└──────────────┘└───┘└───┘└─────────────────────────────────┘└───┘└───┘
+        >>> print(prep.decompose())
+             ┌───┐┌─────────────┐┌───┐                                            ┌───┐
+        q_0: ┤ H ├┤ P(2.0*x[0]) ├┤ H ├──■──────────────────────────────────────■──┤ H ├
+             ├───┤├─────────────┤├───┤┌─┴─┐┌────────────────────────────────┐┌─┴─┐├───┤
+        q_1: ┤ H ├┤ P(2.0*x[1]) ├┤ H ├┤ X ├┤ P(2.0*(pi - x[0])*(pi - x[1])) ├┤ X ├┤ H ├
+             └───┘└─────────────┘└───┘└───┘└────────────────────────────────┘└───┘└───┘
 
         >>> prep = PauliFeatureMap(2, reps=1, paulis=['ZY'])
-        >>> print(prep)
-             ┌───┐┌──────────┐                                             ┌───────────┐
-        q_0: ┤ H ├┤ RX(pi/2) ├──■───────────────────────────────────────■──┤ RX(-pi/2) ├
-             ├───┤└──────────┘┌─┴─┐┌─────────────────────────────────┐┌─┴─┐└───────────┘
-        q_1: ┤ H ├────────────┤ X ├┤ U1(2.0*(pi - x[0])*(pi - x[1])) ├┤ X ├─────────────
-             └───┘            └───┘└─────────────────────────────────┘└───┘
+        >>> print(prep.decompose())
+             ┌───┐┌──────────┐                                            ┌───────────┐
+        q_0: ┤ H ├┤ RX(pi/2) ├──■──────────────────────────────────────■──┤ RX(-pi/2) ├
+             ├───┤└──────────┘┌─┴─┐┌────────────────────────────────┐┌─┴─┐└───────────┘
+        q_1: ┤ H ├────────────┤ X ├┤ P(2.0*(pi - x[0])*(pi - x[1])) ├┤ X ├─────────────
+             └───┘            └───┘└────────────────────────────────┘└───┘
 
         >>> from qiskit.circuit.library import EfficientSU2
         >>> prep = PauliFeatureMap(3, reps=3, paulis=['Z', 'YY', 'ZXZ'])
@@ -104,13 +403,18 @@ class PauliFeatureMap(NLocal):
 
     References:
 
-
-
     [1] Havlicek et al. Supervised learning with quantum enhanced feature spaces,
     `Nature 567, 209-212 (2019) <https://www.nature.com/articles/s41586-019-0980-2>`__.
-
     """
 
+    @deprecate_func(
+        since="1.3",
+        additional_msg=(
+            "Use the pauli_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: Optional[int] = None,
@@ -161,6 +465,7 @@ class PauliFeatureMap(NLocal):
             name=name,
         )
 
+        self._prefix = parameter_prefix
         self._data_map_func = data_map_func or self_product
         self._paulis = paulis or ["Z", "ZZ"]
         self._alpha = alpha
@@ -217,6 +522,11 @@ class PauliFeatureMap(NLocal):
 
     @property
     def entanglement_blocks(self):
+        """The blocks in the entanglement layers.
+
+        Returns:
+            The blocks in the entanglement layers.
+        """
         return [self.pauli_block(pauli) for pauli in self._paulis]
 
     @entanglement_blocks.setter
@@ -275,7 +585,10 @@ class PauliFeatureMap(NLocal):
                 if pauli == "X":
                     circuit.h(i)
                 elif pauli == "Y":
-                    circuit.rx(-np.pi / 2 if inverse else np.pi / 2, i)
+                    if inverse:
+                        circuit.sxdg(i)
+                    else:
+                        circuit.sx(i)
 
         def cx_chain(circuit, inverse=False):
             num_cx = len(indices) - 1

qiskit/circuit/library/fourier_checking.py

@@ -12,13 +12,14 @@
 
 """Fourier checking circuit."""
 
-from typing import List
-
+from collections.abc import Sequence
 import math
+
 from qiskit.circuit import QuantumCircuit
 from qiskit.circuit.exceptions import CircuitError
+from qiskit.utils.deprecation import deprecate_func
 
-from .generalized_gates.diagonal import Diagonal
+from .generalized_gates.diagonal import Diagonal, DiagonalGate
 
 
 class FourierChecking(QuantumCircuit):
@@ -52,7 +53,12 @@ class FourierChecking(QuantumCircuit):
     `arXiv:1411.5729 <https://arxiv.org/abs/1411.5729>`_
     """
 
-    def __init__(self, f: List[int], g: List[int]) -> None:
+    @deprecate_func(
+        since="1.3",
+        additional_msg="Use qiskit.circuit.library.fourier_checking instead.",
+        pending=True,
+    )
+    def __init__(self, f: Sequence[int], g: Sequence[int]) -> None:
         """Create Fourier checking circuit.
 
         Args:
@@ -81,17 +87,72 @@ class FourierChecking(QuantumCircuit):
                 "{1, -1}."
             )
 
-        circuit = QuantumCircuit(num_qubits, name=f"fc: {f}, {g}")
-
+        # This definition circuit is not replaced by the circuit produced by fourier_checking,
+        # as the latter produces a slightly different circuit, with DiagonalGates instead
+        # of Diagonal circuits.
+        circuit = QuantumCircuit(int(num_qubits), name=f"fc: {f}, {g}")
         circuit.h(circuit.qubits)
-
         circuit.compose(Diagonal(f), inplace=True)
-
         circuit.h(circuit.qubits)
-
         circuit.compose(Diagonal(g), inplace=True)
-
         circuit.h(circuit.qubits)
-
         super().__init__(*circuit.qregs, name=circuit.name)
         self.compose(circuit.to_gate(), qubits=self.qubits, inplace=True)
+
+
+def fourier_checking(f: Sequence[int], g: Sequence[int]) -> QuantumCircuit:
+    """Fourier checking circuit.
+
+    The circuit for the Fourier checking algorithm, introduced in [1],
+    involves a layer of Hadamards, the function :math:`f`, another layer of
+    Hadamards, the function :math:`g`, followed by a final layer of Hadamards.
+    The functions :math:`f` and :math:`g` are classical functions realized
+    as phase oracles (diagonal operators with {-1, 1} on the diagonal).
+
+    The probability of observing the all-zeros string is :math:`p(f,g)`.
+    The algorithm solves the promise Fourier checking problem,
+    which decides if f is correlated with the Fourier transform
+    of g, by testing if :math:`p(f,g) <= 0.01` or :math:`p(f,g) >= 0.05`,
+    promised that one or the other of these is true.
+
+    The functions :math:`f` and :math:`g` are currently implemented
+    from their truth tables but could be represented concisely and
+    implemented efficiently for special classes of functions.
+
+    Fourier checking is a special case of :math:`k`-fold forrelation [2].
+
+    **Reference Circuit:**
+
+    .. plot::
+       :include-source:
+
+       from qiskit.circuit.library import fourier_checking
+       circuit = fourier_checking([1, -1, -1, -1], [1, 1, -1, -1])
+       circuit.draw('mpl')
+
+    **Reference:**
+
+    [1] S. Aaronson, BQP and the Polynomial Hierarchy, 2009 (Section 3.2).
+    `arXiv:0910.4698 <https://arxiv.org/abs/0910.4698>`_
+
+    [2] S. Aaronson, A. Ambainis, Forrelation: a problem that
+    optimally separates quantum from classical computing, 2014.
+    `arXiv:1411.5729 <https://arxiv.org/abs/1411.5729>`_
+    """
+    num_qubits = math.log2(len(f))
+
+    if len(f) != len(g) or num_qubits == 0 or not num_qubits.is_integer():
+        raise CircuitError(
+            "The functions f and g must be given as truth "
+            "tables, each as a list of 2**n entries of "
+            "{1, -1}."
+        )
+    num_qubits = int(num_qubits)
+
+    circuit = QuantumCircuit(num_qubits, name=f"fc: {f}, {g}")
+    circuit.h(circuit.qubits)
+    circuit.append(DiagonalGate(f), range(num_qubits))
+    circuit.h(circuit.qubits)
+    circuit.append(DiagonalGate(g), range(num_qubits))
+    circuit.h(circuit.qubits)
+    return circuit

qiskit/circuit/library/generalized_gates/__init__.py

@@ -14,7 +14,7 @@
 
 from .diagonal import Diagonal, DiagonalGate
 from .permutation import Permutation, PermutationGate
-from .mcmt import MCMT, MCMTVChain
+from .mcmt import MCMT, MCMTVChain, MCMTGate
 from .gms import GMS, MSGate
 from .gr import GR, GRX, GRY, GRZ
 from .pauli import PauliGate