References

class Ansaetze:
    def get_available(parameterized_only=False):
        # list of parameterized ansaetze
        ansaetze = [
            Ansaetze.Circuit_1,
            Ansaetze.Circuit_2,
            Ansaetze.Circuit_3,
            Ansaetze.Circuit_4,
            Ansaetze.Circuit_5,
            Ansaetze.Circuit_6,
            Ansaetze.Circuit_7,
            Ansaetze.Circuit_8,
            Ansaetze.Circuit_9,
            Ansaetze.Circuit_10,
            Ansaetze.Circuit_13,
            Ansaetze.Circuit_14,
            Ansaetze.Circuit_15,
            Ansaetze.Circuit_16,
            Ansaetze.Circuit_17,
            Ansaetze.Circuit_18,
            Ansaetze.Circuit_19,
            Ansaetze.Circuit_20,
            Ansaetze.No_Entangling,
            Ansaetze.Strongly_Entangling,
            Ansaetze.Hardware_Efficient,
        ]

        # extend by the non-parameterized ones
        if not parameterized_only:
            ansaetze += [
                Ansaetze.No_Ansatz,
                Ansaetze.GHZ,
            ]

        return ansaetze

    class No_Ansatz(DeclarativeCircuit):
        @classmethod
        def structure(cls):
            return ()

    class GHZ(DeclarativeCircuit):
        @classmethod
        def structure(cls):
            return (
                Block(gate=Gates.H),
                Block(gate=Gates.CX, topology=Topology.stairs, reverse=True),
            )

        @classmethod
        def build(cls, w: np.ndarray, n_qubits: int, **kwargs):
            Gates.H(wires=0, **kwargs)
            for q in range(n_qubits - 1):
                Gates.CX(wires=[q, q + 1], **kwargs)

        @classmethod
        def n_pulse_params_per_layer(cls, n_qubits: int) -> int:
            n_params = PulseInformation.num_params("H")  # only 1 H
            n_params += (n_qubits - 1) * PulseInformation.num_params(Gates.CX)
            return n_params

    class Circuit_1(DeclarativeCircuit):
        @classmethod
        def structure(cls):
            return (
                Block(gate=Gates.RX),
                Block(gate=Gates.RZ),
            )

    class Circuit_2(DeclarativeCircuit):
        @classmethod
        def structure(cls):
            return (
                Block(gate=Gates.RX),
                Block(gate=Gates.RZ),
                Block(
                    gate=Gates.CX,
                    topology=Topology.stairs,
                ),
            )

    class Circuit_3(DeclarativeCircuit):
        @classmethod
        def structure(cls):
            return (
                Block(gate=Gates.RX),
                Block(gate=Gates.RZ),
                Block(gate=Gates.CRZ, topology=Topology.stairs),
            )

    class Circuit_4(DeclarativeCircuit):
        @classmethod
        def structure(cls):
            return (
                Block(gate=Gates.RX),
                Block(gate=Gates.RZ),
                Block(gate=Gates.CRX, topology=Topology.stairs),
            )

    class Circuit_5(DeclarativeCircuit):
        @classmethod
        def structure(cls):
            return (
                Block(gate=Gates.RX),
                Block(gate=Gates.RZ),
                Block(gate=Gates.CRZ, topology=Topology.all_to_all),
                Block(gate=Gates.RX),
                Block(gate=Gates.RZ),
            )

    class Circuit_6(DeclarativeCircuit):
        @classmethod
        def structure(cls):
            return (
                Block(gate=Gates.RX),
                Block(gate=Gates.RZ),
                Block(gate=Gates.CRX, topology=Topology.all_to_all),
                Block(gate=Gates.RX),
                Block(gate=Gates.RZ),
            )

    class Circuit_7(DeclarativeCircuit):
        @classmethod
        def structure(cls):
            return (
                Block(gate=Gates.RX),
                Block(gate=Gates.RZ),
                Block(
                    gate=Gates.CRZ,
                    topology=Topology.bricks,
                ),
                Block(gate=Gates.RX),
                Block(gate=Gates.RZ),
                Block(
                    gate=Gates.CRZ,
                    topology=Topology.bricks,
                    offset=1,
                ),
            )

    class Circuit_8(DeclarativeCircuit):
        @classmethod
        def structure(cls):
            return (
                Block(gate=Gates.RX),
                Block(gate=Gates.RZ),
                Block(
                    gate=Gates.CRX,
                    topology=Topology.bricks,
                ),
                Block(gate=Gates.RX),
                Block(gate=Gates.RZ),
                Block(
                    gate=Gates.CRX,
                    topology=Topology.bricks,
                    offset=1,
                ),
            )

    class Circuit_9(DeclarativeCircuit):
        @classmethod
        def structure(cls):
            return (
                Block(gate=Gates.H),
                Block(gate="CZ", topology=Topology.stairs),
                Block(gate=Gates.RX),
            )

    class Circuit_10(DeclarativeCircuit):
        @classmethod
        def structure(cls):
            return (
                Block(gate=Gates.RY),
                Block(gate="CZ", topology=Topology.stairs, offset=-1, wrap=True),
                Block(gate=Gates.RY),
            )

    class Circuit_13(DeclarativeCircuit):
        @classmethod
        def structure(cls):
            return (
                Block(gate=Gates.RY),
                Block(
                    gate=Gates.CRZ,
                    topology=Topology.stairs,
                    wrap=True,
                    reverse=True,
                    mirror=False,
                ),
                Block(gate=Gates.RY),
                Block(
                    gate=Gates.CRZ,
                    topology=Topology.stairs,
                    reverse=False,
                    mirror=False,
                    offset=lambda n: n - 1,
                    span=3,
                    wrap=True,
                ),
            )

    class Circuit_14(DeclarativeCircuit):
        @classmethod
        def structure(cls):
            return (
                Block(gate=Gates.RY),
                Block(
                    gate=Gates.CRX,
                    topology=Topology.stairs,
                    wrap=True,
                    reverse=True,
                    mirror=False,
                ),
                Block(gate=Gates.RY),
                Block(
                    gate=Gates.CRX,
                    topology=Topology.stairs,
                    reverse=False,
                    mirror=False,
                    offset=lambda n: n - 1,
                    span=3,
                    wrap=True,
                ),
            )

    class Circuit_15(DeclarativeCircuit):
        @classmethod
        def structure(cls):
            return (
                Block(gate=Gates.RY),
                Block(
                    gate=Gates.CX,
                    topology=Topology.stairs,
                    wrap=True,
                    reverse=True,
                    mirror=False,
                ),
                Block(gate=Gates.RY),
                Block(
                    gate=Gates.CX,
                    topology=Topology.stairs,
                    reverse=False,
                    mirror=False,
                    offset=lambda n: n - 1,
                    span=3,
                    wrap=True,
                ),
            )

    class Circuit_16(DeclarativeCircuit):
        @classmethod
        def structure(cls):
            return (
                Block(gate=Gates.RX),
                Block(gate=Gates.RZ),
                Block(
                    gate=Gates.CRZ,
                    topology=Topology.bricks,
                ),
                Block(
                    gate=Gates.CRZ,
                    topology=Topology.bricks,
                    offset=1,
                ),
            )

    class Circuit_17(DeclarativeCircuit):
        @classmethod
        def structure(cls):
            return (
                Block(gate=Gates.RX),
                Block(gate=Gates.RZ),
                Block(
                    gate=Gates.CRX,
                    topology=Topology.bricks,
                ),
                Block(
                    gate=Gates.CRX,
                    topology=Topology.bricks,
                    offset=1,
                ),
            )

    class Circuit_18(DeclarativeCircuit):
        @classmethod
        def structure(cls):
            return (
                Block(gate=Gates.RX),
                Block(gate=Gates.RZ),
                Block(
                    gate=Gates.CRZ,
                    topology=Topology.stairs,
                    wrap=True,
                    mirror=False,
                ),
            )

    class Circuit_19(DeclarativeCircuit):
        @classmethod
        def structure(cls):
            return (
                Block(gate=Gates.RX),
                Block(gate=Gates.RZ),
                Block(
                    gate=Gates.CRX,
                    topology=Topology.stairs,
                    wrap=True,
                    mirror=False,
                ),
            )

    class Circuit_20(DeclarativeCircuit):
        @classmethod
        def structure(cls):
            return (
                Block(gate=Gates.RY),
                Block(
                    gate=Gates.CX,
                    topology=Topology.stairs,
                    wrap=True,
                    reverse=True,
                    mirror=False,
                ),
                Block(gate=Gates.RY),
                Block(
                    gate=Gates.CX,
                    topology=Topology.stairs,
                    reverse=False,
                    offset=lambda n: n - 2,
                    span=1,
                    wrap=True,
                ),
            )

    class No_Entangling(DeclarativeCircuit):
        @classmethod
        def structure(cls):
            return (Block(gate=Gates.Rot),)

    class Hardware_Efficient(DeclarativeCircuit):
        @classmethod
        def structure(cls):
            return (
                Block(gate=Gates.RY),
                Block(gate=Gates.RZ),
                Block(gate=Gates.RY),
                Block(
                    gate=Gates.CX,
                    topology=Topology.bricks,
                    mirror=False,
                ),
                Block(
                    gate=Gates.CX,
                    topology=Topology.bricks,
                    offset=-1,
                    modulo=True,
                    wrap=True,
                    mirror=False,
                ),
            )

    class Strongly_Entangling(DeclarativeCircuit):
        @classmethod
        def structure(cls):
            return (
                Block(gate=Gates.Rot),
                Block(
                    gate=Gates.CX,
                    topology=Topology.stairs,
                    wrap=True,
                    reverse=False,
                    mirror=False,
                ),
                Block(gate=Gates.Rot),
                Block(
                    gate=Gates.CX,
                    topology=Topology.stairs,
                    reverse=False,
                    span=lambda n: n // 2,
                    wrap=True,
                    mirror=False,
                ),
            )

