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

qiskit/circuit/library/n_local/n_local.py

@@ -17,21 +17,28 @@ from __future__ import annotations
 import collections
 import itertools
 import typing
-from collections.abc import Callable, Mapping, Sequence
+from collections.abc import Callable, Mapping, Sequence, Iterable
 
 import numpy
-from qiskit.circuit.quantumcircuit import QuantumCircuit
+from qiskit.circuit.gate import Gate
+from qiskit.circuit.quantumcircuit import QuantumCircuit, ParameterValueType
+from qiskit.circuit.parametervector import ParameterVector, ParameterVectorElement
 from qiskit.circuit.quantumregister import QuantumRegister
 from qiskit.circuit import (
     Instruction,
     Parameter,
-    ParameterVector,
     ParameterExpression,
     CircuitInstruction,
 )
 from qiskit.exceptions import QiskitError
 from qiskit.circuit.library.standard_gates import get_standard_gate_name_mapping
-from qiskit._accelerate.circuit_library import get_entangler_map as fast_entangler_map
+from qiskit.utils.deprecation import deprecate_func
+
+from qiskit._accelerate.circuit_library import (
+    Block,
+    py_n_local,
+    get_entangler_map as fast_entangler_map,
+)
 
 from ..blueprintcircuit import BlueprintCircuit
 
@@ -39,6 +46,219 @@ from ..blueprintcircuit import BlueprintCircuit
 if typing.TYPE_CHECKING:
     import qiskit  # pylint: disable=cyclic-import
 
