Add a symbolize transformer

Symbolizes single qubit gates by tags.

Author: babacry

cirq-core/cirq/__init__.py

@@ -393,6 +393,7 @@
     single_qubit_matrix_to_phxz as single_qubit_matrix_to_phxz,
     single_qubit_op_to_framed_phase_form as single_qubit_op_to_framed_phase_form,
     stratified_circuit as stratified_circuit,
+    symbolize_single_qubit_gates_by_indexed_tags as symbolize_single_qubit_gates_by_indexed_tags,
     synchronize_terminal_measurements as synchronize_terminal_measurements,
     TRANSFORMER as TRANSFORMER,
     TransformerContext as TransformerContext,

cirq-core/cirq/transformers/__init__.py

@@ -133,6 +133,10 @@
     unroll_circuit_op_greedy_frontier as unroll_circuit_op_greedy_frontier,
 )
 
+from cirq.transformers.symbolize import (
+    symbolize_single_qubit_gates_by_indexed_tags as symbolize_single_qubit_gates_by_indexed_tags,
+)
+
 from cirq.transformers.gauge_compiling import (
     CZGaugeTransformer as CZGaugeTransformer,
     ConstantGauge as ConstantGauge,

cirq-core/cirq/transformers/symbolize.py

@@ -0,0 +1,89 @@
+# Copyright 2025 The Cirq Developers
+#
+# 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 re
+from typing import Hashable, Optional, TYPE_CHECKING
+
+import sympy
+
+from cirq import ops
+from cirq.transformers import transformer_api, transformer_primitives
+
+if TYPE_CHECKING:
+    import cirq
+
+
+@transformer_api.transformer
+def symbolize_single_qubit_gates_by_indexed_tags(
+    circuit: 'cirq.AbstractCircuit',
+    *,
+    context: Optional['cirq.TransformerContext'] = None,
+    tag_prefix: Optional[str] = "TO-PHXZ",
+) -> 'cirq.Circuit':
+    """Symbolizes single qubit operations by indexed tags prefixed by tag_prefix.
+
+    Example:
+        >>> q0, q1 = cirq.LineQubit.range(2)
+        >>> c = cirq.Circuit(\
+                    cirq.X(q0).with_tags("phxz_0"),\
+                    cirq.CZ(q0,q1),\
+                    cirq.Y(q0).with_tags("phxz_1"),\
+                    cirq.X(q0))
+        >>> print(c)
+        0: ───X[phxz_0]───@───Y[phxz_1]───X───
+                          │
+        1: ───────────────@───────────────────
+        >>> new_circuit = cirq.symbolize_single_qubit_gates_by_indexed_tags(\
+                c, tag_prefix="phxz")
+        >>> print(new_circuit)
+        0: ───PhXZ(a=a0,x=x0,z=z0)───@───PhXZ(a=a1,x=x1,z=z1)───X───
+                                     │
+        1: ──────────────────────────@──────────────────────────────
+
+    Args:
+        circuit: Input circuit to apply the transformations on. The input circuit is not mutated.
+        context: `cirq.TransformerContext` storing common configurable options for transformers.
+        tag_prefix: The prefix of the tag.
+
+    Returns:
+        Copy of the transformed input circuit.
+    """
+
+    def _map_func(op: 'cirq.Operation', _):
+        """Maps an op with tag `{tag_prefix}_i` to a symbolzied `PhasedXZGate(xi,zi,ai)`."""
+        tags: set[Hashable] = set(op.tags)
+        tag_id: None | int = None
+        for tag in tags:
+            if re.fullmatch(f"{tag_prefix}_\\d+", str(tag)):
+                if tag_id is None:
+                    tag_id = int(str(tag).rsplit("_", maxsplit=-1)[-1])
+                else:
+                    raise ValueError(f"Multiple tags are prefixed with {tag_prefix}.")
+        if tag_id is None:
+            return op
+        tags.remove(f"{tag_prefix}_{tag_id}")
+        phxz_params = {
+            "x_exponent": sympy.Symbol(f"x{tag_id}"),
+            "z_exponent": sympy.Symbol(f"z{tag_id}"),
+            "axis_phase_exponent": sympy.Symbol(f"a{tag_id}"),
+        }
+
+        return ops.PhasedXZGate(**phxz_params).on(*op.qubits).with_tags(*tags)
+
+    return transformer_primitives.map_operations(
+        circuit.freeze(),
+        _map_func,
+        deep=context.deep if context else False,
+        tags_to_ignore=context.tags_to_ignore if context else [],
+    ).unfreeze(copy=False)

cirq-core/cirq/transformers/symbolize_test.py

@@ -0,0 +1,52 @@
+# Copyright 2025 The Cirq Developers
+#
+# 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 pytest
+import sympy
+
+import cirq
+
+
+def test_symbolize_single_qubit_gates_by_indexed_tags_success():
+    q = cirq.NamedQubit("a")
+    input_circuit = cirq.Circuit(
+        cirq.X(q).with_tags("TO-PHXZ_1"),
+        cirq.Y(q).with_tags("tag1"),
+        cirq.Z(q).with_tags("TO-PHXZ_0"),
+    )
+    output_circuit = cirq.symbolize_single_qubit_gates_by_indexed_tags(input_circuit)
+    cirq.testing.assert_same_circuits(
+        output_circuit,
+        cirq.Circuit(
+            cirq.PhasedXZGate(
+                x_exponent=sympy.Symbol("x1"),
+                z_exponent=sympy.Symbol("z1"),
+                axis_phase_exponent=sympy.Symbol("a1"),
+            ).on(q),
+            cirq.Y(q).with_tags("tag1"),
+            cirq.PhasedXZGate(
+                x_exponent=sympy.Symbol("x0"),
+                z_exponent=sympy.Symbol("z0"),
+                axis_phase_exponent=sympy.Symbol("a0"),
+            ).on(q),
+        ),
+    )
+
+
+def test_symbolize_single_qubit_gates_by_indexed_tags_multiple_tags():
+    q = cirq.NamedQubit("a")
+    input_circuit = cirq.Circuit(cirq.X(q).with_tags("TO-PHXZ_0", "TO-PHXZ_2"))
+
+    with pytest.raises(ValueError, match="Multiple tags are prefixed with TO-PHXZ."):
+        cirq.symbolize_single_qubit_gates_by_indexed_tags(input_circuit)