qilisdk 0.1.8__cp312-cp312-win32.whl

qilisdk/digital/circuit.py

@@ -0,0 +1,371 @@
+# 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
+
+import random
+from typing import TYPE_CHECKING, Iterable
+
+import numpy as np
+from typing_extensions import Self
+
+from qilisdk.core.parameterizable import Parameterizable
+from qilisdk.core.variables import Domain, Parameter
+from qilisdk.utils.visualization import CircuitStyle
+from qilisdk.yaml import yaml
+
+from .exceptions import ParametersNotEqualError, QubitOutOfRangeError
+from .gates import BasicGate, Gate
+
+if TYPE_CHECKING:
+    from qilisdk.core.types import RealNumber
+
+
+@yaml.register_class
+class Circuit(Parameterizable):
+    def __init__(self, nqubits: int) -> None:
+        """
+        Initialize a Circuit instance with a specified number of qubits.
+
+        Args:
+            nqubits (int): The number of qubits in the circuit.
+        """
+        super(Circuit, self).__init__()
+        self._nqubits: int = nqubits
+        self._gates: list[Gate] = []
+        self._init_state: np.ndarray = np.zeros(nqubits)
+        self._parameters: dict[str, Parameter] = {}
+
+    @property
+    def nqubits(self) -> int:
+        """
+        Retrieve the number of qubits in the circuit.
+
+        Returns:
+            int: The total number of qubits.
+        """
+        return self._nqubits
+
+    @property
+    def nparameters(self) -> int:
+        """
+        Retrieve the total number of parameters required by all parameterized gates in the circuit.
+
+        Returns:
+            int: The total count of parameters from all parameterized gates.
+        """
+        return len(self._parameters)
+
+    @property
+    def gates(self) -> list[Gate]:
+        """
+        Retrieve the list of gates in the circuit.
+
+        Returns:
+            list[Gate]: A list of gates that have been added to the circuit.
+        """
+        return self._gates
+
+    def get_parameter_values(self) -> list[float]:
+        """
+        Retrieve the parameter values from all parameterized gates in the circuit.
+
+        Returns:
+            list[float]: A list of parameter values from each parameterized gate.
+        """
+        return [param.value for param in self._parameters.values()]
+
+    def get_parameter_names(self) -> list[str]:
+        """
+        Retrieve the parameter values from all parameterized gates in the circuit.
+
+        Returns:
+            list[float]: A list of parameter values from each parameterized gate.
+        """
+        return list(self._parameters.keys())
+
+    def get_parameters(self) -> dict[str, float]:
+        """
+        Retrieve the parameter names and values from all parameterized gates in the circuit.
+
+        Returns:
+            dict[str, float]: A dictionary of the parameters with their current values.
+        """
+        return {label: param.value for label, param in self._parameters.items()}
+
+    def set_parameter_values(self, values: list[float]) -> None:
+        """
+        Set new parameter values for all parameterized gates in the circuit.
+
+        Args:
+            values (list[float]): A list containing new parameter values to assign to the parameterized gates.
+
+        Raises:
+            ParametersNotEqualError: If the number of provided values does not match the expected number of parameters.
+        """
+        if len(values) != self.nparameters:
+            raise ParametersNotEqualError
+        for i, parameter in enumerate(self._parameters.values()):
+            parameter.set_value(values[i])
+
+    def set_parameters(self, parameters: dict[str, RealNumber]) -> None:
+        """Set the parameter values by their label. No need to provide the full list of parameters.
+
+        Args:
+            parameters (dict[str, float]): A dictionary with the labels of the parameters to be modified and their new value.
+
+        Raises:
+            ValueError: if the label provided doesn't correspond to a parameter defined in this circuit.
+        """
+        for label, param in parameters.items():
+            if label not in self._parameters:
+                raise ValueError(f"Parameter {label} is not defined in this circuit.")
+            self._parameters[label].set_value(param)
+
+    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:
+        for label, bound in ranges.items():
+            if label not in self._parameters:
+                raise ValueError(
+                    f"The provided parameter label {label} is not defined in the list of parameters in this object."
+                )
+            self._parameters[label].set_bounds(bound[0], bound[1])
+
+    def _parse_params(self, gate: Gate) -> None:
+        """Parse The parameters in the gate
+
+        Args:
+            gate (Gate): The gate to be parsed.
+        """
+        if gate.is_parameterized:
+            param_base_label = f"{gate.name}({','.join(map(str, gate.qubits))})"
+            for label, parameter in gate.parameters.items():
+                if label == parameter.label and label in gate.PARAMETER_NAMES:
+                    parameter_label = param_base_label + f"_{label}_{len(self._parameters)}"
+                else:
+                    parameter_label = parameter.label
+                self._parameters[parameter_label] = gate.parameters[label]
+
+    def _add(self, gate: Gate) -> None:
+        """
+        Add a quantum gate to the circuit.
+
+        Args:
+            gate (Gate): The quantum gate or a list of quantum gates to be added to the circuit.
+
+        Raises:
+            QubitOutOfRangeError: If any qubit index used by the gate is not within the circuit's qubit range.
+        """
+        if any(qubit >= self.nqubits for qubit in gate.qubits):
+            raise QubitOutOfRangeError
+
+        self._parse_params(gate)
+        self._gates.append(gate)
+
+    def add(self, gates: Gate | Iterable[Gate]) -> None:
+        """
+        Add a quantum gate to the circuit.
+
+        Args:
+            gates (Gate | list[Gate]): The quantum gate or a list of quantum gates to be added to the circuit.
+        """
+        if isinstance(gates, Gate):
+            self._add(gates)
+            return
+        for g in gates:
+            self._add(g)
+
+    def _insert(self, gate: Gate, index: int = -1) -> None:
+        """Insert a quantum gate to the circuit at a given index.
+
+        Args:
+            gate (Gate): The gate to be inserted.
+            index (int, optional): The index at which the gate is inserted. Defaults to -1.
+
+        Raises:
+            QubitOutOfRangeError: If any qubit index used by the gate is not within the circuit's qubit range.
+        """
+        if any(qubit >= self.nqubits for qubit in gate.qubits):
+            raise QubitOutOfRangeError
+
+        self._parse_params(gate)
+        self._gates.insert(index, gate)
+
+    def insert(self, gates: Gate | Iterable[Gate], index: int = -1) -> None:
+        """Insert a quantum gate to the circuit at a given index.
+
+        Args:
+            gates (Gate | list[Gate]): The gate or list of gates to be inserted.
+            index (int, optional): The index at which the gate is inserted. Defaults to -1.
+        """
+        if isinstance(gates, Gate):
+            self._insert(gates, index)
+            return
+        for i, gate in enumerate(gates):
+            self._insert(gate, i + index)
+
+    def append(self, circuit: Circuit) -> None:
+        """Append circuit elements at the end of the current circuit.
+
+        Args:
+            circuit (Circuit): The circuit to be appended.
+
+        Raises:
+            QubitOutOfRangeError: If the appended circuit acts on more qubits than the current circuit.
+        """
+        if circuit.nqubits != self.nqubits:
+            raise QubitOutOfRangeError(
+                "the appended circuit contains different number of qubits than the current circuit."
+            )
+
+        for g in circuit.gates:
+            self.add(g)
+
+    def prepend(self, circuit: Circuit) -> None:
+        """Prepend circuit elements to the beginning of the current circuit.
+
+        Args:
+            circuit (Circuit): The circuit to be prepended.
+
+        Raises:
+            QubitOutOfRangeError: If the circuit to be prepended acts on more qubits than the current circuit.
+        """
+        if circuit.nqubits != self.nqubits:
+            raise QubitOutOfRangeError(
+                "the prepended circuit contains different number of qubits than the current circuit."
+            )
+
+        for i, g in enumerate(circuit.gates):
+            self.insert(g, i)
+
+    def __add__(self, other: Circuit | Gate) -> Circuit | NotImplementedError:
+        if not isinstance(other, (Circuit, Gate)):
+            return NotImplementedError(
+                "Addition is only supported between Circuit objects or a Circuit and a Gate objects"
+            )
+        if isinstance(other, Gate):
+            self.add(other)
+        else:
+            self.append(other)
+        return self
+
+    __iadd__ = __add__
+
+    def __radd__(self, other: Circuit | Gate) -> Circuit | NotImplementedError:
+        if not isinstance(other, (Circuit, Gate)):
+            return NotImplementedError(
+                "Addition is only supported between Circuit objects or a Circuit and a Gate objects"
+            )
+        if isinstance(other, Gate):
+            self.insert(other, 0)
+        else:
+            self.prepend(other)
+        return self
+
+    def draw(self, style: CircuitStyle = CircuitStyle(), filepath: str | None = None) -> None:
+        """
+        Render this circuit with Matplotlib and optionally save it to a file.
+
+        The circuit is rendered using the provided style configuration. If ``filepath`` is
+        given, the resulting figure is saved to disk (the output format is inferred
+        from the file extension, e.g. ``.png``, ``.pdf``, ``.svg``).
+
+        Args:
+            style (CircuitStyle): Visual style configuration applied to the plot.
+                If not provided, the default :class:`CircuitStyle` is used.
+            filepath (str | None): Destination file path for the rendered figure.
+                If ``None``, the figure is not saved.
+        """
+        from qilisdk.utils.visualization.circuit_renderers import MatplotlibCircuitRenderer  # noqa: PLC0415
+
+        renderer = MatplotlibCircuitRenderer(self, style=style)
+        renderer.plot()
+        if filepath:
+            renderer.save(filepath)
+
+    @classmethod
+    def random(
+        cls, nqubits: int, single_qubit_gates: set[type[BasicGate]], two_qubit_gates: set[type[BasicGate]], ngates: int
+    ) -> Self:
+        """
+        Generate a random quantum circuit from a given set of gates.
+
+        Args:
+            nqubits (int): The number of qubits in the circuit.
+            single_qubit_gates (set[Gate]): A set of single-qubit gate classes to choose from.
+            two_qubit_gates (set[Gate]): A set of two-qubit gate classes to choose from.
+            ngates (int): The number of gates to include in the circuit.
+
+        Returns:
+            Circuit: A randomly generated quantum circuit.
+
+        Raises:
+            ValueError: If it is not possible to generate a full random circuit with the provided parameters
+
+        """
+
+        # If we only have one gate and one qubit, throw an error
+        if nqubits == 1 and len(single_qubit_gates) == 1:
+            raise ValueError("Cannot generate a full random circuit with only one qubit and one gate.")
+
+        # Make sure we have given gates
+        if len(single_qubit_gates) == 0 and len(two_qubit_gates) == 0:
+            raise ValueError("At least one gate must be provided to generate a random circuit.")
+
+        new_circuit = cls(nqubits)
+        gate_list: list[type[BasicGate]] = list(single_qubit_gates)
+        if nqubits > 1:
+            gate_list.extend(list(two_qubit_gates))
+        prev_gate_type = None
+        prev_qubits = None
+        for _ in range(ngates):
+            gate_class = random.choice(gate_list)
+            gate_nqubits = 1 if gate_class in single_qubit_gates else 2
+            qubits = tuple(random.sample(range(nqubits), gate_nqubits))
+
+            # Avoid adding the same gate on the same qubits consecutively
+            if gate_class == prev_gate_type and qubits == prev_qubits:
+                # If we only have one qubit, pick a different gate
+                if nqubits == 1:
+                    possible_new_gates = [g for g in single_qubit_gates if g != gate_class]
+                    gate_class = random.choice(possible_new_gates)
+
+                # If the gate list does not include all qubits, change the first to be a different qubit
+                if len(qubits) < nqubits:
+                    possible_new_qubits = [q for q in range(nqubits) if q not in qubits]
+                    new_qubit = random.choice(possible_new_qubits)
+                    qubits = (new_qubit, *qubits[1:])
+
+                # Otherwise, flip the order of the qubits
+                else:
+                    qubits = tuple(reversed(qubits))
+
+            # Update previous gate info
+            prev_gate_type = gate_class
+            prev_qubits = qubits
+
+            # Generate random parameters if needed
+            params = {}
+            if gate_class.PARAMETER_NAMES:
+                for param_name in gate_class.PARAMETER_NAMES:
+                    val = random.uniform(-np.pi, np.pi)
+                    params[param_name] = Parameter(
+                        label=param_name + str(val), value=val, domain=Domain.REAL, bounds=(val, val)
+                    )
+
+            # Add the gate to the circuit
+            new_circuit.add(gate_class(*qubits, **params))
+
+        return new_circuit