+# entanglement for an individual block, e.g. if the block is CXGate() and we have
+# 3 qubits, this could be [(0, 1), (1, 2), (2, 0)]
+BlockEntanglement = typing.Union[str, Iterable[Iterable[int]]]
+
+
+def n_local(
+    num_qubits: int,
+    rotation_blocks: str | Gate | Iterable[str | Gate],
+    entanglement_blocks: str | Gate | Iterable[str | Gate],
+    entanglement: (
+        BlockEntanglement
+        | Iterable[BlockEntanglement]
+        | Callable[[int], BlockEntanglement | Iterable[BlockEntanglement]]
+    ) = "full",
+    reps: int = 3,
+    insert_barriers: bool = False,
+    parameter_prefix: str = "θ",
+    overwrite_block_parameters: bool = True,
+    skip_final_rotation_layer: bool = False,
+    skip_unentangled_qubits: bool = False,
+    name: str | None = "nlocal",
+) -> QuantumCircuit:
+    r"""Construct an n-local variational circuit.
+
+    The structure of the n-local circuit are alternating rotation and entanglement layers.
+    In both layers, parameterized circuit-blocks act on the circuit in a defined way.
+    In the rotation layer, the blocks are applied stacked on top of each other, while in the
+    entanglement layer according to the ``entanglement`` strategy.
+    The circuit blocks can have arbitrary sizes (smaller equal to the number of qubits in the
+    circuit). Each layer is repeated ``reps`` times, and by default a final rotation layer is
+    appended.
+
+    For instance, a rotation block on 2 qubits and an entanglement block on 4 qubits using
+    ``"linear"`` entanglement yields the following circuit.
+
+    .. parsed-literal::
+
+        ┌──────┐ ░ ┌──────┐                      ░ ┌──────┐
+        ┤0     ├─░─┤0     ├──────────────── ... ─░─┤0     ├
+        │  Rot │ ░ │      │┌──────┐              ░ │  Rot │
+        ┤1     ├─░─┤1     ├┤0     ├──────── ... ─░─┤1     ├
+        ├──────┤ ░ │  Ent ││      │┌──────┐      ░ ├──────┤
+        ┤0     ├─░─┤2     ├┤1     ├┤0     ├ ... ─░─┤0     ├
+        │  Rot │ ░ │      ││  Ent ││      │      ░ │  Rot │
+        ┤1     ├─░─┤3     ├┤2     ├┤1     ├ ... ─░─┤1     ├
+        ├──────┤ ░ └──────┘│      ││  Ent │      ░ ├──────┤
+        ┤0     ├─░─────────┤3     ├┤2     ├ ... ─░─┤0     ├
+        │  Rot │ ░         └──────┘│      │      ░ │  Rot │
+        ┤1     ├─░─────────────────┤3     ├ ... ─░─┤1     ├
+        └──────┘ ░                 └──────┘      ░ └──────┘
+
+        |                                 |
+        +---------------------------------+
+               repeated reps times
+
+    Entanglement:
+
+        The entanglement describes the connections of the gates in the entanglement layer.
+        For a two-qubit gate for example, the entanglement contains pairs of qubits on which the
+        gate should acts, e.g. ``[[ctrl0, target0], [ctrl1, target1], ...]``.
+        A set of default entanglement strategies is provided and can be selected by name:
+
+        * ``"full"`` entanglement is each qubit is entangled with all the others.
+        * ``"linear"`` entanglement is qubit :math:`i` entangled with qubit :math:`i + 1`,
+          for all :math:`i \in \{0, 1, ... , n - 2\}`, where :math:`n` is the total number of qubits.
+        * ``"reverse_linear"`` entanglement is qubit :math:`i` entangled with qubit :math:`i + 1`,
+          for all :math:`i \in \{n-2, n-3, ... , 1, 0\}`, where :math:`n` is the total number of qubits.
+          Note that if ``entanglement_blocks=="cx"`` then this option provides the same unitary as
+          ``"full"`` with fewer entangling gates.
+        * ``"pairwise"`` entanglement is one layer where qubit :math:`i` is entangled with qubit
+          :math:`i + 1`, for all even values of :math:`i`, and then a second layer where qubit :math:`i`
+          is entangled with qubit :math:`i + 1`, for all odd values of :math:`i`.
+        * ``"circular"`` entanglement is linear entanglement but with an additional entanglement of the
+          first and last qubit before the linear part.
+        * ``"sca"`` (shifted-circular-alternating) entanglement is a generalized and modified version
+          of the proposed circuit 14 in `Sim et al. <https://arxiv.org/abs/1905.10876>`__.
+          It consists of circular entanglement where the "long" entanglement connecting the first with
+          the last qubit is shifted by one each block.  Furthermore the role of control and target
+          qubits are swapped every block (therefore alternating).
+
+        If an entanglement layer contains multiple blocks, then the entanglement should be
+        given as list of entanglements for each block. For example::
+
+            entanglement_blocks = ["rxx", "ryy"]
+            entanglement = ["full", "linear"]  # full for rxx and linear for ryy
+
+        or::
+
+            structure_rxx = [[0, 1], [2, 3]]
+            structure_ryy = [[0, 2]]
+            entanglement = [structure_rxx, structure_ryy]
+
+        Finally, the entanglement can vary in each repetition of the circuit. For this, we
+        support passing a callable that takes as input the layer index and returns the entanglement
+        for the layer in the above format. See the examples below for a concrete example.
+
+    Examples:
+
+        The rotation and entanglement gates can be specified via single strings, if they
+        are made up of a single block per layer:
+
+        .. plot::
+            :include-source:
+            :context:
+
+            from qiskit.circuit.library import n_local
+
+            circuit = n_local(3, "ry", "cx", "linear", reps=2, insert_barriers=True)
+            circuit.draw("mpl")
+
+        Multiple gates per layer can be set by passing a list. Here, for example, we use
+        Pauli-Y and Pauli-Z rotations in the rotation layer:
+
+        .. plot::
+            :include-source:
+            :context:
+
+            circuit = n_local(3, ["ry", "rz"], "cz", "full", reps=1, insert_barriers=True)
+            circuit.draw("mpl")
+
+        To omit rotation or entanglement layers, the block can be set to an empty list:
+
+        .. plot::
+            :include-source:
+            :context:
+
+            circuit = n_local(4, [], "cry", reps=2)
+            circuit.draw("mpl")
+
+        The entanglement can be set explicitly via the ``entanglement`` argument:
+
+        .. plot::
+            :include-source:
+            :context:
+
+            entangler_map = [[0, 1], [2, 0]]
+            circuit = n_local(3, "x", "crx", entangler_map, reps=2)
+            circuit.draw("mpl")
+
+        We can set different entanglements per layer, by specifing a callable that takes
+        as input the current layer index, and returns the entanglement structure. For example,
+        the following uses different entanglements for odd and even layers:
+
+        .. plot:
+            :include-source:
+            :context:
+
+            def entanglement(layer_index):
+                if layer_index % 2 == 0:
+                    return [[0, 1], [0, 2]]
+                return [[1, 2]]
+
+            circuit = n_local(3, "x", "cx", entanglement, reps=3, insert_barriers=True)
+            circuit.draw("mpl")
+
+
+    Args:
+        num_qubits: The number of qubits of the circuit.
+        rotation_blocks: The blocks used in the rotation layers. If multiple are passed,
+            these will be applied one after another (like new sub-layers).
+        entanglement_blocks: The blocks used in the entanglement layers. If multiple are passed,
+            these will be applied one after another.
+        entanglement: The indices specifying on which qubits the input blocks act. This is
+            specified by string describing an entanglement strategy (see the additional info)
+            or a list of qubit connections.
+            If a list of entanglement blocks is passed, different entanglement for each block can
+            be specified by passing a list of entanglements. To specify varying entanglement for
+            each repetition, pass a callable that takes as input the layer and returns the
+            entanglement for that layer.
+            Defaults to ``"full"``, meaning an all-to-all entanglement structure.
+        reps: Specifies how often the rotation blocks and entanglement blocks are repeated.
+        insert_barriers: If ``True``, barriers are inserted in between each layer. If ``False``,
+            no barriers are inserted.
+        parameter_prefix: The prefix used if default parameters are generated.
+        overwrite_block_parameters: If the parameters in the added blocks should be overwritten.
+            If ``False``, the parameters in the blocks are not changed.
+        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.
+        name: The name of the circuit.
+
+    Returns:
+        An n-local circuit.
+    """
+    if reps < 0:
+        # this is an important check, since we cast this to an unsigned integer Rust-side
+        raise ValueError(f"reps must be non-negative, but is {reps}")
+
+    supported_gates = get_standard_gate_name_mapping()
+    rotation_blocks = _normalize_blocks(
+        rotation_blocks, supported_gates, overwrite_block_parameters
+    )
+    entanglement_blocks = _normalize_blocks(
+        entanglement_blocks, supported_gates, overwrite_block_parameters
+    )
+
+    entanglement = _normalize_entanglement(entanglement, len(entanglement_blocks))
+
+    data = py_n_local(
+        num_qubits=num_qubits,
+        rotation_blocks=rotation_blocks,
+        entanglement_blocks=entanglement_blocks,
+        entanglement=entanglement,
+        reps=reps,
+        insert_barriers=insert_barriers,
+        parameter_prefix=parameter_prefix,
+        skip_final_rotation_layer=skip_final_rotation_layer,
+        skip_unentangled_qubits=skip_unentangled_qubits,
+    )
+    circuit = QuantumCircuit._from_circuit_data(data, add_regs=True, name=name)
+
+    return circuit
+
 
 class NLocal(BlueprintCircuit):
     """The n-local circuit class.
@@ -54,7 +274,7 @@ class NLocal(BlueprintCircuit):
     For instance, a rotation block on 2 qubits and an entanglement block on 4 qubits using
     ``'linear'`` entanglement yields the following circuit.
 
-    .. parsed-literal::
+    .. code-block:: text
 
         ┌──────┐ ░ ┌──────┐                      ░ ┌──────┐
         ┤0     ├─░─┤0     ├──────────────── ... ─░─┤0     ├
@@ -76,8 +296,18 @@ class NLocal(BlueprintCircuit):
 
     If specified, barriers can be inserted in between every block.
     If an initial state object is provided, it is added in front of the NLocal.
+
+    .. seealso::
+
+        The :func:`.n_local` function constructs a functionally equivalent circuit, but faster.
+
     """
 
