qilisdk 0.1.8__cp312-cp312-win_amd64.whl

qilisdk/digital/gates.py

@@ -0,0 +1,1308 @@
+# Copyright 2025 Qilimanjaro Quantum Tech
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import ClassVar, Generic, TypeVar
+
+import numpy as np
+from scipy.linalg import expm
+from typing_extensions import Self
+
+from qilisdk.core.parameterizable import Parameterizable
+from qilisdk.core.variables import Parameter, Term
+from qilisdk.settings import get_settings
+from qilisdk.yaml import yaml
+
+from .exceptions import (
+    GateHasNoMatrixError,
+    GateNotParameterizedError,
+    InvalidParameterNameError,
+    ParametersNotEqualError,
+)
+
+TBasicGate = TypeVar("TBasicGate", bound="BasicGate")
+
+
+def _complex_dtype() -> np.dtype:
+    return get_settings().complex_precision.dtype
+
+
+class Gate(Parameterizable, ABC):
+    """
+    Represents a quantum gate that can be used in quantum circuits.
+    """
+
+    PARAMETER_NAMES: ClassVar[list[str]] = []
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """
+        Retrieve the name of the gate.
+
+        Returns:
+            str: The name of the gate.
+        """
+
+    @property
+    @abstractmethod
+    def matrix(self) -> np.ndarray:
+        """
+        Retrieve the matrix of the gate.
+
+        Raises:
+            GateHasNoMatrixError: If gate has no matrix.
+
+        Returns:
+            np.ndarray: The matrix of the gate.
+        """
+
+    @property
+    def control_qubits(self) -> tuple[int, ...]:
+        """
+        Retrieve the indices of the control qubits.
+
+        Returns:
+            tuple[int, ...]: A tuple containing the indices of the control qubits.
+        """
+        return ()
+
+    @property
+    def target_qubits(self) -> tuple[int, ...]:
+        """
+        Retrieve the indices of the target qubits.
+
+        Returns:
+            tuple[int, ...]: A tuple containing the indices of the target qubits.
+        """
+        return ()
+
+    @property
+    def qubits(self) -> tuple[int, ...]:
+        """
+        Retrieve all qubits associated with the gate, including both control and target qubits.
+
+        Returns:
+            tuple[int, ...]: A tuple of all qubit indices on which the gate operates.
+        """
+        return self.control_qubits + self.target_qubits
+
+    @property
+    def nqubits(self) -> int:
+        """
+        Retrieve the number of qubits the gate acts upon.
+
+        Returns:
+            int: The number of qubits for this gate.
+        """
+        return len(self.qubits)
+
+    @property
+    def nparameters(self) -> int:
+        """
+        Retrieve the number of parameters for the gate.
+
+        Returns:
+            int: The count of parameters needed by the gate.
+        """
+        return len(self.get_parameters())
+
+    @property
+    def is_parameterized(self) -> bool:
+        """
+        Determine whether the gate requires parameters.
+
+        Returns:
+            bool: True if the gate is parameterized; otherwise, False.
+        """
+        return self.nparameters != 0
+
+    @property
+    def parameters(self) -> dict[str, Parameter]:
+        """Returns the raw parameter objects stored in the gate.
+
+        Returns:
+            dict[str, Parameter]: A dictionary mapping each Parameter object to its label.
+        """
+        return {}
+
+    def get_parameters(self) -> dict[str, float]:  # noqa: PLR6301
+        """
+        Retrieve a mapping of parameter names to their corresponding values.
+
+        Returns:
+            dict[str, float]: A dictionary mapping each parameter name to its numeric value.
+        """
+        return {}
+
+    def get_parameter_names(self) -> list[str]:
+        """
+        Retrieve the symbolic names of the gate's parameters.
+
+        Returns:
+            list[str]: A list containing the names of the parameters.
+        """
+        return list(self.get_parameters())
+
+    def get_parameter_values(self) -> list[float]:
+        """
+        Retrieve the numerical values assigned to the gate's parameters.
+
+        Returns:
+            list[float]: A list containing the parameter values.
+        """
+        return list(self.get_parameters().values())
+
+    def set_parameters(self, parameters: dict[str, float]) -> None:
+        """
+        Set the parameters for the gate using a dictionary mapping names to values.
+
+        Args:
+            parameters (dict[str, float]): A dictionary where keys are parameter names and values are the new parameter values.
+
+        Raises:
+            GateNotParameterizedError: If gate is not parameterized.
+            InvalidParameterNameError: If any provided parameter name is not valid for this gate.
+        """
+        if not self.is_parameterized:
+            raise GateNotParameterizedError
+
+        if any(name not in self.get_parameters() for name in parameters):
+            raise InvalidParameterNameError
+
+    def set_parameter_values(self, values: list[float]) -> None:
+        """
+        Set the numerical values for the gate's parameters.
+
+        Args:
+            values (list[float]): A list containing new parameter values.
+
+        Raises:
+            GateNotParameterizedError: If gate is not parameterized.
+            ParametersNotEqualError: If the number of provided values does not match the expected parameter count.
+        """
+        if not self.is_parameterized:
+            raise GateNotParameterizedError
+
+        if len(values) != len(self.get_parameters()):
+            raise ParametersNotEqualError
+
+    def get_parameter_bounds(self) -> dict[str, tuple[float, float]]:  # noqa: PLR6301
+        return {}
+
+    def set_parameter_bounds(self, ranges: dict[str, tuple[float, float]]) -> None:
+        if not self.is_parameterized:
+            raise GateNotParameterizedError
+
+    def __repr__(self) -> str:
+        qubits_str = f"({self.qubits[0]})" if self.nqubits == 1 else str(self.qubits)
+        return f"{self.name}{qubits_str}"
+
+
+@yaml.register_class
+class BasicGate(Gate):
+    """
+    Represents a quantum gate that can be used in quantum circuits.
+    """
+
+    def __init__(
+        self,
+        target_qubits: tuple[int, ...],
+        parameters: dict[str, Parameter] | None = None,
+        parameter_transforms: dict[str, Term] | None = None,
+    ) -> None:
+        """Build a basic gate.
+
+        Args:
+            target_qubits (tuple[int, ...]): Qubit indices the gate acts on. Duplicate indices are rejected.
+            parameters (dict[str, Parameter] | None): Optional parameter objects keyed by label for parameterized gates.
+
+        Raises:
+            ValueError: if duplicate target qubits are found.
+            ValueError: if any parameter transform is not a parameterized term.
+            InvalidParameterNameError: if any parameter mentioned in parameter_transforms is not in parameters.
+        """
+        # Check for duplicate integers in target_qubits.
+        super(BasicGate, self).__init__()
+        if len(target_qubits) != len(set(target_qubits)):
+            raise ValueError("Duplicate target qubits found.")
+
+        self._target_qubits: tuple[int, ...] = target_qubits
+        self._parameters: dict[str, Parameter] = parameters or {}
+        self._parameter_transforms: dict[str, Term] = parameter_transforms or {}
+        self._matrix: np.ndarray = self._generate_matrix()
+
+        # Check the transforms
+        for term in self._parameter_transforms:
+            # Ensure it's a parameterized term (i.e. no variables)
+            if not self._parameter_transforms[term].is_parameterized_term():
+                raise ValueError(
+                    f"Parameter transform '{term}' must be a parameterized term containing only Parameters."
+                )
+
+            # Check that anything mentioned in parameter_transforms is also in parameters
+            for param in self._parameter_transforms[term].variables():
+                if param.label not in self._parameters:
+                    raise InvalidParameterNameError
+
+    @property
+    def matrix(self) -> np.ndarray:
+        return self._matrix
+
+    @property
+    def target_qubits(self) -> tuple[int, ...]:
+        return self._target_qubits
+
+    @property
+    def parameters(self) -> dict[str, Parameter]:
+        return self._parameters
+
+    def get_parameters(self) -> dict[str, float]:
+        return {k: v.value for k, v in self._parameters.items()}
+
+    def set_parameters(self, parameters: dict[str, float]) -> None:
+        super().set_parameters(parameters=parameters)
+        for k, v in parameters.items():
+            self._parameters[k].set_value(v)
+        self._matrix = self._generate_matrix()
+
+    def set_parameter_values(self, values: list[float]) -> None:
+        super().set_parameter_values(values=values)
+
+        for key, value in zip(self.get_parameters(), values):
+            self._parameters[key].set_value(value)
+
+        self._matrix = self._generate_matrix()
+
+    def get_parameter_bounds(self) -> dict[str, tuple[float, float]]:
+        return {k: v.bounds for k, v in self._parameters.items()}
+
+    def set_parameter_bounds(self, ranges: dict[str, tuple[float, float]]) -> None:
+        super().set_parameter_bounds(ranges=ranges)
+        for label, bound in ranges.items():
+            if label not in self._parameters:
+                raise InvalidParameterNameError
+            self._parameters[label].set_bounds(bound[0], bound[1])
+
+    def controlled(self: Self, *control_qubits: int) -> Controlled[Self]:
+        """
+        Creates a controlled version of this unitary gate.
+
+        This method returns a new instance of a Controlled gate where the provided qubits serve as the
+        control qubits and the current unitary gate is used as the target. The resulting gate operates
+        on both the control and target qubits.
+
+        Args:
+            *control_qubits (int): One or more integer indices specifying the control qubits.
+
+        Returns:
+            Controlled: A new Controlled gate instance that wraps this unitary gate with the specified control qubits.
+        """
+        return Controlled(*control_qubits, basic_gate=self)
+
+    def adjoint(self: Self) -> Adjoint[Self]:
+        """
+        Returns the adjoint (conjugate transpose) of this unitary gate.
+
+        This method constructs and returns a new gate whose matrix is the conjugate transpose of the current
+        gate's matrix. The adjoint (or Hermitian conjugate) is commonly used to reverse the effect of a unitary operation.
+
+        Returns:
+            Adjoint: A new Adjoint gate instance representing the adjoint of this gate.
+        """
+        return Adjoint(basic_gate=self)
+
+    def exponential(self: Self) -> Exponential[Self]:
+        """
+        Returns the exponential of this unitary gate.
+
+        This method computes the matrix exponential of the current gate's matrix, resulting in a new gate.
+        The matrix exponential is useful for representing continuous time evolution in quantum systems and
+        appears in various quantum mechanics and quantum computing applications.
+
+        Returns:
+            Exponential: A new Exponential gate instance whose matrix is the matrix exponential of the current gate's matrix.
+        """
+        return Exponential(basic_gate=self)
+
+    @abstractmethod
+    def _generate_matrix(self) -> np.ndarray: ...
+
+
+@yaml.register_class
+class Modified(Gate, Generic[TBasicGate]):
+    def __init__(self, basic_gate: TBasicGate) -> None:
+        self._basic_gate: TBasicGate = basic_gate
+        self._matrix: np.ndarray
+
+    @property
+    def basic_gate(self) -> TBasicGate:
+        return self._basic_gate
+
+    @property
+    def matrix(self) -> np.ndarray:
+        return self._matrix
+
+    @property
+    def target_qubits(self) -> tuple[int, ...]:
+        return self._basic_gate.target_qubits
+
+    @property
+    def nparameters(self) -> int:
+        return self._basic_gate.nparameters
+
+    @property
+    def is_parameterized(self) -> bool:
+        return self._basic_gate.is_parameterized
+
+    @property
+    def parameters(self) -> dict[str, Parameter]:
+        return self._basic_gate.parameters
+
+    def get_parameters(self) -> dict[str, float]:
+        return self._basic_gate.get_parameters()
+
+    def get_parameter_names(self) -> list[str]:
+        return self._basic_gate.get_parameter_names()
+
+    def get_parameter_values(self) -> list[float]:
+        return self._basic_gate.get_parameter_values()
+
+    def set_parameters(self, parameters: dict[str, float]) -> None:
+        self._basic_gate.set_parameters(parameters=parameters)
+        self._matrix = self._generate_matrix()
+
+    def set_parameter_values(self, values: list[float]) -> None:
+        self._basic_gate.set_parameter_values(values=values)
+        self._matrix = self._generate_matrix()
+
+    def get_parameter_bounds(self) -> dict[str, tuple[float, float]]:
+        return self._basic_gate.get_parameter_bounds()
+
+    def set_parameter_bounds(self, ranges: dict[str, tuple[float, float]]) -> None:
+        self._basic_gate.set_parameter_bounds(ranges)
+
+    @abstractmethod
+    def _generate_matrix(self) -> np.ndarray: ...
+
+    def is_modified_from(self, gate_type: type[TBasicGate]) -> bool:
+        return isinstance(self.basic_gate, gate_type)
+
+
+@yaml.register_class
+class Controlled(Modified[TBasicGate]):
+    def __init__(self, *control_qubits: int, basic_gate: TBasicGate) -> None:
+        super().__init__(basic_gate=basic_gate)
+
+        # Check for duplicate integers in control_qubits.
+        if len(control_qubits) != len(set(control_qubits)):
+            raise ValueError("Duplicate control qubits found.")
+
+        # Check if any integer in control_qubits is also in unitary_gate.target_qubits.
+        if set(control_qubits) & set(basic_gate.target_qubits):
+            raise ValueError("Some control qubits are the same as unitary gate's target qubits.")
+
+        # Make sure we have some control qubits
+        if len(control_qubits) == 0:
+            raise ValueError("At least one control qubit must be specified.")
+
+        self._control_qubits = control_qubits + basic_gate.control_qubits
+        self._matrix = self._generate_matrix()
+
+    def _generate_matrix(self) -> np.ndarray:
+        i_full = np.eye(1 << self.nqubits, dtype=_complex_dtype())
+        # Construct projector P_control = |1...1><1...1| on the n control qubits.
+        P = np.array([[0, 0], [0, 1]], dtype=_complex_dtype())
+        for _ in range(len(self.control_qubits) - len(self.basic_gate.control_qubits) - 1):
+            P = np.kron(P, np.array([[0, 0], [0, 1]], dtype=_complex_dtype()))
+        # Extend the projector to the full space (control qubits ⊗ target qubit). It acts as P_control ⊗ I_target.
+        i_target = np.eye(1 << self.basic_gate.nqubits, dtype=_complex_dtype())
+        # The controlled gate is then:
+        controlled = i_full + np.kron(P, self.basic_gate.matrix - i_target)
+        return controlled
+
+    @property
+    def control_qubits(self) -> tuple[int, ...]:
+        return self._control_qubits
+
+    @property
+    def name(self) -> str:
+        return "C" * len(self.control_qubits) + self.basic_gate.name
+
+
+@yaml.register_class
+class Adjoint(Modified[TBasicGate]):
+    """
+    Represents the adjoint (conjugate transpose) of a unitary gate.
+    """
+
+    def __init__(self, basic_gate: TBasicGate) -> None:
+        super().__init__(basic_gate=basic_gate)
+        self._matrix = self._generate_matrix()
+
+    def _generate_matrix(self) -> np.ndarray:
+        return self.basic_gate.matrix.conj().T
+
+    @property
+    def name(self) -> str:
+        """
+        Get the name of the adjoint gate.
+
+        The name is constructed by appending an adjoint symbol (†) to the name of the underlying gate.
+        For example, if the underlying gate's name is "X", this property returns "X†".
+
+        Returns:
+            str: The name of the adjoint gate.
+        """
+        return self.basic_gate.name + "†"
+
+
+@yaml.register_class
+class Exponential(Modified[TBasicGate]):
+    """
+    Represents the exponential of a unitary gate.
+    The matrix of this gate is computed as the matrix exponential (e^(gate.matrix))
+    of the underlying gate's matrix.
+    """
+
+    def __init__(self, basic_gate: TBasicGate) -> None:
+        super().__init__(basic_gate=basic_gate)
+        self._matrix = self._generate_matrix()
+
+    def _generate_matrix(self) -> np.ndarray:
+        return expm(self.basic_gate.matrix)
+
+    @property
+    def name(self) -> str:
+        """
+        Get the name of the exponential gate.
+
+        The name is constructed by prepending the underlying gate's name within "e^".
+        For example, if the underlying gate's name is "X", the exponential gate's name is "e^X".
+
+        Returns:
+            str: The generated name of the exponential gate.
+        """
+        return f"e^{self.basic_gate.name}"
+
+
+@yaml.register_class
+class M(Gate):
+    """
+    Measurement operation on a qubit. The measurement is performed in the computational basis and the
+    result is stored in a classical bit with the same label as the measured qubit.
+    """
+
+    def __init__(self, *qubits: int) -> None:
+        """
+        Initialize a measurement operation.
+
+        Args:
+            qubit (int): The qubit index to be measured.
+        """
+        self._target_qubits = qubits
+
+    @property
+    def name(self) -> str:
+        return "M"
+
+    @property
+    def matrix(self) -> np.ndarray:
+        raise GateHasNoMatrixError
+
+    @property
+    def target_qubits(self) -> tuple[int, ...]:
+        return self._target_qubits
+
+
+@yaml.register_class
+class I(BasicGate):
+    """
+    The Identity gate.
+
+    The associated matrix is:
+
+    .. code-block:: text
+
+       [[1, 0],
+       [0, 1]]
+
+    """
+
+    def __init__(self, qubit: int) -> None:
+        """
+        Initialize a Pauli-X gate.
+
+        Args:
+            qubit (int): The target qubit index for the X gate.
+        """
+        super().__init__(target_qubits=(qubit,))
+
+    @property
+    def name(self) -> str:
+        return "I"
+
+    def _generate_matrix(self) -> np.ndarray:  # noqa: PLR6301
+        return np.array([[1, 0], [0, 1]], dtype=_complex_dtype())
+
+
+@yaml.register_class
+class X(BasicGate):
+    """
+    The Pauli-X gate.
+
+    The associated matrix is:
+
+    .. code-block:: text
+
+       [[0, 1],
+       [1, 0]]
+
+    This is a pi radians rotation around the X-axis in the Bloch sphere.
+    """
+
+    def __init__(self, qubit: int) -> None:
+        """
+        Initialize a Pauli-X gate.
+
+        Args:
+            qubit (int): The target qubit index for the X gate.
+        """
+        super().__init__(target_qubits=(qubit,))
+
+    @property
+    def name(self) -> str:
+        return "X"
+
+    def _generate_matrix(self) -> np.ndarray:  # noqa: PLR6301
+        return np.array([[0, 1], [1, 0]], dtype=_complex_dtype())
+
+
+@yaml.register_class
+class Y(BasicGate):
+    """
+    The Pauli-Y gate.
+
+    The associated matrix is:
+
+    .. code-block:: text
+
+       [[ 0, -i ],
+        [ i,  0 ]]
+
+    This is a pi radians rotation around the Y-axis in the Bloch sphere.
+    """
+
+    def __init__(self, qubit: int) -> None:
+        """
+        Initialize a Pauli-Y gate.
+
+        Args:
+            qubit (int): The target qubit index for the Y gate.
+        """
+        super().__init__(target_qubits=(qubit,))
+
+    @property
+    def name(self) -> str:
+        return "Y"
+
+    def _generate_matrix(self) -> np.ndarray:  # noqa: PLR6301
+        return np.array([[0, -1j], [1j, 0]], dtype=_complex_dtype())
+
+
+@yaml.register_class
+class Z(BasicGate):
+    """
+    The Pauli-Z gate.
+
+    The associated matrix is:
+
+    .. code-block:: text
+
+        [[1, 0],
+        [0, -1]]
+
+    This is a pi radians rotation around the Z-axis in the Bloch sphere.
+    """
+
+    def __init__(self, qubit: int) -> None:
+        """
+        Initialize a Pauli-Z gate.
+
+        Args:
+            qubit (int): The target qubit index for the Z gate.
+        """
+        super().__init__(target_qubits=(qubit,))
+
+    @property
+    def name(self) -> str:
+        return "Z"
+
+    def _generate_matrix(self) -> np.ndarray:  # noqa: PLR6301
+        return np.array([[1, 0], [0, -1]], dtype=_complex_dtype())
+
+
+@yaml.register_class
+class H(BasicGate):
+    """
+    The Hadamard gate.
+
+    The associated matrix is:
+
+    .. code-block:: text
+
+        [[1/sqrt(2),  1/sqrt(2)],
+         [1/sqrt(2), -1/sqrt(2)]]
+
+    This is a pi radians rotation around the (X+Z)-axis in the Bloch sphere.
+    """
+
+    def __init__(self, qubit: int) -> None:
+        """
+        Initialize a Hadamard gate.
+
+        Args:
+            qubit (int): The target qubit index for the Hadamard gate.
+        """
+        super().__init__(target_qubits=(qubit,))
+
+    @property
+    def name(self) -> str:
+        return "H"
+
+    def _generate_matrix(self) -> np.ndarray:  # noqa: PLR6301
+        return (1 / np.sqrt(2)) * np.array([[1, 1], [1, -1]], dtype=_complex_dtype())
+
+
+@yaml.register_class
+class S(BasicGate):
+    """
+    Represents the S gate, which induces a pi/2 phase.
+
+    The associated matrix is:
+
+    .. code-block:: text
+
+        [[1, 0],
+         [0, i]]
+
+    This gate is also known as the square root of Z gate: ``S**2=Z``, or equivalently it is a pi/2 radians rotation around the Z-axis in the Bloch sphere.
+    """
+
+    def __init__(self, qubit: int) -> None:
+        """
+        Initialize an S gate.
+
+        Args:
+            qubit (int): The target qubit index for the S gate.
+        """
+        super().__init__(target_qubits=(qubit,))
+
+    @property
+    def name(self) -> str:
+        return "S"
+
+    def _generate_matrix(self) -> np.ndarray:  # noqa: PLR6301
+        return np.array([[1, 0], [0, 1j]], dtype=_complex_dtype())
+
+
+@yaml.register_class
+class T(BasicGate):
+    """
+    Represents the T gate, which induces a pi/4 phase.
+
+    The associated matrix is:
+
+    .. code-block:: text
+
+        [[1,           0],
+         [0, exp(i*pi/4)]]
+
+    This gate is also known as the fourth-root of Z gate: ``T**4=Z``, or equivalently it is a pi/4 radians rotation around the Z-axis in the Bloch sphere.
+    """
+
+    def __init__(self, qubit: int) -> None:
+        """
+        Initialize a T gate.
+
+        Args:
+            qubit (int): The target qubit index for the T gate.
+        """
+        super().__init__(target_qubits=(qubit,))
+
+    @property
+    def name(self) -> str:
+        return "T"
+
+    def _generate_matrix(self) -> np.ndarray:  # noqa: PLR6301
+        return np.array([[1, 0], [0, np.exp(1j * np.pi / 4)]], dtype=_complex_dtype())
+
+
+def _process_param(
+    name: str,
+    value: float | Parameter | Term,
+    params_to_init: dict[str, Parameter],
+    terms_to_init: dict[str, Term],
+) -> None:
+    """
+    Process a parameter value and update the params_to_init and terms_to_init dictionaries.
+    Args:
+        name (str): The name of the parameter.
+        value (float | Parameter | Term): The value of the parameter.
+        params_to_init (dict[str, Parameter]): The dictionary to initialize parameters.
+        terms_to_init (dict[str, Term]): The dictionary to initialize terms.
+    Raises:
+        ValueError: If a Term is provided that contains Variables instead of Parameters.
+    """
+    if isinstance(value, Parameter):
+        params_to_init[name] = value
+    elif isinstance(value, Term):
+        if not value.is_parameterized_term() and len(value.variables()) > 0:
+            raise ValueError(f"RX gate Term '{name}' must contain a Parameter and not Variables.")
+        for param in value.variables():
+            if isinstance(param, Parameter):
+                params_to_init[param.label] = param
+        terms_to_init[name] = value
+    else:
+        params_to_init[name] = Parameter(name, value)
+
+
+@yaml.register_class
+class RX(BasicGate):
+    """
+    Represents a `theta` angle rotation around the X-axis (polar) in the Bloch sphere.
+
+    The associated matrix is:
+
+    .. code-block:: text
+
+        [[cos(theta/2),     -i*sin(theta/2)],
+         [-i*sin(theta/2),     cos(theta/2)]]
+
+    This is an exponential of the Pauli-X operator:
+        ``RX(theta) = exp(-i*theta*X/2)``
+    """
+
+    PARAMETER_NAMES: ClassVar[list[str]] = ["theta"]
+
+    def __init__(self, qubit: int, *, theta: float | Parameter | Term) -> None:
+        """
+        Initialize an RX gate.
+
+        Args:
+            qubit (int): The target qubit index for the rotation.
+            theta (float | Parameter | Term): The rotation angle (polar) in radians.
+
+        """
+
+        # Initialize parameter terms dictionary
+        params_to_init: dict[str, Parameter] = {}
+        terms_to_init: dict[str, Term] = {}
+
+        # Process the parameters
+        _process_param("theta", theta, params_to_init, terms_to_init)
+
+        # Initialize the base class
+        super().__init__(
+            target_qubits=(qubit,),
+            parameters=params_to_init,
+            parameter_transforms=terms_to_init,
+        )
+
+    @property
+    def name(self) -> str:
+        return "RX"
+
+    @property
+    def theta(self) -> float:
+        if "theta" in self._parameter_transforms:
+            val = self._parameter_transforms["theta"].evaluate({})
+            if isinstance(val, complex):
+                return val.real
+            return val
+        return self.get_parameters()["theta"]
+
+    def _generate_matrix(self) -> np.ndarray:
+        theta = self.theta
+        cos_half = np.cos(theta / 2)
+        sin_half = np.sin(theta / 2)
+        return np.array([[cos_half, -1j * sin_half], [-1j * sin_half, cos_half]], dtype=_complex_dtype())
+
+
+@yaml.register_class
+class RY(BasicGate):
+    """
+    Represents a `theta` angle rotation around the Y-axis (polar) in the Bloch sphere.
+
+    The associated matrix is:
+
+    .. code-block:: text
+
+        [[cos(theta/2), -sin(theta/2)],
+         [sin(theta/2),  cos(theta/2)]]
+
+    This is an exponential of the Pauli-Y operator:
+        ``RY(theta) = exp(-i*theta*Y/2)``
+    """
+
+    PARAMETER_NAMES: ClassVar[list[str]] = ["theta"]
+
+    def __init__(self, qubit: int, *, theta: float | Parameter | Term) -> None:
+        """
+        Initialize an RY gate.
+
+        Args:
+            qubit (int): The target qubit index for the rotation.
+            theta (float | Parameter | Term): The rotation angle (polar) in radians.
+
+        """
+
+        # Initialize parameter terms dictionary
+        params_to_init: dict[str, Parameter] = {}
+        terms_to_init: dict[str, Term] = {}
+
+        # Process the parameters
+        _process_param("theta", theta, params_to_init, terms_to_init)
+
+        # Initialize the base class
+        super().__init__(
+            target_qubits=(qubit,),
+            parameters=params_to_init,
+            parameter_transforms=terms_to_init,
+        )
+
+    @property
+    def name(self) -> str:
+        return "RY"
+
+    @property
+    def theta(self) -> float:
+        if "theta" in self._parameter_transforms:
+            val = self._parameter_transforms["theta"].evaluate({})
+            if isinstance(val, complex):
+                return val.real
+            return val
+        return self.get_parameters()["theta"]
+
+    def _generate_matrix(self) -> np.ndarray:
+        theta = self.theta
+        cos_half = np.cos(theta / 2)
+        sin_half = np.sin(theta / 2)
+        return np.array([[cos_half, -sin_half], [sin_half, cos_half]], dtype=_complex_dtype())
+
+
+@yaml.register_class
+class RZ(BasicGate):
+    """
+    Represents a `phi` angle rotation around the Z-axis (azimuthal) in the Bloch sphere.
+
+    The associated matrix is:
+
+    .. code-block:: text
+
+        [[exp(-i*phi/2),              0],
+         [0,               exp(i*phi/2)]]
+
+    This is an exponential of the Pauli-Z operator:
+        ``RZ(phi) = exp(-i*phi*Z/2)``
+
+    Which is equivalent to the U1 gate plus a global phase:
+        ``RZ(phi) = exp(-i*phi/2)U1(phi)``
+
+    Other unitaries you can get from this one are:
+        - ``RZ(phi=pi) = exp(-i*pi/2) Z = -i Z``
+        - ``RZ(phi=pi/2) = exp(-i*pi/4) S``
+        - ``RZ(phi=pi/4) = exp(-i*pi/8) T``
+    """
+
+    PARAMETER_NAMES: ClassVar[list[str]] = ["phi"]
+
+    def __init__(self, qubit: int, *, phi: float | Parameter | Term) -> None:
+        """
+        Initialize an RZ gate.
+
+        Args:
+            qubit (int): The target qubit index for the rotation.
+            phi (float | Parameter | Term): The rotation angle (azimuthal) in radians.
+
+        """
+
+        # Initialize parameter terms dictionary
+        params_to_init: dict[str, Parameter] = {}
+        terms_to_init: dict[str, Term] = {}
+
+        # Process the parameters
+        _process_param("phi", phi, params_to_init, terms_to_init)
+
+        # Initialize the base class
+        super().__init__(
+            target_qubits=(qubit,),
+            parameters=params_to_init,
+            parameter_transforms=terms_to_init,
+        )
+
+    @property
+    def name(self) -> str:
+        return "RZ"
+
+    @property
+    def phi(self) -> float:
+        if "phi" in self._parameter_transforms:
+            val = self._parameter_transforms["phi"].evaluate({})
+            if isinstance(val, complex):
+                return val.real
+            return val
+        return self.get_parameters()["phi"]
+
+    def _generate_matrix(self) -> np.ndarray:
+        phi = self.phi
+        return np.array([[np.exp(-0.5j * phi), 0.0], [0.0, np.exp(0.5j * phi)]], dtype=_complex_dtype())
+
+
+@yaml.register_class
+class U1(BasicGate):
+    """
+    Represents the U1 gate defined by an azimuthal angle `phi`.
+
+    The associated matrix is:
+
+    .. code-block:: text
+
+        [[1,            0],
+         [0, exp(i*phi)]]
+
+    Which is equivalent to the RZ gate plus a global phase:
+        ``U1(phi) = exp(i*phi/2)RZ(phi)``
+
+    Other unitaries you can get from this one are:
+        - ``U1(phi=np.pi) = Z``
+        - ``U1(phi=np.pi/2) = S``
+        - ``U1(phi=np.pi/4) = T``
+    """
+
+    PARAMETER_NAMES: ClassVar[list[str]] = ["phi"]
+
+    def __init__(self, qubit: int, *, phi: float | Parameter | Term) -> None:
+        """
+        Initialize a U1 gate.
+
+        Args:
+            qubit (int): The target qubit index for the U1 gate.
+            phi (float | Parameter | Term): The phase to add, or equivalently the rotation angle (azimuthal) in radians.
+        """
+        # Initialize parameter terms dictionary
+        params_to_init: dict[str, Parameter] = {}
+        terms_to_init: dict[str, Term] = {}
+
+        # Process the parameters
+        _process_param("phi", phi, params_to_init, terms_to_init)
+
+        # Initialize the base class
+        super().__init__(
+            target_qubits=(qubit,),
+            parameters=params_to_init,
+            parameter_transforms=terms_to_init,
+        )
+
+    @property
+    def name(self) -> str:
+        return "U1"
+
+    @property
+    def phi(self) -> float:
+        if "phi" in self._parameter_transforms:
+            val = self._parameter_transforms["phi"].evaluate({})
+            if isinstance(val, complex):
+                return val.real
+            return val
+        return self.get_parameters()["phi"]
+
+    def _generate_matrix(self) -> np.ndarray:
+        phi = self.phi
+        return np.array([[1, 0], [0, np.exp(1j * phi)]], dtype=_complex_dtype())
+
+
+@yaml.register_class
+class U2(BasicGate):
+    """
+    Represents the U2 gate defined by the angles `phi` and `gamma`.
+
+    The associated matrix is:
+
+    .. code-block:: text
+
+        1/sqrt(2)*[[1,                   -exp(i*gamma)],
+                   [exp(i*phi),    exp(i*(phi+gamma))]]
+
+    Which is equivalent to two azimuthal rotations of `phi` and `gamma`, with a pi/2 polar rotation in between:
+        ``U2(phi, gamma) = exp(i*(phi+gamma)/2) RZ(phi) RY(pi/2) RZ(gamma)``
+
+    This is the same matrix of `qiskit` and `pennylane`, differing from `qibo` implementation on a global phase:
+        ``U2(phi, gamma) = U2_qiskit/pennylane(phi, gamma) = exp(i*(phi+gamma)/2) U2_qibo(phi, gamma)``
+
+    Other unitaries you can get from this one are:
+        - ``U2(phi=0, gamma=pi) = H``
+        - ``U2(phi=0, gamma=0) = RY(theta=pi/2)``
+        - ``U2(phi=-pi/2, gamma=pi/2) = RX(theta=pi/2)``
+    """
+
+    PARAMETER_NAMES: ClassVar[list[str]] = ["phi", "gamma"]
+
+    def __init__(self, qubit: int, *, phi: float | Parameter | Term, gamma: float | Parameter | Term) -> None:
+        """
+        Initialize a U2 gate.
+
+        Args:
+            qubit (int): The target qubit index for the U2 gate.
+            phi (float | Parameter | Term): The first phase parameter, or equivalently the first rotation angle (azimuthal) in radians.
+            gamma (float | Parameter | Term): The second phase parameter, or equivalently the second rotation angle (azimuthal) in radians.
+
+        """
+        # Initialize parameter terms dictionary
+        params_to_init: dict[str, Parameter] = {}
+        terms_to_init: dict[str, Term] = {}
+
+        # Process the parameters
+        _process_param("phi", phi, params_to_init, terms_to_init)
+        _process_param("gamma", gamma, params_to_init, terms_to_init)
+
+        # Initialize the base class
+        super().__init__(
+            target_qubits=(qubit,),
+            parameters=params_to_init,
+            parameter_transforms=terms_to_init,
+        )
+
+    @property
+    def name(self) -> str:
+        return "U2"
+
+    @property
+    def phi(self) -> float:
+        if "phi" in self._parameter_transforms:
+            val = self._parameter_transforms["phi"].evaluate({})
+            if isinstance(val, complex):
+                return val.real
+            return val
+        return self.get_parameters()["phi"]
+
+    @property
+    def gamma(self) -> float:
+        if "gamma" in self._parameter_transforms:
+            val = self._parameter_transforms["gamma"].evaluate({})
+            if isinstance(val, complex):
+                return val.real
+            return val
+        return self.get_parameters()["gamma"]
+
+    def _generate_matrix(self) -> np.ndarray:
+        phi = self.phi
+        gamma = self.gamma
+        return (1 / np.sqrt(2)) * np.array(
+            [
+                [1, -np.exp(1j * gamma)],
+                [np.exp(1j * phi), np.exp(1j * (phi + gamma))],
+            ],
+            dtype=_complex_dtype(),
+        )
+
+
+@yaml.register_class
+class U3(BasicGate):
+    """
+    Represents the U3 gate defined by the angles `theta`, `phi` and `gamma`.
+
+    The associated matrix is:
+
+    .. code-block:: text
+
+        [[cos(theta/2), -exp(i*gamma/2*sin(theta/2))],
+         [exp(i*phi/2)*sin(theta/2),    exp(i*(phi+gamma))*cos(theta/2)]]
+
+    Which is equivalent to two azimuthal rotations of `phi` and `gamma`, with a 'theta' polar rotation in between:
+        ``U3(theta, phi, gamma) = exp(i*(phi+gamma)/2) RZ(phi) RY(theta) RZ(gamma)``
+
+    This is the same matrix of `qiskit` and `pennylane`, differing from `QASM` and `qibo` implementation on a global phase:
+        ``U3(theta, phi, gamma) = U3_qiskit/pennylane(theta, phi, gamma) = exp(-i*(phi+gamma)/2) U3_QASM/qibo(theta, phi, gamma)``
+
+    Other unitaries you can get from this one are:
+        - ``U3(theta=pi/2, phi, gamma) = U2(phi, gamma)``
+        - ``U3(theta=0, phi=0, gamma) = U1(gamma)`` and ``U3(theta=0, phi, gamma=0) = U1(phi)``
+        - ``U3(theta, phi=0, gamma=0) = RY(theta)``
+        - ``U3(theta, phi=-pi/2, gamma=pi/2) = RX(theta)``
+    """
+
+    PARAMETER_NAMES: ClassVar[list[str]] = ["theta", "phi", "gamma"]
+
+    def __init__(
+        self,
+        qubit: int,
+        *,
+        theta: float | Parameter | Term,
+        phi: float | Parameter | Term,
+        gamma: float | Parameter | Term,
+    ) -> None:
+        """
+        Initialize a U3 gate.
+
+        Args:
+            qubit (int): The target qubit index for the U3 gate.
+            theta (float | Parameter | Term): The rotation angle (polar), in between both phase rotations (azimuthal).
+            phi (float | Parameter | Term): The first phase parameter, or equivalently the first rotation angle (azimuthal) in radians.
+            gamma (float | Parameter | Term): The second phase parameter, or equivalently the second rotation angle (azimuthal) in radians.
+
+        """
+
+        # Initialize parameter terms dictionary
+        params_to_init: dict[str, Parameter] = {}
+        terms_to_init: dict[str, Term] = {}
+
+        # Process the parameters
+        _process_param("theta", theta, params_to_init, terms_to_init)
+        _process_param("phi", phi, params_to_init, terms_to_init)
+        _process_param("gamma", gamma, params_to_init, terms_to_init)
+
+        # Initialize the base class
+        super().__init__(
+            target_qubits=(qubit,),
+            parameters=params_to_init,
+            parameter_transforms=terms_to_init,
+        )
+
+    @property
+    def name(self) -> str:
+        return "U3"
+
+    @property
+    def theta(self) -> float:
+        if "theta" in self._parameter_transforms:
+            val = self._parameter_transforms["theta"].evaluate({})
+            if isinstance(val, complex):
+                return val.real
+            return val
+        return self.get_parameters()["theta"]
+
+    @property
+    def phi(self) -> float:
+        if "phi" in self._parameter_transforms:
+            val = self._parameter_transforms["phi"].evaluate({})
+            if isinstance(val, complex):
+                return val.real
+            return val
+        return self.get_parameters()["phi"]
+
+    @property
+    def gamma(self) -> float:
+        if "gamma" in self._parameter_transforms:
+            val = self._parameter_transforms["gamma"].evaluate({})
+            if isinstance(val, complex):
+                return val.real
+            return val
+        return self.get_parameters()["gamma"]
+
+    def _generate_matrix(self) -> np.ndarray:
+        theta = self.theta
+        phi = self.phi
+        gamma = self.gamma
+        return np.array(
+            [
+                [np.cos(theta / 2), -np.exp(1j * gamma) * np.sin(theta / 2)],
+                [np.exp(1j * phi) * np.sin(theta / 2), np.exp(1j * (phi + gamma)) * np.cos(theta / 2)],
+            ],
+            dtype=_complex_dtype(),
+        )
+
+
+@yaml.register_class
+class CNOT(Controlled[X]):
+    """
+    Represents the CNOT gate.
+
+    The associated matrix is:
+
+    .. code-block:: text
+
+        [[1, 0, 0, 0],
+         [0, 1, 0, 0],
+         [0, 0, 0, 1],
+         [0, 0, 1, 0]]
+
+    Which is equivalent to the CZ gate surrounded by two H's gates on the target qubit:
+        ``CNOT(control, target) = H(target) CZ(control, target) H(target)``
+    """
+
+    def __init__(self, control: int, target: int) -> None:
+        super().__init__(control, basic_gate=X(target))
+
+    @property
+    def name(self) -> str:
+        return "CNOT"
+
+
+@yaml.register_class
+class CZ(Controlled[Z]):
+    """
+    Represents the CZ gate.
+
+    The associated matrix is:
+
+    .. code-block:: text
+
+        [[1, 0, 0, 0],
+         [0, 1, 0, 0],
+         [0, 0, 1, 0],
+         [0, 0, 0, -1]]
+
+    This gate is totally symmetric respect control and target, meaning that both are control and target in reality:
+        ``CZ(control, target) = CZ(target, control)``
+
+    It is also equivalent to the CNOT gate surrounded by two H's gates on the target qubit:
+        ``CZ(control, target) = H(target) CNOT(control, target) H(target)``
+    """
+
+    def __init__(self, control: int, target: int) -> None:
+        super().__init__(control, basic_gate=Z(target))
+
+
+@yaml.register_class
+class SWAP(BasicGate):
+    """
+    The SWAP gate.
+
+    The associated matrix is:
+
+    .. code-block:: text
+
+       [[1, 0, 0, 0],
+        [0, 0, 1, 0],
+        [0, 1, 0, 0],
+        [0, 0, 0, 1]]
+
+    """
+
+    def __init__(self, qubit_a: int, qubit_b: int) -> None:
+        """
+        Args:
+            qubit_a (int): First qubit to swap with.
+            qubit_b (int): Second qubit to swap with.
+        """
+        super().__init__(target_qubits=(qubit_a, qubit_b))
+
+    @property
+    def name(self) -> str:
+        return "SWAP"
+
+    def _generate_matrix(self) -> np.ndarray:  # noqa: PLR6301
+        return np.array([[1, 0, 0, 0], [0, 0, 1, 0], [0, 1, 0, 0], [0, 0, 0, 1]], dtype=_complex_dtype())