qilisdk/digital/circuit_transpiler.py

@@ -0,0 +1,46 @@
+# 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 qilisdk.digital import Circuit
+
+from .circuit_transpiler_passes import CircuitTranspilerPass, DecomposeMultiControlledGatesPass
+
+
+class CircuitTranspiler:
+    """Apply an ordered pipeline of circuit transpilation passes.
+
+    The transpiler acts as a thin orchestrator: each pass receives the circuit from the previous
+    pass and must return a brand-new circuit, allowing both structural rewrites and device-specific
+    lowering steps to be chained deterministically. Today the pipeline defaults to a single
+    `DecomposeMultiControlledGatesPass`, but the API is designed so additional passes—e.g. layout,
+    routing, or hardware-aware optimizers—can be composed in future iterations without changing
+    backend code.
+
+    Args:
+        pipeline (list[CircuitTranspilerPass] | None): Sequential list of passes to execute while transpiling.
+    """
+
+    def __init__(self, pipeline: list[CircuitTranspilerPass] | None = None) -> None:
+        self._pipeline = pipeline or [DecomposeMultiControlledGatesPass()]
+
+    def transpile(self, circuit: Circuit) -> Circuit:
+        """Run the configured pass pipeline over the provided circuit.
+
+        Args:
+            circuit (Circuit): Circuit to be rewritten by the transpiler passes.
+        Returns:
+            Circuit: The circuit returned by the last pass in the pipeline.
+        """
+        for transpiler_pass in self._pipeline:
+            circuit = transpiler_pass.run(circuit)
+        return circuit