+    @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,
@@ -1069,3 +1299,174 @@ def _stdlib_gate_from_simple_block(block: QuantumCircuit) -> _StdlibGateResult |
     ):
         return None
     return _StdlibGateResult(instruction.operation.base_class, len(instruction.operation.params))
+
+
+def _normalize_entanglement(
+    entanglement: (
+        BlockEntanglement
+        | Iterable[BlockEntanglement]
+        | Callable[[int], BlockEntanglement | Iterable[BlockEntanglement]]
+    ),
+    num_entanglement_blocks: int,
+) -> list[str | list[tuple[int]]] | Callable[[int], list[str | list[tuple[int]]]]:
+    """If the entanglement is Iterable[Iterable], normalize to list[tuple]."""
+    if isinstance(entanglement, str):
+        return [entanglement] * num_entanglement_blocks
+
+    if callable(entanglement):
+        return lambda offset: _normalize_entanglement(entanglement(offset), num_entanglement_blocks)
+
+    # here, entanglement is an Iterable
+    if len(entanglement) == 0:
+        # handle edge cases when entanglement is set to an empty list
+        return [[]]
+
+    # if the entanglement is Iterable[Iterable[int]], normalize to Iterable[Iterable[Iterable[int]]]
+    try:
+        # if users e.g. gave Iterable[int] this in invalid and will raise a TypeError
+        if isinstance(entanglement[0][0], (int, numpy.integer)):
+            entanglement = [entanglement]
+    except TypeError as exc:
+        raise TypeError(f"Invalid entanglement type: {entanglement}.") from exc
+
+    # ensure the number of block entanglements matches the number of blocks
+    if len(entanglement) != num_entanglement_blocks:
+        raise QiskitError(
+            f"Number of block-entanglements ({len(entanglement)}) must match number of "
+            f"entanglement blocks ({num_entanglement_blocks})!"
+        )
+
+    # normalize the data: str remains, and Iterable[Iterable[int]] becomes list[tuple[int]]
+    normalized = []
+    for block in entanglement:
+        if isinstance(block, str):
+            normalized.append(block)
+        else:
+            normalized.append([tuple(connections) for connections in block])
+
+    return normalized
+
+
+def _normalize_blocks(
+    blocks: str | Gate | Iterable[str | Gate],
+    supported_gates: dict[str, Gate],
+    overwrite_block_parameters: bool,
+) -> list[Block]:
+    # normalize the input into an iterable -- we add an extra check for a circuit as
+    # courtesy to the users, since the NLocal class used to accept circuits
+    if isinstance(blocks, (str, Gate, QuantumCircuit)):
+        blocks = [blocks]
+
+    normalized = []
+    for block in blocks:
+        # since the NLocal circuit accepted circuits as inputs, we raise a warning here
+        # to simplify the transition (even though, strictly speaking, quantum circuits are
+        # not a supported input type)
+        if isinstance(block, QuantumCircuit):
+            raise ValueError(
+                "The blocks should be of type Gate or str, but you passed a QuantumCircuit. "
+                "You can call .to_gate() on the circuit to turn it into a Gate object."
+            )
+
+        is_standard = False
+        if isinstance(block, str):
+            if block not in supported_gates:
+                raise ValueError(f"Unsupported gate: {block}")
+            block = supported_gates[block]
+            is_standard = True
+        elif isinstance(block, Gate) and getattr(block, "_standard_gate", None) is not None:
+            if len(block.params) == 0:
+                is_standard = True
+            # the fast path will always overwrite block parameters
+            elif overwrite_block_parameters:
+                # if all parameters are plain Parameter objects, this is a plain
+                # standard gate we do not need to propagate parameterizations for
+                is_standard = all(isinstance(p, Parameter) for p in block.params)
+
+        if is_standard:
+            block = Block.from_standard_gate(block._standard_gate)
+        else:
+            if overwrite_block_parameters:
+                num_parameters, builder = _get_gate_builder(block)
+            else:
+                num_parameters, builder = _trivial_builder(block)
+
+            block = Block.from_callable(block.num_qubits, num_parameters, builder)
+
+        normalized.append(block)
+
+    return normalized
+
+
+def _trivial_builder(
+    gate: Gate,
+) -> tuple[int, Callable[list[Parameter], tuple[Gate, list[ParameterValueType]]]]:
+
+    def builder(_):
+        copied = gate.copy()
+        return copied, copied.params
+
+    return 0, builder
+
+
+def _get_gate_builder(
+    gate: Gate,
+) -> tuple[int, Callable[list[Parameter], tuple[Gate, list[ParameterValueType]]]]:
+    """Construct a callable that handles parameter-rebinding.
+
+    For a given gate, this return the number of free parameters and a callable that can be
+    used to obtain a re-parameterized version of the gate. For example::
+
+        x, y = Parameter("x"), Parameter("y")
+        gate = CUGate(x, 2 * y, 0.5, 0.)
+
+        num_parameters, builder = _build_gate(gate)
+        print(num_parameters)  # prints 2
+
+        a, b = Parameter("a"), Parameter("b")
+        new_gate, new_params = builder([a, b])
+        print(new_gate)  # CUGate(a, 2 * b, 0.5, 0)
+        print(new_params)  # [a, 2 * b, 0.5, 0]
+
+    """
+    free_parameters = set()
+    for p in gate.params:
+        if isinstance(p, ParameterExpression):
+            free_parameters |= set(p.parameters)
+
+    num_parameters = len(free_parameters)
+
+    sorted_parameters = _sort_parameters(free_parameters)
+
+    def builder(new_parameters):
+        out = gate.copy()
+
+        # re-bind the ``Gate.params`` attribute
+        param_dict = dict(zip(sorted_parameters, new_parameters))
+        bound_params = gate.params.copy()
+        for i, expr in enumerate(gate.params):
+            if isinstance(expr, ParameterExpression):
+                for parameter in expr.parameters:
+                    expr = expr.assign(parameter, param_dict[parameter])
+                bound_params[i] = expr
+
+        out.params = bound_params
+
+        # if the definition exists, rebind it
+        if out._definition is not None:
+            out._definition.assign_parameters(param_dict, inplace=True)
+
+        return out, bound_params
+
+    return num_parameters, builder
+
+
+def _sort_parameters(parameters):
+    """Sort a list of Parameter objects."""
+
+    def key(parameter):
+        if isinstance(parameter, ParameterVectorElement):
+            return (parameter.vector.name, parameter.index)
+        return (parameter.name,)
+
+    return sorted(parameters, key=key)