class Circuit(ABC):
    """Abstract base class for quantum circuit ansätze."""

    def __init__(self) -> None:
        """Initialize the circuit."""
        pass

    @abstractmethod
    def n_params_per_layer(self, n_qubits: int) -> int:
        """
        Get the number of parameters per circuit layer.

        Args:
            n_qubits (int): Number of qubits in the circuit.

        Returns:
            int: Number of parameters required per layer.

        Raises:
            NotImplementedError: Must be implemented by subclasses.
        """
        raise NotImplementedError("n_params_per_layer method is not implemented")

    def n_pulse_params_per_layer(self, n_qubits: int) -> int:
        """
        Get the number of pulse parameters per circuit layer.

        Subclasses that do not use pulse-level simulation do not need to
        override this method.

        Args:
            n_qubits (int): Number of qubits in the circuit.

        Returns:
            int: Number of pulse parameters required per layer.

        Raises:
            NotImplementedError: If called but not overridden by subclass.
        """
        raise NotImplementedError("n_pulse_params_per_layer method is not implemented")

    @abstractmethod
    def get_control_indices(self, n_qubits: int) -> Optional[List[int]]:
        """
        Get indices for controlled rotation gates in one layer.

        Returns slice indices [start:stop:step] for extracting controlled
        gate parameters from a full parameter array for one layer.

        Args:
            n_qubits (int): Number of qubits in the circuit.

        Returns:
            Optional[List[int]]: List of three integers [start, stop, step]
                for slicing, or None if the circuit contains no controlled
                rotation gates.

        Raises:
            NotImplementedError: Must be implemented by subclasses.
        """
        raise NotImplementedError("get_control_indices method is not implemented")

    def get_control_angles(self, w: np.ndarray, n_qubits: int) -> Optional[np.ndarray]:
        """
        Extract angles for controlled rotation gates from parameter array.

        Args:
            w (np.ndarray): Parameter array for one layer.
            n_qubits (int): Number of qubits in the circuit.

        Returns:
            Optional[np.ndarray]: Array of controlled gate parameters,
                or empty array if circuit contains no controlled gates.
        """
        indices = self.get_control_indices(n_qubits)
        if indices is None:
            return np.array([])

        if len(indices) == 3 and None in indices:
            return w[indices[0] : indices[1] : indices[2]]
        else:
            return w.take(np.array(indices))

    def _build(self, w: np.ndarray, n_qubits: int, **kwargs: Any) -> Any:
        """
        Build one layer of the circuit using unitary or pulse-level parameters.

        Internal method that handles pulse parameter validation and context
        management before delegating to the build() method.

        Args:
            w (np.ndarray): Parameter array for the current layer.
            n_qubits (int): Number of qubits in the circuit.
            **kwargs: Additional keyword arguments:
                - gate_mode (str): "unitary" (default) or "pulse" for
                  pulse-level simulation.
                - pulse_params (np.ndarray): Pulse parameters if gate_mode="pulse".
                - noise_params (Dict): Noise parameters dictionary.

        Returns:
            Any: Result from the build() method.

        Raises:
            ValueError: If pulse_params length doesn't match expected count.
        """
        gate_mode = kwargs.get("gate_mode", "unitary")

        if gate_mode == "pulse" and "pulse_params" in kwargs:
            pulse_params_per_layer = self.n_pulse_params_per_layer(n_qubits)

            if len(kwargs["pulse_params"]) != pulse_params_per_layer:
                raise ValueError(
                    f"Pulse params length {len(kwargs['pulse_params'])} "
                    f"does not match expected {pulse_params_per_layer} "
                    f"for {n_qubits} qubits"
                )

            with Gates.pulse_manager_context(kwargs["pulse_params"]):
                return self.build(w, n_qubits, **kwargs)
        else:
            return self.build(w, n_qubits, **kwargs)

    @abstractmethod
    def build(self, w: np.ndarray, n_qubits: int, **kwargs: Any) -> Any:
        """
        Build one layer of the quantum circuit.

        Args:
            w (np.ndarray): Parameter array for the current layer.
            n_qubits (int): Number of qubits in the circuit.
            **kwargs: Additional keyword arguments passed from _build.

        Returns:
            Any: Circuit construction result.

        Raises:
            NotImplementedError: Must be implemented by subclasses.
        """
        raise NotImplementedError("build method is not implemented")

    def __call__(self, *args: Any, **kwds: Any) -> Any:
        """Call the _build method with provided arguments."""
        self._build(*args, **kwds)

