cirq-core 1.7.0.dev20250825174419__py3-none-any.whl → 1.7.0.dev20251203004401__py3-none-any.whl

cirq/transformers/gauge_compiling/idle_moments_gauge.py

@@ -0,0 +1,225 @@
+# 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.
+from __future__ import annotations
+
+import functools
+from collections.abc import Hashable, Iterator, Sequence
+from typing import TYPE_CHECKING
+
+import attrs
+import numpy as np
+
+import cirq.circuits as circuits
+import cirq.ops as ops
+import cirq.protocols as protocols
+import cirq.transformers.transformer_api as transformer_api
+
+if TYPE_CHECKING:
+    import cirq
+
+_PAULIS: tuple[cirq.Gate, ...] = (ops.I, ops.X, ops.Y, ops.Z)  # type: ignore[has-type]
+_CLIFFORDS = tuple(ops.SingleQubitCliffordGate.all_single_qubit_cliffords)
+_INV_CLIFFORDS = tuple(c**-1 for c in ops.SingleQubitCliffordGate.all_single_qubit_cliffords)
+
+_NAME_TO_GATES = {'pauli': _PAULIS, 'clifford': _CLIFFORDS, 'inv_clifford': _INV_CLIFFORDS}
+
+
+def _gauges_arg_converter(gauges: str | Sequence[cirq.Gate] = 'clifford') -> tuple[cirq.Gate, ...]:
+    if isinstance(gauges, str):
+        if gauges not in _NAME_TO_GATES:
+            valid_names = tuple(_NAME_TO_GATES.keys())
+            raise ValueError(f"{gauges} is not a valid gauge name, valid names are {valid_names}")
+        return _NAME_TO_GATES[gauges]
+    return tuple(gauges)
+
+
+def _repr_fn(gauges: tuple[cirq.Gate, ...]) -> str:
+    if gauges is _PAULIS or gauges == _PAULIS:
+        return '"pauli"'
+    if gauges is _CLIFFORDS or gauges == _CLIFFORDS:
+        return '"clifford"'
+    if gauges is _INV_CLIFFORDS or gauges == _INV_CLIFFORDS:
+        return '"inv_clifford"'
+    return repr(gauges)
+
+
+def _get_structure(
+    active: list[tuple[int, bool]],
+    min_length: int,
+    n: int,
+    gauge_beginning: bool,
+    gauge_ending: bool,
+) -> Iterator[tuple[int, int]]:
+    if gauge_beginning:
+        stop, is_mergable = active[0]
+        if min_length <= stop:
+            if is_mergable:
+                yield (0, stop)
+            else:
+                yield (0, stop - 1)
+
+    for i in range(len(active) - 1):
+        left_pos, left_is_mergable = active[i]
+        right_pos, right_is_mergable = active[i + 1]
+        if right_pos - left_pos - 1 >= min_length:
+            yield (left_pos + 1 - left_is_mergable, right_pos - 1 + right_is_mergable)
+
+    if gauge_ending:
+        stop, is_mergable = active[-1]
+        if min_length <= n - stop - 1:
+            if is_mergable:
+                yield (stop, n - 1)
+            else:
+                yield (stop + 1, n - 1)
+
+
+def _merge(g1: cirq.Gate, g2: cirq.Gate, q: cirq.Qid, tags: Sequence[Hashable]) -> cirq.Operation:
+    u1 = protocols.unitary(g1)
+    u2 = protocols.unitary(g2)
+    return ops.PhasedXZGate.from_matrix(u2 @ u1)(q).with_tags(*tags)
+
+
+@transformer_api.transformer
+@attrs.frozen
+class IdleMomentsGauge:
+    r"""A transformer that inserts identity-preserving "gauge" gates around idle qubit moments.
+
+    This transformer identifies sequences of consecutive idle moments on a single qubit
+    that meet a `min_length` threshold. For each such sequence, it inserts a randomly
+    selected gate `G` from `gauges` at the start of the idle period and its inverse `G^-1`
+    at the end. This ensures the logical circuit behavior remains unchanged ($G \cdot G^{-1} = I$).
+
+    The primary goal is to introduce specific structure into idle periods, which is
+    useful for experiments.
+
+    Attributes:
+        min_length: Minimum number of consecutive idle moments for a gauge to be applied (>= 1).
+
+        gauges: A sequence of `cirq.Gate` objects to randomly select from.
+            Can be a custom tuple or a string alias:
+            - `"pauli"`: Uses single-qubit Pauli gates (I, X, Y, Z).
+            - `"clifford"`: Uses all 24 single-qubit Clifford gates.
+
+        gauge_beginning: If `True`, applies a gauge to idle moments at the circuit's start,
+            before any other qubit operation. Defaults to `False`.
+
+        gauge_ending: If `True`, applies a gauge to idle moments at the circuit's end,
+            after the last qubit operation. Defaults to `False`.
+    """
+
+    min_length: int = attrs.field(
+        validator=(attrs.validators.instance_of(int), attrs.validators.ge(1))
+    )
+    gauges: tuple[cirq.Gate, ...] = attrs.field(
+        default='clifford', converter=_gauges_arg_converter, repr=_repr_fn
+    )
+    gauge_beginning: bool = False
+    gauge_ending: bool = False
+
+    @functools.cached_property
+    def gauges_inverse(self) -> tuple[cirq.Gate, ...]:
+        if self.gauges is _PAULIS:
+            return _PAULIS
+        if self.gauges is _CLIFFORDS:
+            return _INV_CLIFFORDS
+        if self.gauges is _INV_CLIFFORDS:
+            return _CLIFFORDS
+        return tuple(g**-1 for g in self.gauges)
+
+    def __call__(
+        self,
+        circuit: cirq.AbstractCircuit,
+        *,
+        context: transformer_api.TransformerContext | None = None,
+        rng_or_seed: np.random.Generator | int | None = None,
+    ):
+        """Apply the IdleMomentGauge transformer.
+
+        Args:
+            circuit: The circuit to process.
+            context: The TransformerContext.
+            rng_or_seed: The source of randomness.
+
+        Returns:
+            A transformed circuit.
+
+        Raises:
+            ValueError: if the TransformerContext has deep=True.
+        """
+        rng = (
+            rng_or_seed
+            if isinstance(rng_or_seed, np.random.Generator)
+            else np.random.default_rng(rng_or_seed)
+        )
+        context = (
+            context
+            if isinstance(context, transformer_api.TransformerContext)
+            else transformer_api.TransformerContext(deep=False)
+        )
+        if context.deep:
+            raise ValueError("IdleMomentsGauge doesn't support deep TransformerContext")
+
+        tags_to_ignore = frozenset(context.tags_to_ignore)
+        all_qubits = circuit.all_qubits()
+
+        active_moments: dict[cirq.Qid, list[tuple[int, bool]]] = {q: [] for q in all_qubits}
+        for m_id, moment in enumerate(circuit):
+            if not tags_to_ignore.isdisjoint(moment.tags):
+                for q in all_qubits:
+                    active_moments[q].append((m_id, False))
+            else:
+                for op in moment:
+                    is_mergable = (
+                        len(op.qubits) == 1
+                        and tags_to_ignore.isdisjoint(op.tags)
+                        and op.gate is not None
+                    )
+                    for q in op.qubits:
+                        active_moments[q].append((m_id, is_mergable))
+
+        single_qubit_moments = [
+            {op.qubits[0]: op for op in m if len(op.qubits) == 1} for m in circuit
+        ]
+        non_single_qubit_moments = [[op for op in m if len(op.qubits) != 1] for m in circuit]
+
+        for q, active in active_moments.items():
+            for s, e in _get_structure(
+                active, self.min_length, len(circuit), self.gauge_beginning, self.gauge_ending
+            ):
+                gate_index = rng.choice(len(self.gauges))
+                gate = self.gauges[gate_index]
+                gate_inv = self.gauges_inverse[gate_index]
+
+                if existing_op := single_qubit_moments[s].get(q, None):
+                    existing_gate = existing_op.gate
+                    assert existing_gate is not None
+                    single_qubit_moments[s][q] = _merge(existing_gate, gate, q, existing_op.tags)
+                else:
+                    single_qubit_moments[s][q] = gate(q)
+
+                if existing_op := single_qubit_moments[e].get(q, None):
+                    existing_gate = existing_op.gate
+                    assert existing_gate is not None
+                    single_qubit_moments[e][q] = _merge(
+                        gate_inv, existing_gate, q, existing_op.tags
+                    )
+                else:
+                    single_qubit_moments[e][q] = gate_inv(q)
+
+        return circuits.Circuit.from_moments(
+            *(
+                [op for op in sq.values()] + nsq
+                for sq, nsq in zip(single_qubit_moments, non_single_qubit_moments, strict=True)
+            )
+        )

