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

qiskit/circuit/library/n_local/efficient_su2.py

@@ -14,18 +14,121 @@
 
 from __future__ import annotations
 import typing
-from collections.abc import Callable
+from collections.abc import Callable, Iterable
 
 from numpy import pi
 
-from qiskit.circuit import QuantumCircuit
+from qiskit.circuit import QuantumCircuit, Gate
 from qiskit.circuit.library.standard_gates import RYGate, RZGate, CXGate
+from qiskit.utils.deprecation import deprecate_func
+from .n_local import n_local, BlockEntanglement
 from .two_local import TwoLocal
 
 if typing.TYPE_CHECKING:
     import qiskit  # pylint: disable=cyclic-import
 
 
+def efficient_su2(
+    num_qubits: int,
+    su2_gates: str | Gate | Iterable[str | Gate] | None = None,
+    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 = "EfficientSU2",
+):
+    r"""The hardware-efficient :math:`SU(2)` 2-local circuit.
+
+    The ``efficient_su2`` circuit consists of layers of single qubit operations spanned by
+    :math:`SU(2)` and CX entanglements. This is a heuristic pattern that can be used to prepare trial
+    wave functions for variational quantum algorithms or classification circuit for machine learning.
+
+    :math:`SU(2)` is the special unitary group of degree 2, its elements are :math:`2 \times 2`
+    unitary matrices with determinant 1, such as the Pauli rotation gates.
+
+    On 3 qubits and using the Pauli :math:`Y` and :math:`Z` rotations as single qubit gates, the
+    this circuit is represented by:
+
+    .. parsed-literal::
+
+        ┌──────────┐┌──────────┐ ░            ░       ░ ┌───────────┐┌───────────┐
+        ┤ RY(θ[0]) ├┤ RZ(θ[3]) ├─░────────■───░─ ... ─░─┤ RY(θ[12]) ├┤ RZ(θ[15]) ├
+        ├──────────┤├──────────┤ ░      ┌─┴─┐ ░       ░ ├───────────┤├───────────┤
+        ┤ RY(θ[1]) ├┤ RZ(θ[4]) ├─░───■──┤ X ├─░─ ... ─░─┤ RY(θ[13]) ├┤ RZ(θ[16]) ├
+        ├──────────┤├──────────┤ ░ ┌─┴─┐└───┘ ░       ░ ├───────────┤├───────────┤
+        ┤ RY(θ[2]) ├┤ RZ(θ[5]) ├─░─┤ X ├──────░─ ... ─░─┤ RY(θ[14]) ├┤ RZ(θ[17]) ├
+        └──────────┘└──────────┘ ░ └───┘      ░       ░ └───────────┘└───────────┘
+
+    Examples:
+
+        Per default, the ``"reverse_linear"`` entanglement is used, which, in the case of
+        CX gates, is equivalent to an all-to-all entanglement:
+
+        .. plot::
+            :include-source:
+            :context:
+
+            from qiskit.circuit.library import efficient_su2
+
+            circuit = efficient_su2(3, reps=1)
+            circuit.draw("mpl")
+
+        To specify which SU(2) gates should be used in the rotation layer, we can set the
+        ``su2_gates`` argument. In addition, we can change the entanglement structure.
+        For example:
+
+        .. plot::
+            :include-source:
+            :context:
+
+            circuit = efficient_su2(4, su2_gates=["rx", "y"], entanglement="circular", reps=1)
+            circuit.draw("mpl")
+
+    Args:
+        num_qubits: The number of qubits.
+        su2_gates: The :math:`SU(2)` single qubit gates to apply in single qubit gate layers.
+            If only one gate is provided, the same gate is applied to each qubit.
+            If a list of gates is provided, all gates are applied to each qubit in the provided
+            order.
+        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:
+        An efficient-SU(2) circuit.
+    """
+    if su2_gates is None:
+        su2_gates = ["ry", "rz"]
+
+    return n_local(
+        num_qubits,
+        su2_gates,
+        ["cx"],
+        entanglement,
+        reps,
+        insert_barriers,
+        parameter_prefix,
+        True,
+        skip_final_rotation_layer,
+        skip_unentangled_qubits,
+        name,
+    )
+
+
 class EfficientSU2(TwoLocal):
     r"""The hardware efficient SU(2) 2-local circuit.
 
@@ -39,7 +142,7 @@ class EfficientSU2(TwoLocal):
     On 3 qubits and using the Pauli :math:`Y` and :math:`Z` su2_gates as single qubit gates, the
     hardware efficient SU(2) circuit is represented by:
 
-    .. parsed-literal::
+    .. code-block:: text
 
         ┌──────────┐┌──────────┐ ░            ░       ░ ┌───────────┐┌───────────┐
         ┤ RY(θ[0]) ├┤ RZ(θ[3]) ├─░────────■───░─ ... ─░─┤ RY(θ[12]) ├┤ RZ(θ[15]) ├
@@ -55,7 +158,7 @@ class EfficientSU2(TwoLocal):
     Examples:
 
         >>> circuit = EfficientSU2(3, reps=1)
-        >>> print(circuit)
+        >>> print(circuit.decompose())
              ┌──────────┐┌──────────┐          ┌──────────┐┌──────────┐
         q_0: ┤ RY(θ[0]) ├┤ RZ(θ[3]) ├──■────■──┤ RY(θ[6]) ├┤ RZ(θ[9]) ├─────────────
              ├──────────┤├──────────┤┌─┴─┐  │  └──────────┘├──────────┤┌───────────┐
@@ -64,7 +167,8 @@ class EfficientSU2(TwoLocal):
         q_2: ┤ RY(θ[2]) ├┤ RZ(θ[5]) ├─────┤ X ├───┤ X ├────┤ RY(θ[8]) ├┤ RZ(θ[11]) ├
              └──────────┘└──────────┘     └───┘   └───┘    └──────────┘└───────────┘
 
-        >>> ansatz = EfficientSU2(4, su2_gates=['rx', 'y'], entanglement='circular', reps=1)
+        >>> ansatz = EfficientSU2(4, su2_gates=['rx', 'y'], entanglement='circular', reps=1,
+        ... flatten=True)
         >>> qc = QuantumCircuit(4)  # create a circuit and append the RY variational form
         >>> qc.compose(ansatz, inplace=True)
         >>> qc.draw()
@@ -78,8 +182,17 @@ class EfficientSU2(TwoLocal):
         q_3: ┤ RX(θ[3]) ├┤ Y ├──■──────────────────────┤ X ├────┤ RX(θ[7]) ├┤ Y ├
              └──────────┘└───┘                         └───┘    └──────────┘└───┘
 
+    .. seealso::
+
+        The :func:`.efficient_su2` function constructs a functionally equivalent circuit, but faster.
+
     """
 