class DeclarativeCircuit(Circuit):
    """
    A circuit defined entirely by a sequence of Block descriptors.

    Subclasses only need to set the class attribute `structure` — a tuple of

    All of `n_params_per_layer`, `n_pulse_params_per_layer`,
    `get_control_indices`, and `build` are derived automatically.
    """

    @classmethod
    def structure(cls) -> Tuple[Any, ...]:
        """Override in subclass to return the structure tuple."""
        raise NotImplementedError

    @classmethod
    def n_params_per_layer(cls, n_qubits: int) -> int:
        return sum(block.n_params(n_qubits) for block in cls.structure())

    @classmethod
    def n_pulse_params_per_layer(cls, n_qubits: int) -> int:
        return sum(block.n_pulse_params(n_qubits) for block in cls.structure())

    @classmethod
    def get_control_indices(cls, n_qubits: int) -> Optional[List]:
        """
        Computes parameter indices for controlled rotation Gates.
        Scans the structure for Block with
        [start, stop, step] into the flat parameter vector, or None.
        """
        structure = cls.structure()
        total_params = sum(block.n_params(n_qubits) for block in structure)

        # Collect which parameter indices correspond to controlled rotations
        controlled_indices = []
        offset = 0
        for block in structure:
            n = block.n_params(n_qubits)
            if block.is_controlled_rotation:
                controlled_indices.extend(range(offset, offset + n))
            offset += n

        # FIXME: this last part should be reworked

        if not controlled_indices:
            return None

        # Check if indices form a contiguous tail (the common case)
        # This preserves backwards compatibility with the [start, None, None] format
        if controlled_indices == list(
            range(total_params - len(controlled_indices), total_params)
        ):
            return [-len(controlled_indices), None, None]

        # Fallback: return raw indices (future-proof)
        return controlled_indices

    @classmethod
    def build(cls, w: np.ndarray, n_qubits: int, **kwargs: Any) -> None:
        structure = cls.structure()
        w_idx = 0
        for block in structure:
            w_idx = block.apply(n_qubits, w, w_idx, **kwargs)
            Gates.Barrier(wires=list(range(n_qubits)), **kwargs)