qiskit/circuit/library/n_local/pauli_two_design.py

@@ -16,9 +16,104 @@ from __future__ import annotations
 import numpy as np
 
 from qiskit.circuit import QuantumCircuit
+from qiskit.circuit.library.standard_gates import RXGate, RYGate, RZGate, CZGate
+from qiskit.utils.deprecation import deprecate_func
+from qiskit._accelerate.circuit_library import Block, py_n_local
+from .two_local import TwoLocal
 
 
-from .two_local import TwoLocal
+def pauli_two_design(
+    num_qubits: int,
+    reps: int = 3,
+    seed: int | None = None,
+    insert_barriers: bool = False,
+    parameter_prefix: str = "θ",
+    name: str = "PauliTwoDesign",
+) -> QuantumCircuit:
+    r"""Construct a Pauli 2-design ansatz.
+
+    This class implements a particular form of a 2-design circuit [1], which is frequently studied
+    in quantum machine learning literature, such as, e.g., the investigation of Barren plateaus in
+    variational algorithms [2].
+
+    The circuit consists of alternating rotation and entanglement layers with
+    an initial layer of :math:`\sqrt{H} = RY(\pi/4)` gates.
+    The rotation layers contain single qubit Pauli rotations, where the axis is chosen uniformly
+    at random to be X, Y or Z. The entanglement layers is compromised of pairwise CZ gates
+    with a total depth of 2.
+
+    For instance, the circuit could look like this:
+
+    .. parsed-literal::
+
+             ┌─────────┐┌──────────┐       ░ ┌──────────┐       ░  ┌──────────┐
+        q_0: ┤ RY(π/4) ├┤ RZ(θ[0]) ├─■─────░─┤ RY(θ[4]) ├─■─────░──┤ RZ(θ[8]) ├
+             ├─────────┤├──────────┤ │     ░ ├──────────┤ │     ░  ├──────────┤
+        q_1: ┤ RY(π/4) ├┤ RZ(θ[1]) ├─■──■──░─┤ RY(θ[5]) ├─■──■──░──┤ RX(θ[9]) ├
+             ├─────────┤├──────────┤    │  ░ ├──────────┤    │  ░ ┌┴──────────┤
+        q_2: ┤ RY(π/4) ├┤ RX(θ[2]) ├─■──■──░─┤ RY(θ[6]) ├─■──■──░─┤ RX(θ[10]) ├
+             ├─────────┤├──────────┤ │     ░ ├──────────┤ │     ░ ├───────────┤
+        q_3: ┤ RY(π/4) ├┤ RZ(θ[3]) ├─■─────░─┤ RX(θ[7]) ├─■─────░─┤ RY(θ[11]) ├
+             └─────────┘└──────────┘       ░ └──────────┘       ░ └───────────┘
+
+    Examples:
+
+        .. plot::
+            :include-source:
+
+            from qiskit.circuit.library import pauli_two_design
+            circuit = pauli_two_design(4, reps=2, seed=5, insert_barriers=True)
+            circuit.draw("mpl")
+
+    Args:
+        num_qubits: The number of qubits of the Pauli Two-Design circuit.
+        reps: Specifies how often a block consisting of a rotation layer and entanglement
+            layer is repeated.
+        seed: The seed for randomly choosing the axes of the Pauli rotations.
+        parameter_prefix: The prefix used for the rotation parameters.
+        insert_barriers: If ``True``, barriers are inserted in between each layer. If ``False``,
+            no barriers are inserted. Defaults to ``False``.
+        name: The circuit name.
+
+    Returns:
+        A Pauli 2-design circuit.
+
+    References:
+
+        [1]: Nakata et al., Unitary 2-designs from random X- and Z-diagonal unitaries.
+            `arXiv:1502.07514 <https://arxiv.org/pdf/1502.07514.pdf>`_
+
+        [2]: McClean et al., Barren plateaus in quantum neural network training landscapes.
+             `arXiv:1803.11173 <https://arxiv.org/pdf/1803.11173.pdf>`_
+    """
+    rng = np.random.default_rng(seed)
+    random_block = Block.from_callable(1, 1, lambda params: _random_pauli_builder(params, rng))
+    cz_block = Block.from_standard_gate(CZGate._standard_gate)
+
+    data = py_n_local(
+        num_qubits=num_qubits,
+        reps=reps,
+        rotation_blocks=[random_block],
+        entanglement_blocks=[cz_block],
+        entanglement=["pairwise"],
+        insert_barriers=insert_barriers,
+        skip_final_rotation_layer=False,
+        skip_unentangled_qubits=False,
+        parameter_prefix=parameter_prefix,
+    )
+    two_design = QuantumCircuit._from_circuit_data(data)
+
+    circuit = QuantumCircuit(num_qubits, name=name)
+    circuit.ry(np.pi / 4, circuit.qubits)
+    circuit.compose(two_design, inplace=True, copy=False)
+
+    return circuit
+
+
+def _random_pauli_builder(params, rng):
+    gate_cls = rng.choice([RXGate, RYGate, RZGate])
+    gate = gate_cls(params[0])
+    return gate, gate.params
 
 
 class PauliTwoDesign(TwoLocal):