+    @deprecate_func(
+        since="1.3",
+        additional_msg="Use the function qiskit.circuit.library.efficient_su2 instead.",
+        pending=True,
+    )
     def __init__(
         self,
         num_qubits: int | None = None,

qiskit/circuit/library/n_local/evolved_operator_ansatz.py

@@ -15,16 +15,263 @@
 from __future__ import annotations
 from collections.abc import Sequence
 
+import typing
+import warnings
+import itertools
 import numpy as np
 
 from qiskit.circuit.library.pauli_evolution import PauliEvolutionGate
 from qiskit.circuit.parameter import Parameter
+from qiskit.circuit.parametervector import ParameterVector
 from qiskit.circuit.quantumregister import QuantumRegister
 from qiskit.circuit.quantumcircuit import QuantumCircuit
 from qiskit.quantum_info import Operator, Pauli, SparsePauliOp
+from qiskit.quantum_info.operators.base_operator import BaseOperator
+
+from qiskit._accelerate.circuit_library import pauli_evolution
 
 from .n_local import NLocal
 
+if typing.TYPE_CHECKING:
+    from qiskit.synthesis.evolution import EvolutionSynthesis
+
+
+def evolved_operator_ansatz(
+    operators: BaseOperator | Sequence[BaseOperator],
+    reps: int = 1,
+    evolution: EvolutionSynthesis | None = None,
+    insert_barriers: bool = False,
+    name: str = "EvolvedOps",
+    parameter_prefix: str | Sequence[str] = "t",
+    remove_identities: bool = True,
+    flatten: bool | None = None,
+) -> QuantumCircuit:
+    r"""Construct an ansatz out of operator evolutions.
+
+    For a set of operators :math:`[O_1, ..., O_J]` and :math:`R` repetitions (``reps``), this circuit
+    is defined as
+
+    .. math::
+
+        \prod_{r=1}^{R} \left( \prod_{j=J}^1 e^{-i\theta_{j, r} O_j} \right)
+
+    where the exponentials :math:`exp(-i\theta O_j)` are expanded using the product formula
+    specified by ``evolution``.
+
+    Examples:
+
+        .. plot::
+            :include-source:
+
+            from qiskit.circuit.library import evolved_operator_ansatz
+            from qiskit.quantum_info import Pauli
+
+            ops = [Pauli("ZZI"), Pauli("IZZ"), Pauli("IXI")]
+            ansatz = evolved_operator_ansatz(ops, reps=3, insert_barriers=True)
+            ansatz.draw("mpl")
+
+    Args:
+        operators: The operators to evolve. Can be a single operator or a sequence thereof.
+        reps: The number of times to repeat the evolved operators.
+        evolution: A specification of which evolution synthesis to use for the
+            :class:`.PauliEvolutionGate`. Defaults to first order Trotterization. Note, that
+            operators of type :class:`.Operator` are evolved using the :class:`.HamiltonianGate`,
+            as there are no Hamiltonian terms to expand in Trotterization.
+        insert_barriers: Whether to insert barriers in between each evolution.
+        name: The name of the circuit.
+        parameter_prefix: Set the names of the circuit parameters. If a string, the same prefix
+            will be used for each parameters. Can also be a list to specify a prefix per
+            operator.
+        remove_identities: If ``True``, ignore identity operators (note that we do not check
+            :class:`.Operator` inputs). This will also remove parameters associated with identities.
+        flatten: If ``True``, a flat circuit is returned instead of nesting it inside multiple
+            layers of gate objects. Setting this to ``False`` is significantly less performant,
+            especially for parameter binding, but can be desirable for a cleaner visualization.
+    """
+    if reps < 0:
+        raise ValueError("reps must be a non-negative integer.")
+
+    if isinstance(operators, BaseOperator):
+        operators = [operators]
+    elif len(operators) == 0:
+        return QuantumCircuit()
+
+    num_operators = len(operators)
+    if not isinstance(parameter_prefix, str):
+        if num_operators != len(parameter_prefix):
+            raise ValueError(
+                f"Mismatching number of operators ({len(operators)}) and parameter_prefix "
+                f"({len(parameter_prefix)})."
+            )
+
+    num_qubits = operators[0].num_qubits
+    if remove_identities:
+        operators, parameter_prefix = _remove_identities(operators, parameter_prefix)
+
+    if any(op.num_qubits != num_qubits for op in operators):
+        raise ValueError("Inconsistent numbers of qubits in the operators.")
+
+    # get the total number of parameters
+    if isinstance(parameter_prefix, str):
+        parameters = ParameterVector(parameter_prefix, reps * num_operators)
+        param_iter = iter(parameters)
+    else:
+        # this creates the parameter vectors per operator, e.g.
+        #    [[a0, a1, a2, ...], [b0, b1, b2, ...], [c0, c1, c2, ...]]
+        # and turns them into an iterator
+        #    a0 -> b0 -> c0 -> a1 -> b1 -> c1 -> a2 -> ...
+        per_operator = [ParameterVector(prefix, reps).params for prefix in parameter_prefix]
+        param_iter = itertools.chain.from_iterable(zip(*per_operator))
+
+    # fast, Rust-path
+    if (
+        flatten is not False  # captures None and True
+        and evolution is None
+        and all(isinstance(op, SparsePauliOp) for op in operators)
+    ):
+        sparse_labels = [op.to_sparse_list() for op in operators]
+        expanded_paulis = []
+        for _ in range(reps):
+            for term in sparse_labels:
+                param = next(param_iter)
+                expanded_paulis += [
+                    (pauli, indices, 2 * coeff * param) for pauli, indices, coeff in term
+                ]
+
+        data = pauli_evolution(num_qubits, expanded_paulis, insert_barriers, False)
+        circuit = QuantumCircuit._from_circuit_data(data, add_regs=True)
+        circuit.name = name
+
+        return circuit
+
+    # slower, Python-path
+    if evolution is None:
+        from qiskit.synthesis.evolution import LieTrotter
+
+        evolution = LieTrotter(insert_barriers=insert_barriers)
+
+    circuit = QuantumCircuit(num_qubits, name=name)
+
+    # pylint: disable=cyclic-import
+    from qiskit.circuit.library.hamiltonian_gate import HamiltonianGate
+
+    for rep in range(reps):
+        for i, op in enumerate(operators):
+            if isinstance(op, Operator):
+                gate = HamiltonianGate(op, next(param_iter))
+                if flatten:
+                    warnings.warn(
+                        "Cannot flatten the evolution of an Operator, flatten is set to "
+                        "False for this operator."
+                    )
+                flatten_operator = False
+
+            elif isinstance(op, BaseOperator):
+                gate = PauliEvolutionGate(op, next(param_iter), synthesis=evolution)
+                flatten_operator = flatten is True or flatten is None
+            else:
+                raise ValueError(f"Unsupported operator type: {type(op)}")
+
+            if flatten_operator:
+                circuit.compose(gate.definition, inplace=True)
+            else:
+                circuit.append(gate, circuit.qubits)
+
+            if insert_barriers and (rep < reps - 1 or i < num_operators - 1):
+                circuit.barrier()
+
+    return circuit
+
+
+def hamiltonian_variational_ansatz(
+    hamiltonian: SparsePauliOp | Sequence[SparsePauliOp],
+    reps: int = 1,
+    insert_barriers: bool = False,
+    name: str = "HVA",
+    parameter_prefix: str = "t",
+) -> QuantumCircuit:
+    r"""Construct a Hamiltonian variational ansatz.
+
+    For a Hamiltonian :math:`H = \sum_{k=1}^K H_k` where the terms :math:`H_k` consist of only
+    commuting Paulis, but the terms do not commute among each other :math:`[H_k, H_{k'}] \neq 0`, the
+    Hamiltonian variational ansatz (HVA) is
+
+    .. math::
+
+        \prod_{r=1}^{R} \left( \prod_{k=K}^1 e^{-i\theta_{k, r} H_k} \right)
+
+    where the exponentials :math:`exp(-i\theta H_k)` are implemented exactly [1, 2]. Note that this
+    differs from :func:`.evolved_operator_ansatz`, where no assumptions on the structure of the
+    operators are done.
+
+    The Hamiltonian can be passed as :class:`.SparsePauliOp`, in which case we split the Hamiltonian
+    into commuting terms :math:`\{H_k\}_k`. Note, that this may not be optimal and if the
+    minimal set of commuting terms is known it can be passed as sequence into this function.
+
+    Examples:
+
+        A single operator will be split into commuting terms automatically:
+
+        .. plot::
+            :include-source:
+
+            from qiskit.quantum_info import SparsePauliOp
+            from qiskit.circuit.library import hamiltonian_variational_ansatz
+
+            # this Hamiltonian will be split into the two terms [ZZI, IZZ] and [IXI]
+            hamiltonian = SparsePauliOp(["ZZI", "IZZ", "IXI"])
+            ansatz = hamiltonian_variational_ansatz(hamiltonian, reps=2)
+            ansatz.draw("mpl")
+
+        Alternatively, we can directly provide the terms:
+
+        .. plot::
+            :include-source:
+
+            from qiskit.quantum_info import SparsePauliOp
+            from qiskit.circuit.library import hamiltonian_variational_ansatz
+
+            zz = SparsePauliOp(["ZZI", "IZZ"])
+            x = SparsePauliOp(["IXI"])
+            ansatz = hamiltonian_variational_ansatz([zz, x], reps=2)
+            ansatz.draw("mpl")
+
+
+    Args:
+        hamiltonian: The Hamiltonian to evolve. If given as single operator, it will be split into
+            commuting terms. If a sequence of :class:`.SparsePauliOp`, then it is assumed that
+            each element consists of commuting terms, but the elements do not commute among each
+            other.
+        reps: The number of times to repeat the evolved operators.
+        insert_barriers: Whether to insert barriers in between each evolution.
+        name: The name of the circuit.
+        parameter_prefix: Set the names of the circuit parameters. If a string, the same prefix
+            will be used for each parameters. Can also be a list to specify a prefix per
+            operator.
+
+    References:
+
+        [1] D. Wecker et al. Progress towards practical quantum variational algorithms (2015)
+            `Phys Rev A 92, 042303 <https://journals.aps.org/pra/abstract/10.1103/PhysRevA.92.042303>`__
+        [2] R. Wiersema et al. Exploring entanglement and optimization within the Hamiltonian
+            Variational Ansatz (2020) `arXiv:2008.02941 <https://arxiv.org/abs/2008.02941>`__
+
+    """
+    # If a single operator is given, check if it is a sum of operators (a SparsePauliOp),
+    # and split it into commuting terms. Otherwise treat it as single operator.
+    if isinstance(hamiltonian, SparsePauliOp):
+        hamiltonian = hamiltonian.group_commuting()
+
+    return evolved_operator_ansatz(
+        hamiltonian,
+        reps=reps,
+        evolution=None,
+        insert_barriers=insert_barriers,
+        name=name,
+        parameter_prefix=parameter_prefix,
+        flatten=True,
+    )
+
 
 class EvolvedOperatorAnsatz(NLocal):
     """The evolved operator ansatz."""
@@ -254,3 +501,15 @@ def _is_pauli_identity(operator):
     if isinstance(operator, Pauli):
         return not np.any(np.logical_or(operator.x, operator.z))
     return False
+
+
+def _remove_identities(operators, prefixes):
+    identity_ops = {index for index, op in enumerate(operators) if _is_pauli_identity(op)}
+
+    if len(identity_ops) == 0:
+        return operators, prefixes
+
+    cleaned_ops = [op for i, op in enumerate(operators) if i not in identity_ops]
+    cleaned_prefix = [prefix for i, prefix in enumerate(prefixes) if i not in identity_ops]
+
+    return cleaned_ops, cleaned_prefix

qiskit/circuit/library/n_local/excitation_preserving.py

@@ -13,14 +13,127 @@
 """The ExcitationPreserving 2-local circuit."""
 
 from __future__ import annotations
-from collections.abc import Callable
+from collections.abc import Callable, Iterable
 from numpy import pi
 
 from qiskit.circuit import QuantumCircuit, Parameter
 from qiskit.circuit.library.standard_gates import RZGate
+from qiskit.utils.deprecation import deprecate_func
+from .n_local import n_local, BlockEntanglement
 from .two_local import TwoLocal
 
 
+def excitation_preserving(
+    num_qubits: int,
+    mode: str = "iswap",
+    entanglement: (
+        BlockEntanglement
+        | Iterable[BlockEntanglement]
+        | Callable[[int], BlockEntanglement | Iterable[BlockEntanglement]]
+    ) = "full",
+    reps: int = 3,
+    skip_unentangled_qubits: bool = False,
+    skip_final_rotation_layer: bool = False,
+    parameter_prefix: str = "θ",
+    insert_barriers: bool = False,
+    name: str = "ExcitationPreserving",
+):
+    r"""The heuristic excitation-preserving wave function ansatz.
+
+    The ``excitation_preserving`` circuit preserves the ratio of :math:`|00\rangle`,
+    :math:`|01\rangle + |10\rangle` and :math:`|11\rangle` states. To this end, this circuit
+    uses two-qubit interactions of the form
+
+    .. math::
+
+        \newcommand{\rotationangle}{\theta/2}
+
+        \begin{pmatrix}
+        1 & 0 & 0 & 0 \\
+        0 & \cos\left(\rotationangle\right) & -i\sin\left(\rotationangle\right) & 0 \\
+        0 & -i\sin\left(\rotationangle\right) & \cos\left(\rotationangle\right) & 0 \\
+        0 & 0 & 0 & e^{-i\phi}
+        \end{pmatrix}
+
+    for the mode ``"fsim"`` or with :math:`e^{-i\phi} = 1` for the mode ``"iswap"``.
+
+    Note that other wave functions, such as UCC-ansatzes, are also excitation preserving.
+    However these can become complex quickly, while this heuristically motivated circuit follows
+    a simpler pattern.
+
+    This trial wave function consists of layers of :math:`Z` rotations with 2-qubit entanglements.
+    The entangling is creating using :math:`XX+YY` rotations and optionally a controlled-phase
+    gate for the mode ``"fsim"``.
+
+    Examples:
+
+        With linear entanglement, this circuit is given by:
+
+        .. plot::
+            :include-source:
+            :context:
+
+            from qiskit.circuit.library import excitation_preserving
+
+            ansatz = excitation_preserving(3, reps=1, insert_barriers=True, entanglement="linear")
+            ansatz.draw("mpl")
+
+        The entanglement structure can be explicitly specified with the ``entanglement`` 
+        argument. The ``"fsim"`` mode includes an additional parameterized :class:`.CPhaseGate`
+        in each block:
+
+        .. plot::
+            :include-source:
+            :context:
+
+            ansatz = excitation_preserving(3, reps=1, mode="fsim", entanglement=[[0, 2]])
+            ansatz.draw("mpl")
+
+    Args:
+        num_qubits: The number of qubits.
+        mode: Choose the entangler mode, can be `"iswap"` or `"fsim"`.
+        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:
+        An excitation-preserving circuit.
+    """
+    supported_modes = ["iswap", "fsim"]
+    if mode not in supported_modes:
+        raise ValueError(f"Unsupported mode {mode}, choose one of {supported_modes}")
+
+    theta = Parameter("θ")
+    swap = QuantumCircuit(2, name="Interaction")
+    swap.rxx(theta, 0, 1)
+    swap.ryy(theta, 0, 1)
+    if mode == "fsim":
+        phi = Parameter("φ")
+        swap.cp(phi, 0, 1)
+
+    return n_local(
+        num_qubits,
+        ["rz"],
+        [swap.to_gate()],
+        entanglement,
+        reps,
+        insert_barriers,
+        parameter_prefix,
+        True,
+        skip_final_rotation_layer,
+        skip_unentangled_qubits,
+        name,
+    )
+
+
 class ExcitationPreserving(TwoLocal):
     r"""The heuristic excitation-preserving wave function ansatz.
 
@@ -57,7 +170,7 @@ class ExcitationPreserving(TwoLocal):
     Examples:
 
         >>> ansatz = ExcitationPreserving(3, reps=1, insert_barriers=True, entanglement='linear')
-        >>> print(ansatz)  # show the circuit
+        >>> print(ansatz.decompose())  # show the circuit
              ┌──────────┐ ░ ┌────────────┐┌────────────┐                             ░ ┌──────────┐
         q_0: ┤ RZ(θ[0]) ├─░─┤0           ├┤0           ├─────────────────────────────░─┤ RZ(θ[5]) ├
              ├──────────┤ ░ │  RXX(θ[3]) ││  RYY(θ[3]) │┌────────────┐┌────────────┐ ░ ├──────────┤
@@ -66,10 +179,10 @@ class ExcitationPreserving(TwoLocal):
         q_2: ┤ RZ(θ[2]) ├─░─────────────────────────────┤1           ├┤1           ├─░─┤ RZ(θ[7]) ├
              └──────────┘ ░                             └────────────┘└────────────┘ ░ └──────────┘
 
-        >>> ansatz = ExcitationPreserving(2, reps=1)
+        >>> ansatz = ExcitationPreserving(2, reps=1, flatten=True)
         >>> qc = QuantumCircuit(2)  # create a circuit and append the RY variational form
         >>> qc.cry(0.2, 0, 1)  # do some previous operation
-        >>> qc.compose(ansatz, inplace=True)  # add the swaprz
+        >>> qc.compose(ansatz, inplace=True)  # add the excitation-preserving
         >>> qc.draw()
                         ┌──────────┐┌────────────┐┌────────────┐┌──────────┐
         q_0: ─────■─────┤ RZ(θ[0]) ├┤0           ├┤0           ├┤ RZ(θ[3]) ├
@@ -78,8 +191,8 @@ class ExcitationPreserving(TwoLocal):
              └─────────┘└──────────┘└────────────┘└────────────┘└──────────┘
 
         >>> ansatz = ExcitationPreserving(3, reps=1, mode='fsim', entanglement=[[0,2]],
-        ... insert_barriers=True)
-        >>> print(ansatz)
+        ... insert_barriers=True, flatten=True)
+        >>> print(ansatz.decompose())
              ┌──────────┐ ░ ┌────────────┐┌────────────┐        ░ ┌──────────┐
         q_0: ┤ RZ(θ[0]) ├─░─┤0           ├┤0           ├─■──────░─┤ RZ(θ[5]) ├
              ├──────────┤ ░ │            ││            │ │      ░ ├──────────┤
@@ -87,8 +200,19 @@ class ExcitationPreserving(TwoLocal):
              ├──────────┤ ░ │            ││            │ │θ[4]  ░ ├──────────┤
         q_2: ┤ RZ(θ[2]) ├─░─┤1           ├┤1           ├─■──────░─┤ RZ(θ[7]) ├
              └──────────┘ ░ └────────────┘└────────────┘        ░ └──────────┘
+
+    .. seealso::
+
+        The :func:`.excitation_preserving` function constructs a functionally equivalent circuit, 
+        but faster.
+
     """
 
+    @deprecate_func(
+        since="1.3",
+        additional_msg="Use the function qiskit.circuit.library.excitation_preserving instead.",
+        pending=True,
+    )
     def __init__(
         self,
         num_qubits: int | None = None,