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

qiskit/circuit/library/n_local/real_amplitudes.py

@@ -13,15 +13,123 @@
 """The real-amplitudes 2-local circuit."""
 
 from __future__ import annotations
-from collections.abc import Callable
+from collections.abc import Callable, Iterable
 
 import numpy as np
 
 from qiskit.circuit import QuantumCircuit
 from qiskit.circuit.library.standard_gates import RYGate, CXGate
+from qiskit.utils.deprecation import deprecate_func
+from .n_local import n_local, BlockEntanglement
 from .two_local import TwoLocal
 
 
+def real_amplitudes(
+    num_qubits: int,
+    entanglement: (
+        BlockEntanglement
+        | Iterable[BlockEntanglement]
+        | Callable[[int], BlockEntanglement | Iterable[BlockEntanglement]]
+    ) = "reverse_linear",
+    reps: int = 3,
+    skip_unentangled_qubits: bool = False,
+    skip_final_rotation_layer: bool = False,
+    parameter_prefix: str = "θ",
+    insert_barriers: bool = False,
+    name: str = "RealAmplitudes",
+) -> QuantumCircuit:
+    r"""Construct a real-amplitudes 2-local circuit.
+
+    This circuit is a heuristic trial wave function used, e.g., as ansatz in chemistry, optimization
+    or machine learning applications. The circuit consists of alternating layers of :math:`Y`
+    rotations and :math:`CX` entanglements. The entanglement pattern can be user-defined or selected
+    from a predefined set. This circuit is  "real amplitudes" since the prepared quantum states will
+    only have real amplitudes.
+
+    For example a ``real_amplitudes`` circuit with 2 repetitions on 3 qubits with ``"reverse_linear"``
+    entanglement is
+
+    .. parsed-literal::
+
+         ┌──────────┐ ░            ░ ┌──────────┐ ░            ░ ┌──────────┐
+         ┤ Ry(θ[0]) ├─░────────■───░─┤ Ry(θ[3]) ├─░────────■───░─┤ Ry(θ[6]) ├
+         ├──────────┤ ░      ┌─┴─┐ ░ ├──────────┤ ░      ┌─┴─┐ ░ ├──────────┤
+         ┤ Ry(θ[1]) ├─░───■──┤ X ├─░─┤ Ry(θ[4]) ├─░───■──┤ X ├─░─┤ Ry(θ[7]) ├
+         ├──────────┤ ░ ┌─┴─┐└───┘ ░ ├──────────┤ ░ ┌─┴─┐└───┘ ░ ├──────────┤
+         ┤ Ry(θ[2]) ├─░─┤ X ├──────░─┤ Ry(θ[5]) ├─░─┤ X ├──────░─┤ Ry(θ[8]) ├
+         └──────────┘ ░ └───┘      ░ └──────────┘ ░ └───┘      ░ └──────────┘
+
+    The entanglement can be set using the ``entanglement`` keyword as string or a list of
+    index-pairs. See the documentation of :func:`.n_local`. Additional options that can be set include
+    the number of repetitions, skipping rotation gates on qubits that are not entangled, leaving out
+    the final rotation layer and inserting barriers in between the rotation and entanglement
+    layers.
+
+    Examples:
+
+        .. plot::
+           :include-source:
+           :context:
+
+           from qiskit.circuit.library import real_amplitudes
+
+           ansatz = real_amplitudes(3, reps=2)  # create the circuit on 3 qubits
+           ansatz.draw("mpl")
+
+        .. plot::
+           :include-source:
+           :context:
+
+           ansatz = real_amplitudes(3, entanglement="full", reps=2)  # it is the same unitary as above
+           ansatz.draw("mpl")
+
+        .. plot::
+           :include-source:
+           :context:
+
+           ansatz = real_amplitudes(3, entanglement="linear", reps=2, insert_barriers=True)
+           ansatz.draw("mpl")
+
+        .. plot::
+           :include-source:
+           :context:
+
+           ansatz = real_amplitudes(4, reps=2, entanglement=[[0,3], [0,2]], skip_unentangled_qubits=True)
+           ansatz.draw("mpl")
+
+    Args:
+        num_qubits: The number of qubits of the RealAmplitudes circuit.
+        reps: Specifies how often the structure of a rotation layer followed by an entanglement
+            layer is repeated.
+        entanglement: The indices specifying on which qubits the input blocks act.
+            See :func:`.n_local` for detailed information.
+        skip_final_rotation_layer: Whether a final rotation layer is added to the circuit.
+        skip_unentangled_qubits: If ``True``, the rotation gates act only on qubits that
+            are entangled. If ``False``, the rotation gates act on all qubits.
+        parameter_prefix: The name of the free parameters.
+        insert_barriers: If True, barriers are inserted in between each layer. If False,
+            no barriers are inserted.
+        name: The name of the circuit.
+
+    Returns:
+        A real-amplitudes circuit.
+    """
+
+    return n_local(
+        num_qubits,
+        ["ry"],
+        ["cx"],
+        entanglement,
+        reps,
+        insert_barriers,
+        parameter_prefix,
+        True,
+        skip_final_rotation_layer,
+        skip_unentangled_qubits,
+        name,
+    )
+
+
 class RealAmplitudes(TwoLocal):
     r"""The real-amplitudes 2-local circuit.
 
@@ -35,7 +143,8 @@ class RealAmplitudes(TwoLocal):
     For example a ``RealAmplitudes`` circuit with 2 repetitions on 3 qubits with ``'reverse_linear'``
     entanglement is
 
-    .. parsed-literal::
+    .. code-block:: text
+
          ┌──────────┐ ░            ░ ┌──────────┐ ░            ░ ┌──────────┐
          ┤ Ry(θ[0]) ├─░────────■───░─┤ Ry(θ[3]) ├─░────────■───░─┤ Ry(θ[6]) ├
          ├──────────┤ ░      ┌─┴─┐ ░ ├──────────┤ ░      ┌─┴─┐ ░ ├──────────┤
@@ -58,7 +167,7 @@ class RealAmplitudes(TwoLocal):
     Examples:
 
         >>> ansatz = RealAmplitudes(3, reps=2)  # create the circuit on 3 qubits
-        >>> print(ansatz)
+        >>> print(ansatz.decompose())
              ┌──────────┐                 ┌──────────┐                 ┌──────────┐
         q_0: ┤ Ry(θ[0]) ├──────────■──────┤ Ry(θ[3]) ├──────────■──────┤ Ry(θ[6]) ├
              ├──────────┤        ┌─┴─┐    ├──────────┤        ┌─┴─┐    ├──────────┤
@@ -67,7 +176,7 @@ class RealAmplitudes(TwoLocal):
         q_2: ┤ Ry(θ[2]) ├┤ X ├┤ Ry(θ[5]) ├────────────┤ X ├┤ Ry(θ[8]) ├────────────
              └──────────┘└───┘└──────────┘            └───┘└──────────┘
 
-        >>> ansatz = RealAmplitudes(3, entanglement='full', reps=2)  # it is the same unitary as above
+        >>> ansatz = RealAmplitudes(3, entanglement='full', reps=2, flatten=True)
         >>> print(ansatz)
              ┌──────────┐          ┌──────────┐                      ┌──────────┐
         q_0: ┤ RY(θ[0]) ├──■────■──┤ RY(θ[3]) ├──────────────■────■──┤ RY(θ[6]) ├────────────
@@ -77,7 +186,8 @@ class RealAmplitudes(TwoLocal):
         q_2: ┤ RY(θ[2]) ├─────┤ X ├───┤ X ├────┤ RY(θ[5]) ├─────┤ X ├───┤ X ├────┤ RY(θ[8]) ├
              └──────────┘     └───┘   └───┘    └──────────┘     └───┘   └───┘    └──────────┘
 
-        >>> ansatz = RealAmplitudes(3, entanglement='linear', reps=2, insert_barriers=True)
+        >>> ansatz = RealAmplitudes(3, entanglement='linear', reps=2, insert_barriers=True,
+        ... flatten=True)
         >>> qc = QuantumCircuit(3)  # create a circuit and append the RY variational form
         >>> qc.compose(ansatz, inplace=True)
         >>> qc.draw()
@@ -89,7 +199,8 @@ class RealAmplitudes(TwoLocal):
         q_2: ┤ RY(θ[2]) ├─░──────┤ X ├─░─┤ RY(θ[5]) ├─░──────┤ X ├─░─┤ RY(θ[8]) ├
              └──────────┘ ░      └───┘ ░ └──────────┘ ░      └───┘ ░ └──────────┘
 
-        >>> ansatz = RealAmplitudes(4, reps=1, entanglement='circular', insert_barriers=True)
+        >>> ansatz = RealAmplitudes(4, reps=1, entanglement='circular', insert_barriers=True,
+        ... flatten=True)
         >>> print(ansatz)
              ┌──────────┐ ░ ┌───┐                ░ ┌──────────┐
         q_0: ┤ RY(θ[0]) ├─░─┤ X ├──■─────────────░─┤ RY(θ[4]) ├
@@ -102,7 +213,7 @@ class RealAmplitudes(TwoLocal):
              └──────────┘ ░                └───┘ ░ └──────────┘
 
         >>> ansatz = RealAmplitudes(4, reps=2, entanglement=[[0,3], [0,2]],
-        ... skip_unentangled_qubits=True)
+        ... skip_unentangled_qubits=True, flatten=True)
         >>> print(ansatz)
              ┌──────────┐                 ┌──────────┐                 ┌──────────┐
         q_0: ┤ RY(θ[0]) ├──■───────■──────┤ RY(θ[3]) ├──■───────■──────┤ RY(θ[6]) ├
@@ -114,8 +225,17 @@ class RealAmplitudes(TwoLocal):
         q_3: ┤ RY(θ[2]) ├┤ X ├┤ RY(θ[5]) ├────────────┤ X ├┤ RY(θ[8]) ├────────────
              └──────────┘└───┘└──────────┘            └───┘└──────────┘
 
+    .. seealso::
+
+        The :func:`.real_amplitudes` function constructs a functionally equivalent circuit, but faster.
+
     """
 