cirq/transformers/gauge_compiling/idle_moments_gauge_test.py

@@ -0,0 +1,193 @@
+# 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 numpy as np
+import pytest
+
+import cirq
+from cirq.transformers import gauge_compiling
+
+
+class _MockRng(np.random.Generator):
+
+    def __init__(self, vals):
+        self._n_calls = 0
+        self._res = tuple(vals)
+
+    def choice(self, seq):
+        ret = self._res[self._n_calls]
+        self._n_calls += 1
+        return ret
+
+
+def test_add_gauge_merges_gates():
+    tr = gauge_compiling.IdleMomentsGauge(2, gauges='pauli')
+
+    circuit = cirq.Circuit.from_moments([], [], [], cirq.X(cirq.q(0)), [], [], cirq.X(cirq.q(0)))
+    transformed_circuit = tr(circuit, rng_or_seed=_MockRng([3]))
+
+    assert transformed_circuit == cirq.Circuit.from_moments(
+        [],
+        [],
+        [],
+        cirq.PhasedXZGate(axis_phase_exponent=0.5, x_exponent=1, z_exponent=0)(cirq.q(0)),
+        [],
+        [],
+        cirq.PhasedXZGate(axis_phase_exponent=0.5, x_exponent=1, z_exponent=0)(cirq.q(0)),
+    )
+
+
+def test_add_gauge_respects_ignore_tag():
+    tr = gauge_compiling.IdleMomentsGauge(2, gauges='pauli')
+
+    circuit = cirq.Circuit.from_moments(
+        cirq.X(cirq.q(0)), [], [], cirq.X(cirq.q(0)).with_tags('ignore')
+    )
+    transformed_circuit = tr(
+        circuit,
+        context=cirq.TransformerContext(tags_to_ignore=("ignore",)),
+        rng_or_seed=_MockRng([3]),
+    )
+    assert transformed_circuit == cirq.Circuit.from_moments(
+        cirq.PhasedXZGate(axis_phase_exponent=0.5, x_exponent=1, z_exponent=0)(cirq.q(0)),
+        [],
+        cirq.Z(cirq.q(0)),
+        cirq.X(cirq.q(0)).with_tags('ignore'),
+    )
+
+
+def test_add_gauge_respects_ignore_moment():
+    tr = gauge_compiling.IdleMomentsGauge(2, gauges='pauli')
+
+    circuit = cirq.Circuit.from_moments(
+        cirq.X(cirq.q(0)), [], [], cirq.Moment(cirq.X(cirq.q(0))).with_tags('ignore')
+    )
+    transformed_circuit = tr(
+        circuit,
+        context=cirq.TransformerContext(tags_to_ignore=("ignore",)),
+        rng_or_seed=_MockRng([3]),
+    )
+    assert transformed_circuit == cirq.Circuit.from_moments(
+        cirq.PhasedXZGate(axis_phase_exponent=0.5, x_exponent=1, z_exponent=0)(cirq.q(0)),
+        [],
+        cirq.Z(cirq.q(0)),
+        cirq.Moment(cirq.X(cirq.q(0))).with_tags('ignore'),
+    )
+
+
+def test_add_gauge_on_prefix():
+    tr = gauge_compiling.IdleMomentsGauge(3, gauges='clifford', gauge_beginning=True)
+
+    circuit = cirq.Circuit.from_moments([], [], [], cirq.CNOT(cirq.q(0), cirq.q(1)))
+    transformed_circuit = tr(circuit, rng_or_seed=_MockRng([20, 15]))
+    assert transformed_circuit == cirq.Circuit.from_moments(
+        [
+            cirq.SingleQubitCliffordGate.all_single_qubit_cliffords[20](cirq.q(0)),
+            cirq.SingleQubitCliffordGate.all_single_qubit_cliffords[15](cirq.q(1)),
+        ],
+        [],
+        [
+            cirq.SingleQubitCliffordGate.all_single_qubit_cliffords[20](cirq.q(0)) ** -1,
+            cirq.SingleQubitCliffordGate.all_single_qubit_cliffords[15](cirq.q(1)) ** -1,
+        ],
+        cirq.CNOT(cirq.q(0), cirq.q(1)),
+    )
+
+
+def test_add_gauge_on_prefix_with_merge():
+    tr = gauge_compiling.IdleMomentsGauge(3, gauges=[cirq.Y], gauge_beginning=True)
+
+    circuit = cirq.Circuit.from_moments([], [], [], cirq.X(cirq.q(0)))
+    transformed_circuit = tr(circuit, rng_or_seed=_MockRng([0]))
+    assert transformed_circuit == cirq.Circuit.from_moments(
+        [cirq.Y(cirq.q(0))],
+        [],
+        [],
+        cirq.PhasedXZGate(axis_phase_exponent=0, x_exponent=0, z_exponent=1)(cirq.q(0)),
+    )
+
+
+def test_add_gauge_on_suffix():
+    tr = gauge_compiling.IdleMomentsGauge(3, gauges='inv_clifford', gauge_ending=True)
+
+    circuit = cirq.Circuit.from_moments(cirq.CNOT(cirq.q(0), cirq.q(1)), [], [], [])
+    transformed_circuit = tr(circuit, rng_or_seed=_MockRng([20, 15]))
+    assert transformed_circuit == cirq.Circuit.from_moments(
+        cirq.CNOT(cirq.q(0), cirq.q(1)),
+        [
+            cirq.SingleQubitCliffordGate.all_single_qubit_cliffords[20](cirq.q(0)) ** -1,
+            cirq.SingleQubitCliffordGate.all_single_qubit_cliffords[15](cirq.q(1)) ** -1,
+        ],
+        [],
+        [
+            cirq.SingleQubitCliffordGate.all_single_qubit_cliffords[20](cirq.q(0)),
+            cirq.SingleQubitCliffordGate.all_single_qubit_cliffords[15](cirq.q(1)),
+        ],
+    )
+
+
+def test_add_gauge_on_suffix_with_merge():
+    tr = gauge_compiling.IdleMomentsGauge(3, gauges=[cirq.Y], gauge_ending=True)
+
+    circuit = cirq.Circuit.from_moments(cirq.X(cirq.q(0)), [], [], [])
+    transformed_circuit = tr(circuit, rng_or_seed=_MockRng([0]))
+    assert transformed_circuit == cirq.Circuit.from_moments(
+        cirq.PhasedXZGate(axis_phase_exponent=0, x_exponent=0, z_exponent=1)(cirq.q(0)),
+        [],
+        [],
+        cirq.Y(cirq.q(0)),
+    )
+
+
+def test_add_gauge_respects_min_length():
+    tr = gauge_compiling.IdleMomentsGauge(2, gauges=[cirq.X])
+
+    circuit = cirq.Circuit.from_moments(cirq.X(cirq.q(0)), [], cirq.X(cirq.q(0)))
+    transformed_circuit = tr(circuit)
+    assert transformed_circuit == circuit
+
+
+def test_context_with_deep_raises():
+    tr = gauge_compiling.IdleMomentsGauge(2, gauges=[cirq.X])
+
+    circuit = cirq.Circuit.from_moments(cirq.X(cirq.q(0)), [], cirq.X(cirq.q(0)))
+    with pytest.raises(
+        ValueError, match="IdleMomentsGauge doesn't support deep TransformerContext"
+    ):
+        _ = tr(circuit, context=cirq.TransformerContext(deep=True))
+
+
+def test_gauge_with_invalid_name_raises():
+    with pytest.raises(ValueError, match='valid gauge'):
+        _ = gauge_compiling.IdleMomentsGauge(2, gauges='invalid')
+
+
+def test_repr():
+    assert repr(gauge_compiling.IdleMomentsGauge(3, gauges='pauli')) == (
+        'IdleMomentsGauge(min_length=3, gauges="pauli", '
+        'gauge_beginning=False, gauge_ending=False)'
+    )
+    assert repr(gauge_compiling.IdleMomentsGauge(4, gauges='clifford')) == (
+        'IdleMomentsGauge(min_length=4, gauges="clifford", '
+        'gauge_beginning=False, gauge_ending=False)'
+    )
+    assert repr(gauge_compiling.IdleMomentsGauge(5, gauges='inv_clifford')) == (
+        'IdleMomentsGauge(min_length=5, gauges="inv_clifford", '
+        'gauge_beginning=False, gauge_ending=False)'
+    )
+    assert repr(gauge_compiling.IdleMomentsGauge(6, gauges=[cirq.X])) == (
+        'IdleMomentsGauge(min_length=6, gauges=(cirq.X,), '
+        'gauge_beginning=False, gauge_ending=False)'
+    )

