Native Support for U3 Gate

[ACE07-Sev]

Is your feature request related to a use case or problem? Please explain

It is more related to a use-case where users may want to use a U3 gate, as opposed to creating an equivalent gate to it themselves which adds time to development for each individual. U3 is a well-known gate, and would be nice to have it in cirq natively.

Describe the solution you would prefer

I would personally suggest adding a class for U3 gate like any other gate to add native support for it.

How urgent is this for you? Is it blocking important work?

No, not urgent.

P0 – this should land no later than a week

P1 – I need this no later than the next release

P2 – we should do it in the next couple of quarters

P3 – I'm not really blocked by it; it's an idea I'm proposing based on principle
P3 I suppose, maybe P2.

Describe alternatives/workarounds you've considered

During 4/9/2025 Cirq Cynq meeting, an approach was proposed to make a helper function that takes U3 parameters (the three angles) and then returns a PhasedXZGate that is equivalent to the U3 gate.

Provide additional information or context (e.g., screenshots)

[ACE07-Sev]

@mhucka Greetings sir. I made the issue as requested for further discussion.

[daxfohl]

#5959 references the existing QasmUGate, and highlights the difference in global phase with qiskit's U gate, and the effect on controlled variants. Could perhaps add a bool parameter to the constructor that forces the global phase to be consistent with qiskit's U gate? Then update unitary to add global phase, decomposition to add a corresponding global phase gate, etc., if that parameter is true. This would presumably resolve #5959 as well.

[ACE07-Sev]

Sounds good. I'll make a PR asap for it and will check for 5959.

[ACE07-Sev]

I made this draft as one way to do it via QasmUGate.

import numpy as np
from cirq import ops, linalg, protocols, value
from typing import Tuple, Dict
from cirq.circuits.qasm_output import QasmUGate


class QasmU3Gate(QasmUGate):
    def __init__(self, theta, phi, lmda) -> None:
        """A QASM gate representing any single qubit unitary with a series of
        three rotations, Z, Y, and Z. This gate is different from QasmUGate
        by a global phase and matches the U3 gate.

        The angles are in radians.

        Args:
            theta: Radians to rotate about Y (applied second).
            phi: Radians to rotate about Z (applied last).
            lmda: Radians to rotate about Z (applied first).
        """
        super().__init__(theta, phi, lmda)

    @staticmethod
    def from_matrix(mat: np.ndarray) -> 'QasmU3Gate':
        pre_phase, rotation, post_phase = linalg.deconstruct_single_qubit_matrix_into_angles(mat)
        return QasmU3Gate(rotation / np.pi, post_phase / np.pi, pre_phase / np.pi)

    def _calculate_global_phase(self):
        import cirq # local import to avoid circular dependency

        mat = cirq.unitary(QasmUGate(self.theta, self.phi, self.lmda))
        det_arg = np.linalg.det(mat)
        det_arg = np.arctan2(det_arg.imag, det_arg.real)
        phase = (det_arg - self.phi * np.pi - self.lmda * np.pi) / 2
        return phase

    def _decompose_(self, qubits):
        q = qubits[0]
        return [
            QasmUGate(self.theta, self.phi, self.lmda).on(q),
            ops.GlobalPhaseGate(
                np.exp(1j * -self._calculate_global_phase())
            ).on()
        ]

Tester

from numpy.testing import assert_almost_equal
from qiskit import QuantumCircuit
from qiskit.quantum_info import Operator
from qiskit.circuit.library import U3Gate
import cirq

theta = 0.2
phi = 0.3
lam = 0.4

qc = QuantumCircuit(1)
qc.append(U3Gate(0.2, 0.3, 0.4), [0])
u = Operator(qc).data

qr = cirq.LineQubit.range(1)
cirq_qc = cirq.Circuit(
    QasmU3Gate(0.2/np.pi, 0.3/np.pi, 0.4/np.pi).on(qr[0])
)
u_check = cirq.unitary(cirq_qc)

assert_almost_equal(u, u_check) # This should pass

[daxfohl]

Cool, yeah if you could, go ahead and update _parser.py to use the correct variant too.

Also IIUC this means the existing QasmUGate._qasm_ is incorrect? It should be u instead of u3, and your new gate should be the one that emits u3? But I guess if QasmArgs.version == '2.0' is specified, your gate should return u and the existing gate should return u plus a global phase? (I'm just getting up to speed on the differences).

Going back to _parser.py, IIUC ideally it should parse u differently for different versions of qasm. I see where the version is parsed in p_format, but I guess it'll need to be stored to a member variable in order to use when it encounters a u gate.