+    @deprecate_func(
+        since="1.3",
+        additional_msg="Use the function qiskit.circuit.library.real_amplitudes instead.",
+        pending=True,
+    )
     def __init__(
         self,
         num_qubits: int | None = None,

qiskit/circuit/library/n_local/two_local.py

@@ -18,6 +18,7 @@ from collections.abc import Callable, Sequence
 
 from qiskit.circuit.quantumcircuit import QuantumCircuit
 from qiskit.circuit import Gate, Instruction
+from qiskit.utils.deprecation import deprecate_func
 
 from .n_local import NLocal
 from ..standard_gates import get_standard_gate_name_mapping
@@ -76,7 +77,7 @@ class TwoLocal(NLocal):
     Examples:
 
         >>> two = TwoLocal(3, 'ry', 'cx', 'linear', reps=2, insert_barriers=True)
-        >>> print(two)  # decompose the layers into standard gates
+        >>> print(two.decompose())  # decompose the layers into standard gates
              ┌──────────┐ ░            ░ ┌──────────┐ ░            ░ ┌──────────┐
         q_0: ┤ Ry(θ[0]) ├─░───■────────░─┤ Ry(θ[3]) ├─░───■────────░─┤ Ry(θ[6]) ├
              ├──────────┤ ░ ┌─┴─┐      ░ ├──────────┤ ░ ┌─┴─┐      ░ ├──────────┤
@@ -85,10 +86,10 @@ class TwoLocal(NLocal):
         q_2: ┤ Ry(θ[2]) ├─░──────┤ X ├─░─┤ Ry(θ[5]) ├─░──────┤ X ├─░─┤ Ry(θ[8]) ├
              └──────────┘ ░      └───┘ ░ └──────────┘ ░      └───┘ ░ └──────────┘
 
-        >>> two = TwoLocal(3, ['ry','rz'], 'cz', 'full', reps=1, insert_barriers=True)
+        >>> two = TwoLocal(3, ['ry','rz'], 'cz', 'full', reps=1, insert_barriers=True, flatten=True)
         >>> qc = QuantumCircuit(3)
         >>> qc &= two
-        >>> print(qc.decompose().draw())
+        >>> print(qc.draw())
              ┌──────────┐┌──────────┐ ░           ░ ┌──────────┐ ┌──────────┐
         q_0: ┤ Ry(θ[0]) ├┤ Rz(θ[3]) ├─░──■──■─────░─┤ Ry(θ[6]) ├─┤ Rz(θ[9]) ├
              ├──────────┤├──────────┤ ░  │  │     ░ ├──────────┤┌┴──────────┤
@@ -98,7 +99,7 @@ class TwoLocal(NLocal):
              └──────────┘└──────────┘ ░           ░ └──────────┘└───────────┘
 
         >>> entangler_map = [[0, 1], [1, 2], [2, 0]]  # circular entanglement for 3 qubits
-        >>> two = TwoLocal(3, 'x', 'crx', entangler_map, reps=1)
+        >>> two = TwoLocal(3, 'x', 'crx', entangler_map, reps=1, flatten=True)
         >>> print(two)  # note: no barriers inserted this time!
                 ┌───┐                             ┌──────────┐┌───┐
         q_0: |0>┤ X ├─────■───────────────────────┤ Rx(θ[2]) ├┤ X ├
@@ -109,9 +110,9 @@ class TwoLocal(NLocal):
                 └───┘            └──────────┘                 └───┘
 
         >>> entangler_map = [[0, 3], [0, 2]]  # entangle the first and last two-way
-        >>> two = TwoLocal(4, [], 'cry', entangler_map, reps=1)
+        >>> two = TwoLocal(4, [], 'cry', entangler_map, reps=1, flatten=True)
         >>> circuit = two.compose(two)
-        >>> print(circuit.decompose().draw())  # note, that the parameters are the same!
+        >>> print(circuit.draw())  # note, that the parameters are the same!
         q_0: ─────■───────────■───────────■───────────■──────
                   │           │           │           │
         q_1: ─────┼───────────┼───────────┼───────────┼──────
@@ -123,7 +124,8 @@ class TwoLocal(NLocal):
 
         >>> layer_1 = [(0, 1), (0, 2)]
         >>> layer_2 = [(1, 2)]
-        >>> two = TwoLocal(3, 'x', 'cx', [layer_1, layer_2], reps=2, insert_barriers=True)
+        >>> two = TwoLocal(3, 'x', 'cx', [layer_1, layer_2], reps=2, insert_barriers=True,
+        ... flatten=True)
         >>> print(two)
              ┌───┐ ░            ░ ┌───┐ ░       ░ ┌───┐
         q_0: ┤ X ├─░───■────■───░─┤ X ├─░───────░─┤ X ├
@@ -135,6 +137,11 @@ class TwoLocal(NLocal):
 
     """
 
+    @deprecate_func(
+        since="1.3",
+        additional_msg="Use the function qiskit.circuit.library.n_local instead.",
+        pending=True,
+    )
     def __init__(
         self,
         num_qubits: int | None = None,

qiskit/circuit/library/overlap.py

@@ -16,6 +16,7 @@ from qiskit.circuit import QuantumCircuit, Gate
 from qiskit.circuit.parametervector import ParameterVector
 from qiskit.circuit.exceptions import CircuitError
 from qiskit.circuit import Barrier
+from qiskit.utils.deprecation import deprecate_func
 
 
 class UnitaryOverlap(QuantumCircuit):
@@ -41,13 +42,13 @@ class UnitaryOverlap(QuantumCircuit):
         from qiskit.circuit.library import EfficientSU2, UnitaryOverlap
         from qiskit.primitives import Sampler
 
-        # get two circuit to prepare states of which we comput the overlap
+        # get two circuit to prepare states of which we compute the overlap
         circuit = EfficientSU2(2, reps=1)
         unitary1 = circuit.assign_parameters(np.random.random(circuit.num_parameters))
         unitary2 = circuit.assign_parameters(np.random.random(circuit.num_parameters))
 
         # create the overlap circuit
-        overlap = UnitaryOverap(unitary1, unitary2)
+        overlap = UnitaryOverlap(unitary1, unitary2)
 
         # sample from the overlap
         sampler = Sampler(options={"shots": 100})
@@ -58,6 +59,11 @@ class UnitaryOverlap(QuantumCircuit):
 
     """
 
+    @deprecate_func(
+        since="1.3",
+        additional_msg="Use qiskit.circuit.library.unitary_overlap instead.",
+        pending=True,
+    )
     def __init__(
         self,
         unitary1: QuantumCircuit,
@@ -80,30 +86,9 @@ class UnitaryOverlap(QuantumCircuit):
             CircuitError: Number of qubits in ``unitary1`` and ``unitary2`` does not match.
             CircuitError: Inputs contain measurements and/or resets.
         """
-        # check inputs are valid
-        if unitary1.num_qubits != unitary2.num_qubits:
-            raise CircuitError(
-                f"Number of qubits in unitaries does "
-                f"not match: {unitary1.num_qubits} != {unitary2.num_qubits}."
-            )
-
-        unitaries = [unitary1, unitary2]
-        for unitary in unitaries:
-            _check_unitary(unitary)
-
-        # Vectors of new parameters, if any. Need the unitaries in a list here to ensure
-        # we can overwrite them.
-        for i, prefix in enumerate([prefix1, prefix2]):
-            if unitaries[i].num_parameters > 0:
-                new_params = ParameterVector(prefix, unitaries[i].num_parameters)
-                unitaries[i] = unitaries[i].assign_parameters(new_params)
-
-        # Generate the actual overlap circuit
-        super().__init__(unitaries[0].num_qubits, name="UnitaryOverlap")
-        self.compose(unitaries[0], inplace=True)
-        if insert_barrier:
-            self.barrier()
-        self.compose(unitaries[1].inverse(), inplace=True)
+        circuit = unitary_overlap(unitary1, unitary2, prefix1, prefix2, insert_barrier)
+        super().__init__(*circuit.qregs, name=circuit.name)
+        self.compose(circuit, qubits=self.qubits, inplace=True)
 
 
 def _check_unitary(circuit):
@@ -115,3 +100,83 @@ def _check_unitary(circuit):
                 "One or more instructions cannot be converted to"
                 f' a gate. "{instruction.operation.name}" is not a gate instruction'
             )
+
+
+def unitary_overlap(
+    unitary1: QuantumCircuit,
+    unitary2: QuantumCircuit,
+    prefix1: str = "p1",
+    prefix2: str = "p2",
+    insert_barrier: bool = False,
+) -> QuantumCircuit:
+    r"""Circuit that returns the overlap between two unitaries :math:`U_2^{\dag} U_1`.
+
+    The input quantum circuits must represent unitary operations, since they must be invertible.
+    If the inputs will have parameters, they are replaced by :class:`.ParameterVector`\s with
+    names `"p1"` (for circuit ``unitary1``) and `"p2"` (for circuit ``unitary_2``) in the output
+    circuit.
+
+    This circuit is usually employed in computing the fidelity:
+
+    .. math::
+
+        \left|\langle 0| U_2^{\dag} U_1|0\rangle\right|^{2}
+
+    by computing the probability of being in the all-zeros bit-string, or equivalently,
+    the expectation value of projector :math:`|0\rangle\langle 0|`.
+
+    **Reference Circuit:**
+
+    .. plot::
+        :include-source:
+
+        import numpy as np
+        from qiskit.circuit.library import EfficientSU2, unitary_overlap
+
+        # get two circuit to prepare states of which we compute the overlap
+        circuit = EfficientSU2(2, reps=1)
+        unitary1 = circuit.assign_parameters(np.random.random(circuit.num_parameters))
+        unitary2 = circuit.assign_parameters(np.random.random(circuit.num_parameters))
+
+        # create the overlap circuit
+        overlap = unitary_overlap(unitary1, unitary2)
+        overlap.draw('mpl')
+
+    Args:
+        unitary1: Unitary acting on the ket vector.
+        unitary2: Unitary whose inverse operates on the bra vector.
+        prefix1: The name of the parameter vector associated to ``unitary1``,
+            if it is parameterized. Defaults to ``"p1"``.
+        prefix2: The name of the parameter vector associated to ``unitary2``,
+            if it is parameterized. Defaults to ``"p2"``.
+        insert_barrier: Whether to insert a barrier between the two unitaries.
+
+    Raises:
+        CircuitError: Number of qubits in ``unitary1`` and ``unitary2`` does not match.
+        CircuitError: Inputs contain measurements and/or resets.
+    """
+    # check inputs are valid
+    if unitary1.num_qubits != unitary2.num_qubits:
+        raise CircuitError(
+            f"Number of qubits in unitaries does "
+            f"not match: {unitary1.num_qubits} != {unitary2.num_qubits}."
+        )
+
+    unitaries = [unitary1, unitary2]
+    for unitary in unitaries:
+        _check_unitary(unitary)
+
+    # Vectors of new parameters, if any. Need the unitaries in a list here to ensure
+    # we can overwrite them.
+    for i, prefix in enumerate([prefix1, prefix2]):
+        if unitaries[i].num_parameters > 0:
+            new_params = ParameterVector(prefix, unitaries[i].num_parameters)
+            unitaries[i] = unitaries[i].assign_parameters(new_params)
+
+    # Generate the actual overlap circuit
+    circuit = QuantumCircuit(unitaries[0].num_qubits, name="UnitaryOverlap")
+    circuit.compose(unitaries[0], inplace=True)
+    if insert_barrier:
+        circuit.barrier()
+    circuit.compose(unitaries[1].inverse(), inplace=True)
+    return circuit

qiskit/circuit/library/pauli_evolution.py

@@ -14,10 +14,11 @@
 
 from __future__ import annotations
 
-from typing import Union, Optional, TYPE_CHECKING
+from typing import TYPE_CHECKING
 import numpy as np
 
 from qiskit.circuit.gate import Gate
+from qiskit.circuit.quantumcircuit import ParameterValueType
 from qiskit.circuit.parameterexpression import ParameterExpression
 from qiskit.quantum_info import Pauli, SparsePauliOp
 
@@ -56,6 +57,7 @@ class PauliEvolutionGate(Gate):
 
         X = SparsePauliOp("X")
         Z = SparsePauliOp("Z")
+        I = SparsePauliOp("I")
 
         # build the evolution gate
         operator = (Z ^ Z) - 0.1 * (X ^ I)
@@ -84,10 +86,10 @@ class PauliEvolutionGate(Gate):
 
     def __init__(
         self,
-        operator,
-        time: Union[int, float, ParameterExpression] = 1.0,
-        label: Optional[str] = None,
-        synthesis: Optional[EvolutionSynthesis] = None,
+        operator: Pauli | SparsePauliOp | list[Pauli | SparsePauliOp],
+        time: ParameterValueType = 1.0,
+        label: str | None = None,
+        synthesis: EvolutionSynthesis | None = None,
     ) -> None:
         """
         Args:
@@ -108,21 +110,23 @@ class PauliEvolutionGate(Gate):
         else:
             operator = _to_sparse_pauli_op(operator)
 
-        if synthesis is None:
-            from qiskit.synthesis.evolution import LieTrotter
-
-            synthesis = LieTrotter()
-
         if label is None:
             label = _get_default_label(operator)
 
         num_qubits = operator[0].num_qubits if isinstance(operator, list) else operator.num_qubits
         super().__init__(name="PauliEvolution", num_qubits=num_qubits, params=[time], label=label)
         self.operator = operator
+
+        if synthesis is None:
+            # pylint: disable=cyclic-import
+            from qiskit.synthesis.evolution import LieTrotter
+
+            synthesis = LieTrotter()
+
         self.synthesis = synthesis
 
     @property
-    def time(self) -> Union[float, ParameterExpression]:
+    def time(self) -> ParameterValueType:
         """Return the evolution time as stored in the gate parameters.
 
         Returns:
@@ -131,7 +135,7 @@ class PauliEvolutionGate(Gate):
         return self.params[0]
 
     @time.setter
-    def time(self, time: Union[float, ParameterExpression]) -> None:
+    def time(self, time: ParameterValueType) -> None:
         """Set the evolution time.
 
         Args:
@@ -143,9 +147,7 @@ class PauliEvolutionGate(Gate):
         """Unroll, where the default synthesis is matrix based."""
         self.definition = self.synthesis.synthesize(self)
 
-    def validate_parameter(
-        self, parameter: Union[int, float, ParameterExpression]
-    ) -> Union[float, ParameterExpression]:
+    def validate_parameter(self, parameter: ParameterValueType) -> ParameterValueType:
         """Gate parameters should be int, float, or ParameterExpression"""
         if isinstance(parameter, int):
             parameter = float(parameter)

qiskit/circuit/library/phase_estimation.py

@@ -12,11 +12,11 @@
 
 """Phase estimation circuit."""
 
-from typing import Optional
+from __future__ import annotations
 
 from qiskit.circuit import QuantumCircuit, QuantumRegister
-
-from .basis_change import QFT
+from qiskit.utils.deprecation import deprecate_func
+from qiskit.circuit.library import QFT
 
 
 class PhaseEstimation(QuantumCircuit):
@@ -49,11 +49,16 @@ class PhaseEstimation(QuantumCircuit):
 
     """
 
+    @deprecate_func(
+        since="1.3",
+        additional_msg="Use qiskit.circuit.library.phase_estimation instead.",
+        pending=True,
+    )
     def __init__(
         self,
         num_evaluation_qubits: int,
         unitary: QuantumCircuit,
-        iqft: Optional[QuantumCircuit] = None,
+        iqft: QuantumCircuit | None = None,
         name: str = "QPE",
     ) -> None:
         """
@@ -97,3 +102,74 @@ class PhaseEstimation(QuantumCircuit):
 
         super().__init__(*circuit.qregs, name=circuit.name)
         self.compose(circuit.to_gate(), qubits=self.qubits, inplace=True)
+
+
+def phase_estimation(
+    num_evaluation_qubits: int,
+    unitary: QuantumCircuit,
+    name: str = "QPE",
+) -> QuantumCircuit:
+    r"""Phase Estimation circuit.
+
+    In the Quantum Phase Estimation (QPE) algorithm [1, 2, 3], the Phase Estimation circuit is used
+    to estimate the phase :math:`\phi` of an eigenvalue :math:`e^{2\pi i\phi}` of a unitary operator
+    :math:`U`, provided with the corresponding eigenstate :math:`|\psi\rangle`.
+    That is
+
+    .. math::
+
+        U|\psi\rangle = e^{2\pi i\phi} |\psi\rangle
+
+    This estimation (and thereby this circuit) is a central routine to several well-known
+    algorithms, such as Shor's algorithm or Quantum Amplitude Estimation.
+
+    Args:
+        num_evaluation_qubits: The number of evaluation qubits.
+        unitary: The unitary operation :math:`U` which will be repeated and controlled.
+        name: The name of the circuit.
+
+    **Reference Circuit:**
+
+    .. plot::
+       :include-source:
+
+       from qiskit.circuit import QuantumCircuit
+       from qiskit.circuit.library import phase_estimation
+       unitary = QuantumCircuit(2)
+       unitary.x(0)
+       unitary.y(1)
+       circuit = phase_estimation(3, unitary)
+       circuit.draw('mpl')
+
+    **References:**
+
+    [1]: Kitaev, A. Y. (1995). Quantum measurements and the Abelian Stabilizer Problem. 1–22.
+        `quant-ph/9511026 <http://arxiv.org/abs/quant-ph/9511026>`_
+
+    [2]: Michael A. Nielsen and Isaac L. Chuang. 2011.
+         Quantum Computation and Quantum Information: 10th Anniversary Edition (10th ed.).
+         Cambridge University Press, New York, NY, USA.
+
+    [3]: Qiskit
+        `textbook <https://github.com/Qiskit/textbook/blob/main/notebooks/ch-algorithms/
+        quantum-phase-estimation.ipynb>`_
+
+    """
+    # pylint: disable=cyclic-import
+    from qiskit.circuit.library import PermutationGate, QFTGate
+
+    qr_eval = QuantumRegister(num_evaluation_qubits, "eval")
+    qr_state = QuantumRegister(unitary.num_qubits, "q")
+    circuit = QuantumCircuit(qr_eval, qr_state, name=name)
+
+    circuit.h(qr_eval)  # hadamards on evaluation qubits
+
+    for j in range(num_evaluation_qubits):  # controlled powers
+        circuit.compose(unitary.power(2**j).control(), qubits=[j] + qr_state[:], inplace=True)
+
+    circuit.append(QFTGate(num_evaluation_qubits).inverse(), qr_eval[:])
+
+    reversal_pattern = list(reversed(range(num_evaluation_qubits)))
+    circuit.append(PermutationGate(reversal_pattern), qr_eval[:])
+
+    return circuit