cirq/transformers/gauge_compiling/multi_moment_cphase_gauge.py

@@ -0,0 +1,242 @@
+# 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.
+
+"""A Multi-Moment Gauge Transformer for the cphase gate."""
+
+from __future__ import annotations
+
+from typing import cast
+
+import numpy as np
+from attrs import field, frozen
+
+from cirq import circuits, ops
+from cirq.transformers.gauge_compiling.multi_moment_gauge_compiling import (
+    MultiMomentGaugeTransformer,
+)
+
+_PAULIS: np.ndarray = np.array((ops.I, ops.X, ops.Y, ops.Z), dtype=object)
+_COMMUTING_GATES = {ops.I, ops.Z}  # I,Z Commute with ZPowGate and CZPowGate; X,Y anti-commute.
+
+
+def _merge_pauliandzpow(left: _PauliAndZPow, right: _PauliAndZPow) -> _PauliAndZPow:
+    # 1. Commute left.zpow and right.pauli:
+    #        ─left.pauli─left.zpow─right.pauli─right.zpow─
+    #    ==> ─left.pauli─right.pauli─(+/-left.zpow─right.zpow)─
+    if right.pauli in _COMMUTING_GATES:
+        new_zpow_exp = left.zpow.exponent + right.zpow.exponent
+    else:
+        new_zpow_exp = -left.zpow.exponent + right.zpow.exponent
+
+    # 2. Merge left.pauli and right.pauli
+    new_pauli = left.pauli
+    if right.pauli is not ops.I:
+        if new_pauli is ops.I:
+            new_pauli = right.pauli
+        else:
+            # left.pauli * right.pauli
+            new_pauli = cast(ops.Pauli, new_pauli).phased_pauli_product(
+                cast(ops.Pauli, right.pauli)
+            )[1]
+
+    return _PauliAndZPow(pauli=new_pauli, zpow=ops.ZPowGate(exponent=new_zpow_exp))
+
+
+@frozen
+class _PauliAndZPow:
+    """A gate represented by a Pauli followed by a ZPowGate.
+
+    The order is ─Pauli──ZPowGate─.
+
+    Attributes:
+        pauli: The Pauli gate.
+        zpow: The ZPowGate.
+    """
+
+    pauli: ops.Pauli | ops.IdentityGate = ops.I
+    zpow: ops.ZPowGate = ops.ZPowGate(exponent=0)
+
+    def merge_left(self, left: _PauliAndZPow) -> _PauliAndZPow:
+        """Merges another `_PauliAndZPow` from the left.
+
+        Calculates `─left─self─` and returns a new `_PauliAndZPow` instance.
+        """
+        return _merge_pauliandzpow(left, self)
+
+    def merge_right(self, right: _PauliAndZPow) -> _PauliAndZPow:
+        """Merges another `_PauliAndZPow` from the right.
+
+        Calculates `─self─right─` and returns a new `_PauliAndZPow` instance.
+        """
+        return _merge_pauliandzpow(self, right)
+
+    def after_cphase(
+        self, cphase: ops.CZPowGate
+    ) -> tuple[ops.CZPowGate, _PauliAndZPow, _PauliAndZPow]:
+        """Pull self through cphase.
+
+        Returns:
+            A tuple of
+                (updated cphase gate, pull_through of this qubit, pull_through of the other qubit).
+        """
+        if self.pauli in _COMMUTING_GATES:
+            return cphase, _PauliAndZPow(self.pauli, self.zpow), _PauliAndZPow()
+        else:
+            # Taking self.pauli==X gate as an example:
+            # 0: ─X─Z^t──@──────      0: ─X──@─────Z^t─       0: ─@──────X──Z^t──
+            #            │       ==>         │           ==>      │
+            # 1: ────────@^exp──      1: ────@^exp─────       1: ─@^-exp─Z^exp───
+            # Similarly for X|Y on qubit 0/1, the result is always flipping cphase and
+            # add an extra Rz rotation on the other qubit.
+            return (
+                cast(ops.CZPowGate, cphase**-1),
+                _PauliAndZPow(self.pauli, self.zpow),
+                _PauliAndZPow(zpow=ops.ZPowGate(exponent=cphase.exponent)),
+            )
+
+    def after_pauli(self, pauli: ops.Pauli | ops.IdentityGate) -> _PauliAndZPow:
+        """Calculates ─self─pauli─  ==>  ─pauli─output─."""
+        if pauli in _COMMUTING_GATES:
+            return _PauliAndZPow(self.pauli, self.zpow)
+        else:
+            return _PauliAndZPow(self.pauli, ops.ZPowGate(exponent=-self.zpow.exponent))
+
+    def after_zpow(self, zpow: ops.ZPowGate) -> tuple[ops.ZPowGate, _PauliAndZPow]:
+        """Calculates ─self─zpow─  ==>  ─+/-zpow─output─."""
+        if self.pauli in _COMMUTING_GATES:
+            return zpow, _PauliAndZPow(self.pauli, self.zpow)
+        else:
+            return ops.ZPowGate(exponent=-zpow.exponent), self
+
+    def __str__(self) -> str:
+        return f"─{self.pauli}──{self.zpow}─"
+
+    def to_single_qubit_gate(self) -> ops.PhasedXZGate | ops.ZPowGate | ops.IdentityGate:
+        """Converts the _PauliAndZPow to a single-qubit gate."""
+        exp = self.zpow.exponent
+        match self.pauli:
+            case ops.I:
+                if exp % 2 == 0:
+                    return ops.I
+                return self.zpow
+            case ops.X:
+                return ops.PhasedXZGate(x_exponent=1, z_exponent=exp, axis_phase_exponent=0)
+            case ops.Y:
+                return ops.PhasedXZGate(x_exponent=1, z_exponent=exp - 1, axis_phase_exponent=0)
+            case _:  # ops.Z
+                return ops.ZPowGate(exponent=1 + exp)
+
+
+def _pull_through_single_cphase(
+    cphase: ops.CZPowGate, input0: _PauliAndZPow, input1: _PauliAndZPow
+) -> tuple[ops.CZPowGate, _PauliAndZPow, _PauliAndZPow]:
+    """Pulls input0 and input1 through a CZPowGate.
+    Input:                      Output:
+    0: ─(input0)─@─────         0: ─@────────(output0)─
+                 │        ==>       │
+    1: ─(input1)─@^exp─         1: ─@^+/-exp─(output1)─
+    """
+
+    # Step 1; pull input0 through CZPowGate.
+    # 0: ─input0─@─────     0: ────────@─────────output0─
+    #            │      ==>            │
+    # 1: ─input1─@^exp─     1: ─input1─@^+/-exp──output1─
+    output_cphase, output0, output1 = input0.after_cphase(cphase)
+
+    # Step 2; similar to step 1, pull input1 through CZPowGate.
+    #      0: ─@──────────pulled0────output0─     0: ─@────────output0─
+    #  ==>     │                              ==>     │
+    #      1: ─@^+/-exp───pulled1────output1─     1: ─@^+/-exp─output1─
+    output_cphase, pulled1, pulled0 = input1.after_cphase(output_cphase)
+    output0 = output0.merge_left(pulled0)
+    output1 = output1.merge_left(pulled1)
+
+    return output_cphase, output0, output1
+
+
+_TARGET_GATESET: ops.Gateset = ops.Gateset(ops.CZPowGate)
+_SUPPORTED_GATESET: ops.Gateset = ops.Gateset(ops.Pauli, ops.IdentityGate, ops.ZPowGate)
+
+
+@frozen
+class CPhaseGaugeTransformerMM(MultiMomentGaugeTransformer):
+    """A gauge transformer for the cphase gate."""
+
+    target: ops.GateFamily | ops.Gateset = field(default=_TARGET_GATESET, init=False)
+    supported_gates: ops.GateFamily | ops.Gateset = field(default=_SUPPORTED_GATESET)
+
+    def sample_left_moment(
+        self, active_qubits: frozenset[ops.Qid], prng: np.random.Generator
+    ) -> circuits.Moment:
+        return circuits.Moment([cast(ops.Gate, prng.choice(_PAULIS)).on(q) for q in active_qubits])
+
+    def gauge_on_moments(
+        self, moments_to_gauge: list[circuits.Moment], prng: np.random.Generator
+    ) -> list[circuits.Moment]:
+        """Gauges a block of moments that contains at least a cphase gate in each of the moment.
+
+        Args:
+            moments_to_gauge: A list of moments to be gauged.
+            prng: A pseudorandom number generator.
+
+        Returns:
+            A list of moments after gauging.
+        """
+        active_qubits = circuits.Circuit.from_moments(*moments_to_gauge).all_qubits()
+        left_moment = self.sample_left_moment(active_qubits, prng)
+        pulled: dict[ops.Qid, _PauliAndZPow] = {
+            op.qubits[0]: _PauliAndZPow(pauli=cast(ops.Pauli | ops.IdentityGate, op.gate))
+            for op in left_moment
+            if op.gate
+        }
+        ret: list[circuits.Moment] = [left_moment]
+        # The loop iterates through each moment of the target block, propagating
+        # the `pulled` gauge from left to right. In each iteration, `prev` holds
+        # the gauge to the left of the current `moment`, and the loop computes
+        # the transformed `moment` and the new `pulled` gauge to its right.
+        for moment in moments_to_gauge:
+            # Calculate --prev--moment-- ==> --updated_momment--pulled--
+            prev = pulled
+            pulled = {}
+            ops_at_updated_moment: list[ops.Operation] = []
+            for op in moment:
+                # Pull prev through ops at the moment.
+                if op.gate:
+                    match op.gate:
+                        case ops.CZPowGate():
+                            q0, q1 = op.qubits
+                            new_gate, pulled[q0], pulled[q1] = _pull_through_single_cphase(
+                                op.gate, prev[q0], prev[q1]
+                            )
+                            ops_at_updated_moment.append(new_gate.on(q0, q1))
+                        case ops.Pauli() | ops.IdentityGate():
+                            q = op.qubits[0]
+                            ops_at_updated_moment.append(op)
+                            pulled[q] = prev[q].after_pauli(op.gate)
+                        case ops.ZPowGate():
+                            q = op.qubits[0]
+                            new_zpow, pulled[q] = prev[q].after_zpow(op.gate)
+                            ops_at_updated_moment.append(new_zpow.on(q))
+                        case _:
+                            raise ValueError(f"Gate type {type(op.gate)} is not supported.")
+            # Keep the other ops of prev
+            for q, gate in prev.items():
+                if q not in pulled:
+                    pulled[q] = gate
+            ret.append(circuits.Moment(ops_at_updated_moment))
+        last_moment = circuits.Moment(
+            [gate.to_single_qubit_gate().on(q) for q, gate in pulled.items()]
+        )
+        ret.append(last_moment)
+        return ret