@@ -37,7 +132,7 @@ class PauliTwoDesign(TwoLocal):
     For instance, the circuit could look like this (but note that choosing a different seed
     yields different Pauli rotations).
 
-    .. parsed-literal::
+    .. code-block:: text
 
              ┌─────────┐┌──────────┐       ░ ┌──────────┐       ░  ┌──────────┐
         q_0: ┤ RY(π/4) ├┤ RZ(θ[0]) ├─■─────░─┤ RY(θ[4]) ├─■─────░──┤ RZ(θ[8]) ├
@@ -58,6 +153,10 @@ class PauliTwoDesign(TwoLocal):
            circuit = PauliTwoDesign(4, reps=2, seed=5, insert_barriers=True)
            circuit.draw('mpl')
 
+    .. seealso::
+
+        The :func:`.pauli_two_design` function constructs the functionally same circuit, but faster.
+
     References:
 
         [1]: Nakata et al., Unitary 2-designs from random X- and Z-diagonal unitaries.
@@ -67,6 +166,11 @@ class PauliTwoDesign(TwoLocal):
              `arXiv:1803.11173 <https://arxiv.org/pdf/1803.11173.pdf>`_
     """
 
+    @deprecate_func(
+        since="1.3",
+        additional_msg="Use the function qiskit.circuit.library.pauli_two_design instead.",
+        pending=True,
+    )
     def __init__(
         self,
         num_qubits: int | None = None,
@@ -85,8 +189,6 @@ class PauliTwoDesign(TwoLocal):
                 no barriers are inserted. Defaults to ``False``.
 
         """
