[Rotation Synthesis] add Tx/Tz/Tx*/Tz* representation and methods to export to Cirq and Quirk (#1751)

This PR adds
1. a method to represent an $SU(2)$ matrix as a string of $Tx,
Tx^\dagger, Tz, Tz^\dagger$
2. a method that exports the representation as a cirq circuit
3. a method that exports the representatoin as quirk link

Author: NoureldinYosri

qualtran/rotation_synthesis/README.md

@@ -13,6 +13,7 @@
 #  limitations under the License.
 
 from qualtran.rotation_synthesis.math_config import NumpyConfig, with_dps
+from qualtran.rotation_synthesis.matrix import to_cirq, to_quirk, to_sequence
 from qualtran.rotation_synthesis.protocols import (
     diagonal_unitary_approx,
     fallback_protocol,

qualtran/rotation_synthesis/__init__.py

@@ -18,10 +18,12 @@
 from typing import Optional, Sequence, Union
 
 import attrs
+import cirq
 import numpy as np
 
 import qualtran.rotation_synthesis._typing as rst
 import qualtran.rotation_synthesis.math_config as mc
+import qualtran.rotation_synthesis.matrix.clifford_t_repr as ctr
 import qualtran.rotation_synthesis.rings as rings
 from qualtran.rotation_synthesis.matrix import su2_ct
 from qualtran.rotation_synthesis.rings import zsqrt2
@@ -111,6 +113,41 @@ def from_sequence(cls, seq: Sequence[str], twirl: bool = False) -> UnitaryChanne
         n = sum(g.startswith("T") for g in seq)
         return UnitaryChannel(u.matrix[0, 0], u.matrix[1, 0], n, twirl)
 
+    def to_cirq(self, fmt: str = "xz", qs: Optional[Sequence[cirq.Qid]] = None) -> cirq.Circuit:
+        """Retruns a representation of the channel as a cirq circuit.
+
+        Args:
+            fmt: The gates to use (see the documentation of to_sequence).
+            qs: Optional qubits to operate on.
+        Returns:
+            A cirq circuit
+        Raises:
+            ValueError: If twirl=True
+        """
+        if self.twirl:
+            raise ValueError("to_cirq is not supported when twirl=True")
+        if qs:
+            (q,) = qs
+        else:
+            q = cirq.q(0)
+        return cirq.Circuit(ctr.to_cirq(self.to_matrix(), fmt, q))
+
+    def to_quirk(self, fmt: str = "xz") -> str:
+        """Retruns a quirk link representing the channel operation.
+
+        Args:
+            fmt: The gates to use (see the documentation of to_sequence).
+        Returns:
+            A quirk link.
+        Raises:
+            ValueError: If twirl=True
+        """
+        if self.twirl:
+            raise ValueError("to_quirk is not supported when twirl=True")
+        gates = ctr.to_quirk(self.to_matrix(), fmt)
+        cols = '[' + ','.join(f'[{g}]' for g in gates) + ']'
+        return "https://algassert.com/quirk#circuit={\"cols\":%s}" % cols
+
     def diamond_norm_distance_to_unitary(
         self, unitary: np.ndarray, config: mc.MathConfig
     ) -> rst.Real:
@@ -212,6 +249,71 @@ def diamond_norm_distance_to_rz(self, theta: rst.Real, config: mc.MathConfig) ->
             theta - self.failure_angle(config), config
         )
 
+    def to_cirq(self, fmt: str = "xz", qs: Optional[Sequence[cirq.Qid]] = None) -> cirq.Circuit:
+        """Retruns a representation of the channel as a cirq circuit.
+
+        Args:
+            fmt: The gates to use (see the documentation of to_sequence).
+            qs: Optional qubits to operate on.
+        Returns:
+            A cirq circuit
+        Raises:
+            ValueError: If the correction channel is not a UnitaryChannel.
+        """
+        if qs:
+            q0, q1 = qs
+        else:
+            q0, q1 = cirq.LineQubit.range(2)
+        correction = self.correction
+        if not isinstance(correction, UnitaryChannel):
+            raise ValueError('to_cirq does not support a non unitary correction')
+        return cirq.Circuit(
+            cirq.CNOT(q0, q1),
+            cirq.CircuitOperation(self.rotation.to_cirq(fmt, (q0,)).freeze()),
+            cirq.CNOT(q0, q1),
+            cirq.measure(q1, key='m'),
+            cirq.CircuitOperation(correction.to_cirq(fmt, (q0,)).freeze()).with_classical_controls(
+                'm'
+            ),
+        )
+
+    def to_quirk(self, fmt: str = "xz") -> str:
+        """Retruns a quirk link representing the channel operation.
+
+        Args:
+            fmt: The gates to use (see the documentation of to_sequence).
+        Returns:
+            A quirk link.
+        """
+        correction = self.correction
+        if not isinstance(correction, UnitaryChannel):
+            raise ValueError(f"to_quirk is not supported for correction of type {type(correction)}")
+        rot = ctr.to_quirk(self.rotation.to_matrix(), fmt)
+        cor = ctr.to_quirk(correction.to_matrix(), fmt)
+        first_row = []
+        second_row = []
+        # CNOT
+        first_row.append("\"•\"")
+        second_row.append("\"X\"")
+        # rotation
+        first_row.extend(rot)
+        second_row.extend("1" for _ in rot)
+        # CNOT
+        first_row.append("\"•\"")
+        second_row.append("\"X\"")
+        # measure
+        first_row.append("1")
+        second_row.append("\"Measure\"")
+        # correction
+        first_row.extend(cor)
+        second_row.extend("\"•\"" for _ in cor)
+        cols = (
+            '['
+            + ','.join(f'[{g1},{g2}]' for g1, g2 in zip(first_row, second_row, strict=True))
+            + ']'
+        )
+        return "https://algassert.com/quirk#circuit={\"cols\":%s}" % cols
+
 
 @attrs.frozen
 class ProbabilisticChannel(Channel):

qualtran/rotation_synthesis/channels/channel.py

@@ -12,11 +12,13 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
+import cirq
 import numpy as np
 import pytest
 
 import qualtran.rotation_synthesis.channels as ch
 import qualtran.rotation_synthesis.math_config as mc
+import qualtran.rotation_synthesis.matrix.clifford_t_repr as ctr
 import qualtran.rotation_synthesis.matrix.su2_ct as su2_ct
 
 
@@ -310,3 +312,38 @@ def test_diamond_distance_for_mixed_fallback(
     np.testing.assert_allclose(
         float(c.diamond_norm_distance_to_rz(theta, mc.NumpyConfig)), distance, atol=3e-5
     )
+
+
+@pytest.mark.parametrize(
+    "gates",
+    [["I", "Z", "I", "Tz"], ["I", "S", "Tz"], ["I", "S", "Tz"], ["I", "Z", "S", "Tz"], ["I", "S"]],
+)
+@pytest.mark.parametrize("fmt", ["xz", "xyz"])
+def test_unitary_to_cirq(gates, fmt):
+    u = ch.UnitaryChannel.from_sequence(gates)
+    assert u.to_cirq(fmt) == cirq.Circuit(ctr.to_cirq(u.to_matrix(), fmt))
+
+
+@pytest.mark.parametrize(
+    "gates1",
+    [["I", "Z", "I", "Tz"], ["I", "S", "Tz"], ["I", "S", "Tz"], ["I", "Z", "S", "Tz"], ["I", "S"]],
+)
+@pytest.mark.parametrize(
+    "gates2",
+    [["I", "Z", "I", "Tz"], ["I", "S", "Tz"], ["I", "S", "Tz"], ["I", "Z", "S", "Tz"], ["I", "S"]],
+)
+@pytest.mark.parametrize("fmt", ["xz", "xyz"])
+def test_fallback_to_cirq(gates1, gates2, fmt):
+    c = ch.ProjectiveChannel(
+        ch.UnitaryChannel.from_sequence(gates1), ch.UnitaryChannel.from_sequence(gates2)
+    )
+    q0, q1 = cirq.LineQubit.range(2)
+    assert c.to_cirq(fmt) == cirq.Circuit(
+        cirq.CNOT(q0, q1),
+        cirq.CircuitOperation(cirq.FrozenCircuit(ctr.to_cirq(c.rotation.to_matrix(), fmt, q0))),
+        cirq.CNOT(q0, q1),
+        cirq.measure(q1, key='m'),
+        cirq.CircuitOperation(
+            cirq.FrozenCircuit(ctr.to_cirq(c.correction.to_matrix(), fmt, q0))  # type: ignore[attr-defined]
+        ).with_classical_controls('m'),
+    )

qualtran/rotation_synthesis/channels/channel_test.py

@@ -14,8 +14,10 @@
 
 r"""A submodule for compiling $\mathbb{Z}[e^{i \pi/4}]$ matrices to Clifford+T as well as generating them."""
 
+from qualtran.rotation_synthesis.matrix.clifford_t_repr import to_cirq, to_quirk, to_sequence
 from qualtran.rotation_synthesis.matrix.generation import (
+    generate_cliffords,
     generate_rotations,
     generate_rotations_iter,
 )
-from qualtran.rotation_synthesis.matrix.su2_ct import generate_cliffords, SU2CliffordT
+from qualtran.rotation_synthesis.matrix.su2_ct import SU2CliffordT

qualtran/rotation_synthesis/matrix/__init__.py

@@ -0,0 +1,157 @@
+#  Copyright 2025 Google LLC
+#
+#  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
+#
+#      https://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 cast, Mapping, Optional
+
+import cirq
+
+import qualtran.rotation_synthesis.matrix.generation as ctg
+import qualtran.rotation_synthesis.matrix.su2_ct as su2_ct
+import qualtran.rotation_synthesis.rings.zsqrt2 as zsqrt2
+
+_TWO = zsqrt2.ZSqrt2(2)
+
+
+def clifford(matrix: su2_ct.SU2CliffordT) -> tuple[str, ...]:
+    assert matrix.det() == 2
+    cliffords = ctg.generate_cliffords()
+    if matrix in cliffords:
+        return cliffords[matrix]
+    return ("Z", "X", "Z", "X") + cliffords[-matrix]
+
+
+def _xyz_sequence(matrix: su2_ct.SU2CliffordT) -> tuple[str, ...]:
+    seq = []
+    while matrix.det() > _TWO:
+        t = su2_ct._key_map()[matrix._key]
+        nxt = (su2_ct.GATE_MAP[t].adjoint() @ matrix).scale_down()
+        assert nxt is not None
+        assert nxt.det() < matrix.det()
+        seq.append(t)
+        matrix = nxt
+    return clifford(matrix) + tuple(seq[::-1])
+
+
+_T_list = [
+    ('Tz', su2_ct.Tz),
+    ('Tx', su2_ct.Tx),
+    ('Tz*', su2_ct.Tz.adjoint()),
+    ('Tx*', su2_ct.Tx.adjoint()),
+]
+
+
+def _xz_sequence(matrix: su2_ct.SU2CliffordT, use_hs: bool = True) -> Optional[tuple[str, ...]]:
+    if matrix.det() == 2:
+        return clifford(matrix)
+    cliffords = [su2_ct.ISqrt2]
+    if use_hs:
+        cliffords.append(su2_ct.HSqrt2)
+        cliffords.append(su2_ct.HSqrt2 @ su2_ct.SSqrt2)
+    candidates = []
+    for name, t in _T_list:
+        for c in cliffords:
+            new = c.adjoint() @ matrix
+            new = t.adjoint() @ new
+            new = new.scale_down()
+            if new is None or not new.is_valid():
+                continue
+            seq = _xz_sequence(new, False)
+            if seq is None:
+                continue
+            gates = cast(tuple[str, ...], c.gates)
+            candidates.append(seq + (name,) + gates)
+    if not candidates:
+        return None
+    return min(candidates, key=len)
+
+
+def to_sequence(matrix: su2_ct.SU2CliffordT, fmt: str = 'xyz') -> tuple[str, ...]:
+    r"""Returns a sequence of Clifford+T that produces the given matrix.
+
+    Args:
+        matrix: The matrix to represent.
+        fmt: A string from the set {'xz', 'xyz'} representing the allowed T gates where
+            - 'xyz' uses Tx, Ty, Tz gates.
+            - 'xz' uses $Tx, Tz, Tx^\dagger, Tz^\dagger$
+    Returns:
+        A tuple of strings representing the gates.
+    Raises:
+        ValueError: If `fmt` is not supported.
+    """
+    if fmt == 'xyz':
+        return _xyz_sequence(matrix)
+    if fmt == 'xz':
+        return cast(tuple[str, ...], _xz_sequence(matrix))
+    raise ValueError(f'{type=} is not supported')
+
+
+_CIRQ_GATE_MAP: Mapping[str, cirq.Gate] = {
+    "I": cirq.I,
+    "H": cirq.H,
+    "S": cirq.S,
+    "X": cirq.X,
+    "Y": cirq.Y,
+    "Z": cirq.Z,
+    "Tx": cirq.rx(math.pi / 4),
+    "Ty": cirq.ry(math.pi / 4),
+    "Tz": cirq.rz(math.pi / 4),
+    "Tx*": cirq.rx(-math.pi / 4),
+    "Ty*": cirq.ry(-math.pi / 4),
+    "Tz*": cirq.rz(-math.pi / 4),
+}
+
+
+def _to_quirk_name(name: str) -> str:
+    if name == "I":
+        return "1"
+    if name in ("X", "Y", "Z", "H"):
+        return "\"" + name + "\""
+    if name == "S":
+        return "\"Z^½\""
+    if name == "S*":
+        return "\"Z^-½\""
+    if name.startswith("T"):
+        if name.endswith("*"):
+            return "\"" + name[1].upper() + "^-¼" + "\""
+        return "\"" + name[1].upper() + "^¼" + "\""
+    raise ValueError(f"{name=} is not supported")
+
+
+def to_cirq(
+    matrix: su2_ct.SU2CliffordT, fmt: str, q: Optional[cirq.Qid] = None
+) -> tuple[cirq.Operation]:
+    """Retruns a representation of the matrix as a sequence of Cirq operations.
+
+    Args:
+        matrix: The matrix to represent.
+        fmt: The gates to use (see the documentation of to_sequence).
+        q: The qubit to use.
+    Returns:
+        A tuple of Cirq operations.
+    """
+    q = q or cirq.q(0)
+    return tuple(_CIRQ_GATE_MAP[g](q) for g in to_sequence(matrix, fmt))
+
+
+def to_quirk(matrix: su2_ct.SU2CliffordT, fmt: str) -> tuple[str, ...]:
+    """Retruns a representation of the matrix as a sequence of quirk symbols.
+
+    Args:
+        matrix: The matrix to represent.
+        fmt: The gates to use (see the documentation of to_sequence).
+    Returns:
+        A tuple quirk symbols.
+    """
+    return tuple(_to_quirk_name(name) for name in to_sequence(matrix, fmt))