qilisdk/digital/circuit_transpiler_passes/__init__.py

@@ -0,0 +1,18 @@
+# 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 .circuit_transpiler_pass import CircuitTranspilerPass
+from .decompose_multi_controlled_gates_pass import DecomposeMultiControlledGatesPass
+
+__all__ = ["CircuitTranspilerPass", "DecomposeMultiControlledGatesPass"]

qilisdk/digital/circuit_transpiler_passes/circuit_transpiler_pass.py

@@ -0,0 +1,36 @@
+# 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 abc import ABC, abstractmethod
+
+from qilisdk.digital import Circuit
+
+
+class CircuitTranspilerPass(ABC):
+    """Base class for non-mutating circuit transpiler passes.
+
+    Returns:
+        CircuitTranspilerPass: Instances expose the `run` API required by the transpiler.
+    """
+
+    @abstractmethod
+    def run(self, circuit: Circuit) -> Circuit:
+        """Create a new circuit built from `circuit` without mutating the input.
+
+        Args:
+            circuit (Circuit): Circuit to be transpiled.
+        Returns:
+            Circuit: Newly transpiled circuit.
+        """
+        ...

qilisdk/digital/circuit_transpiler_passes/decompose_multi_controlled_gates_pass.py

@@ -0,0 +1,220 @@
+# 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.
+
+import math
+from typing import List, TypeGuard
+
+from qilisdk.digital import RX, RY, RZ, U1, U2, U3, Circuit, Gate, H, I, S, T, X, Y, Z
+from qilisdk.digital.gates import BasicGate, Controlled
+
+from .circuit_transpiler_pass import CircuitTranspilerPass
+from .numeric_helpers import (
+    _unitary_sqrt_2x2,
+    _zyz_from_unitary,
+)
+
+
+def _is_controlled_basic(g: Gate) -> TypeGuard[Controlled[BasicGate]]:
+    return isinstance(g, Controlled)
+
+
+class DecomposeMultiControlledGatesPass(CircuitTranspilerPass):
+    """Decompose multi-controlled (k >= 2) single-qubit gates.
+
+    The construction follows Lemma 7.5 from Barenco et al., *Elementary Gates for Quantum Computation*,
+    recursively replacing a k-controlled unitary with five layers of (k-1)-controlled operations built
+    from sqrt(U), its adjoint, and multi-controlled Pauli-X gates.
+    """
+
+    def run(self, circuit: Circuit) -> Circuit:
+        """Rewrite the circuit while decomposing multi-controlled gates.
+
+        Args:
+            circuit (Circuit): Circuit whose gates should be rewritten.
+        Returns:
+            Circuit: Newly built circuit containing only supported primitives.
+        """
+        out = Circuit(circuit.nqubits)
+        for g in circuit.gates:
+            for h in self._rewrite_gate(g):
+                out.add(h)
+
+        return out
+
+    def _rewrite_gate(self, gate: Gate) -> List[Gate]:  # noqa: PLR6301
+        """Expand unsupported gates into equivalent elementary gates.
+
+        Args:
+            gate (Gate): Candidate gate potentially containing multiple controls.
+        Returns:
+            list[Gate]: Sequence of equivalent gates that rely on supported primitives.
+        """
+        # --- Multi-controlled gates ---
+        if _is_controlled_basic(gate):
+            base: BasicGate = gate.basic_gate
+            if base.nqubits != 1:
+                raise NotImplementedError("Controlled version of multi-qubit gates is not supported.")
+
+            return _decompose(gate)
+
+        # Everything else is untouched.
+        return [gate]
+
+
+def _decompose(gate: Controlled) -> List[Gate]:
+    """Recursively decompose a multi-controlled single-qubit gate.
+
+    Args:
+        gate (Controlled): Controlled gate whose target operation is single-qubit.
+    Returns:
+        list[Gate]: Gate sequence computing the same unitary as `gate`.
+    """
+    if len(gate.control_qubits) == 1:
+        return [gate]
+
+    c_last = gate.control_qubits[-1]
+    rest = gate.control_qubits[:-1]
+
+    v = _sqrt_of(gate.basic_gate)
+    v_adjoint = _adjoint_of(v)
+
+    seq: List[Gate] = []
+    seq += _decompose(Controlled(c_last, basic_gate=v))
+    seq += _decompose(X(c_last).controlled(*rest))
+    seq += _decompose(Controlled(c_last, basic_gate=v_adjoint))
+    seq += _decompose(X(c_last).controlled(*rest))
+    seq += _decompose(Controlled(*rest, basic_gate=v))
+
+    return seq
+
+
+def _sqrt_of(gate: BasicGate) -> BasicGate:
+    """Return a gate V whose square equals the provided gate.
+
+    Args:
+        gate (BasicGate): Single-qubit gate to compute the principal square root for.
+    Returns:
+        BasicGate: New primitive V that satisfies V · V ≡ gate.
+    """
+    q = gate.qubits[0]
+
+    # Identity: sqrt(I) = I
+    if isinstance(gate, I):
+        return I(q)
+
+    # Direct parametric rotations.
+    if isinstance(gate, RZ):
+        return RZ(q, phi=gate.phi / 2.0)
+    if isinstance(gate, RX):
+        return RX(q, theta=gate.theta / 2.0)
+    if isinstance(gate, RY):
+        return RY(q, theta=gate.theta / 2.0)
+
+    # Pauli gates via half-angle rotations.
+    if isinstance(gate, Z):
+        return RZ(q, phi=math.pi / 2.0)
+    if isinstance(gate, X):
+        return RX(q, theta=math.pi / 2.0)
+    if isinstance(gate, Y):
+        return RY(q, theta=math.pi / 2.0)
+
+    # Phase gate U1(phi) = diag(1, e^{iphi}), sqrt is U1(phi/2).
+    if isinstance(gate, U1):
+        return RZ(q, phi=gate.phi / 2.0)
+
+    # S and T: phase gates with known relation to RZ
+    # S = RZ(pi/2) ⇒ sqrt(S) = RZ(pi/4) ≡ T
+    if isinstance(gate, S):
+        return T(q)
+
+    # T = RZ(pi/4) ⇒ sqrt(T) = RZ(pi/8)
+    if isinstance(gate, T):
+        return RZ(q, phi=math.pi / 8.0)
+
+    # Build the 2x2 unitary matrix for gate
+    if isinstance(gate, BasicGate) and gate.nqubits == 1:
+        U = gate.matrix
+    else:
+        raise NotImplementedError(f"_sqrt_1q_gate_as_basis only supports 1-qubit gates; got {type(gate).__name__}")
+
+    # Compute a matrix square root V such that V @ V ≈ U.
+    v_sqrt = _unitary_sqrt_2x2(U)
+
+    # Express V as a U3 on the same qubit. This introduces a new gate in U3 form
+    # for the *square root*, but leaves the original g untouched.
+    th, ph, lam = _zyz_from_unitary(v_sqrt)
+    return U3(q, theta=th, phi=ph, gamma=lam)
+
+
+def _adjoint_of(gate: BasicGate) -> BasicGate:
+    """Return the single-qubit adjoint (inverse) of a gate.
+
+    Args:
+        gate (BasicGate): Gate whose inverse should be produced.
+    Returns:
+        BasicGate: Gate that when composed with `gate` yields the identity.
+    """
+    q = gate.qubits[0]
+
+    # Identity: self-adjoint.
+    if isinstance(gate, I):
+        return I(q)
+
+    # Pauli & Hadamard: self-adjoint.
+    if isinstance(gate, X):
+        return X(q)
+    if isinstance(gate, Y):
+        return Y(q)
+    if isinstance(gate, Z):
+        return Z(q)
+    if isinstance(gate, H):
+        return H(q)
+
+    if isinstance(gate, RX):
+        return RX(q, theta=-gate.theta)
+    if isinstance(gate, RY):
+        return RY(q, theta=-gate.theta)
+    if isinstance(gate, RZ):
+        return RZ(q, phi=-gate.phi)
+
+    if isinstance(gate, U1):
+        # U1(gamma)† = U1(-gamma)
+        return RZ(q, phi=-gate.phi)
+    if isinstance(gate, U2):
+        # U2(phi, gamma)† = U3(pi/2, phi, gamma)† = U3(-pi/2, -phi, -gamma)
+        return U3(q, theta=-math.pi / 2.0, phi=-gate.gamma, gamma=-gate.phi)
+    if isinstance(gate, U3):
+        # U3(theta, phi, gamma)† = U3(-theta, -gamma, -phi)
+        return U3(q, theta=-gate.theta, phi=-gate.gamma, gamma=-gate.phi)
+
+    # S, T: phase gates about Z.
+    # S = RZ(pi/2)  ⇒ S† = RZ(-pi/2)
+    if isinstance(gate, S):
+        return RZ(q, phi=-math.pi / 2.0)
+
+    # T = RZ(pi/4)  ⇒ T† = RZ(-pi/4)
+    if isinstance(gate, T):
+        return RZ(q, phi=-math.pi / 4.0)
+
+    # ---------- Generic 1-qubit unitary via matrix adjoint ----------
+
+    if isinstance(gate, BasicGate) and gate.nqubits == 1:
+        U = gate.matrix
+    else:
+        raise NotImplementedError(f"_adjoint_1q only supports 1-qubit gates; got {type(gate).__name__}")
+
+    # Take the matrix adjoint U† and convert to ZYZ → U3.
+    u_dagger = U.conj().T
+    theta, phi, gamma = _zyz_from_unitary(u_dagger)
+    return U3(q, theta=theta, phi=phi, gamma=gamma)