class Block:
    def __init__(
        self,
        gate: str,
        topology: Any = None,
        **kwargs,
    ):
        """
        Initialize a Block object; the atoms of Ansatzes.

        Args:
            gate (str): Name of the Gate class to use.
            topology (Any, optional): Topology of the gate for entangling gates.
                Defaults to None.
            kwargs (Any): Additional keyword arguments passed to the topology function.
        """
        if isinstance(gate, str):
            self.gate = getattr(Gates, gate)
        else:
            self.gate = gate

        if self.is_entangling:
            assert topology is not None, (
                "Topology must be specified for entangling gates"
            )

        self.topology = topology
        self.kwargs = kwargs

    def __repr__(self):
        if self.topology is None:
            return f"{self.__class__.__name__}({self.gate.__name__})"
        else:
            return (
                f"{self.__class__.__name__}"
                f"({self.topology.__name__}[{self.gate.__name__}])"
            )

    @property
    def is_entangling(self):
        return Gates.is_entangling(self.gate)

    @property
    def is_rotational(self):
        return Gates.is_rotational(self.gate)

    @property
    def is_controlled_rotation(self):
        return self.is_entangling and self.is_rotational

    def enough_qubits(self, n_qubits):
        if self.is_entangling:
            # NOTE This must be adjusted if default values
            # in Topology change
            span = self.kwargs.get("span", 1)
            if callable(span):
                span = span(n_qubits)

            return (n_qubits >= 2) and (n_qubits > span)

        return n_qubits >= 1

    def n_params(self, n_qubits: int) -> int:
        assert n_qubits > 0, "Number of qubits must be positive"

        if self.is_rotational:
            if self.is_entangling:
                if not self.enough_qubits(n_qubits):
                    warnings.warn(
                        f"Skipping {self.topology.__name__} with n_qubits={n_qubits} "
                        f"as there are not enough qubits"
                        f"for this topology."
                    )
                    return 0
                else:
                    return len(self.topology(n_qubits=n_qubits, **self.kwargs))
            else:
                return n_qubits if self.gate.__name__ != "Rot" else 3 * n_qubits

        return 0

    def n_pulse_params(self, n_qubits: int) -> int:
        assert n_qubits > 0, "Number of qubits must be positive"

        n_pulse_params = PulseInformation.num_params(self.gate)
        if self.is_entangling:
            if not self.enough_qubits(n_qubits):
                warnings.warn(
                    f"Skipping {self.topology.__name__} with n_qubits={n_qubits} "
                    f"as there are not enough qubits"
                    f"for this topology."
                )
                return 0
            else:
                return n_pulse_params * len(
                    self.topology(n_qubits=n_qubits, **self.kwargs)
                )
        return n_pulse_params * n_qubits

    def apply(
        self, n_qubits: int, w: np.ndarray = None, w_idx: int = None, **kwargs
    ) -> int:
        """
        Applies the block to the given circuit.

        Args:
            n_qubits (int): Number of qubits, the block is applied to.
            w (np.ndarray, optional): Weights to use for rotational gates.
                Defaults to None.
            w_idx (int, optional): Index of weights to use for rotational gates.
                Defaults to None.
            **kwargs (Any): Keyword arguments passed to the gate.

        Returns:
            int: The new index of weights after applying the block.
        """
        assert n_qubits > 0, "Number of qubits must be positive"

        iterator = (
            self.topology(n_qubits=n_qubits, **self.kwargs)
            if self.is_entangling
            else range(n_qubits)
        )

        for wires in iterator:
            if self.is_entangling and not self.enough_qubits(n_qubits):
                warnings.warn(
                    f"Skipping {self.topology.__name__} with n_qubits={n_qubits} "
                    f"as there are not enough qubits"
                    f"for this topology."
                )
                continue

            if self.is_rotational:
                assert w is not None, "w must be provided for rotational gates"
                assert w_idx is not None, "w_idx must be provided for rotational gates"

                if self.gate.__name__ == "Rot":
                    self.gate(
                        w[w_idx], w[w_idx + 1], w[w_idx + 2], wires=wires, **kwargs
                    )
                    w_idx += 3
                else:
                    self.gate(w[w_idx], wires=wires, **kwargs)
                    w_idx += 1
            else:
                self.gate(wires=wires, **kwargs)
        return w_idx