-        from qiskit.circuit.library import RYGate  # pylint: disable=cyclic-import
-
         # store a random number generator
         self._seed = seed
         self._rng = np.random.default_rng(seed)

qiskit/circuit/library/n_local/qaoa_ansatz.py

@@ -21,8 +21,87 @@ from qiskit.circuit.parametervector import ParameterVector
 from qiskit.circuit.quantumcircuit import QuantumCircuit
 from qiskit.circuit.quantumregister import QuantumRegister
 from qiskit.quantum_info import SparsePauliOp
+from qiskit.quantum_info.operators.base_operator import BaseOperator
+
+from .evolved_operator_ansatz import (
+    EvolvedOperatorAnsatz,
+    _is_pauli_identity,
+    evolved_operator_ansatz,
+)
+
+
+def qaoa_ansatz(
+    cost_operator: BaseOperator,
+    reps: int = 1,
+    initial_state: QuantumCircuit | None = None,
+    mixer_operator: BaseOperator | None = None,
+    insert_barriers: bool = False,
+    name: str = "QAOA",
+    flatten: bool = True,
+) -> QuantumCircuit:
+    r"""A generalized QAOA quantum circuit with a support of custom initial states and mixers.
+
+    Examples:
+
+        To define the QAOA ansatz we require a cost Hamiltonian, encoding the classical
+        optimization problem:
+
+        .. plot::
+            :include-source:
+
+            from qiskit.quantum_info import SparsePauliOp
+            from qiskit.circuit.library import qaoa_ansatz
+
+            cost_operator = SparsePauliOp(["ZZII", "IIZZ", "ZIIZ"])
+            ansatz = qaoa_ansatz(cost_operator, reps=3, insert_barriers=True)
+            ansatz.draw("mpl")
+
+    Args:
+        cost_operator: The operator representing the cost of the optimization problem, denoted as
+            :math:`U(C, \gamma)` in [1].
+        reps: The integer determining the depth of the circuit, called :math:`p` in [1].
+        initial_state: An optional initial state to use, which defaults to a layer of
+            Hadamard gates preparing the :math:`|+\rangle^{\otimes n}` state.
+            If a custom mixer is chosen, this circuit should be set to prepare its ground state,
+            to appropriately fulfill the annealing conditions.
+        mixer_operator: An optional custom mixer, which defaults to global Pauli-:math:`X`
+            rotations. This is denoted as :math:`U(B, \beta)` in [1]. If this is set,
+            the ``initial_state`` might also require modification.
+        insert_barriers: Whether to insert barriers in-between the cost and mixer operators.
+        name: The name of the circuit.
+        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.
 
-from .evolved_operator_ansatz import EvolvedOperatorAnsatz, _is_pauli_identity
+    References:
+
+        [1]: Farhi et al., A Quantum Approximate Optimization Algorithm.
+            `arXiv:1411.4028 <https://arxiv.org/pdf/1411.4028>`_
+    """
+    num_qubits = cost_operator.num_qubits
+
+    if initial_state is None:
+        initial_state = QuantumCircuit(num_qubits)
+        initial_state.h(range(num_qubits))
+
+    if mixer_operator is None:
+        mixer_operator = SparsePauliOp.from_sparse_list(
+            [("X", [i], 1) for i in range(num_qubits)], num_qubits
+        )
+
+    parameter_prefix = ["γ", "β"]
+
+    return initial_state.compose(
+        evolved_operator_ansatz(
+            [cost_operator, mixer_operator],
+            reps=reps,
+            insert_barriers=insert_barriers,
+            parameter_prefix=parameter_prefix,
+            name=name,
+            flatten=flatten,
+        ),
+        copy=False,
+    )
 
 
 class QAOAAnsatz(EvolvedOperatorAnsatz):