cirq-core 1.3.0.dev20231201141002__py3-none-any.whl → 1.4.0__py3-none-any.whl

cirq/transformers/dynamical_decoupling.py

@@ -0,0 +1,122 @@
+# Copyright 2024 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.
+
+"""Transformer pass that adds dynamical decoupling operations to a circuit."""
+
+from functools import reduce
+from typing import Dict, Optional, Sequence, Tuple, Union
+
+from cirq.transformers import transformer_api
+import cirq
+import numpy as np
+
+
+def _repeat_sequence(
+    base_sequence: Sequence['cirq.Gate'], num_idle_moments: int
+) -> Sequence['cirq.Gate']:
+    """Returns the longest possible dynamical decoupling sequence."""
+    repeat_times = num_idle_moments // len(base_sequence)
+    return list(base_sequence) * repeat_times
+
+
+def _get_dd_sequence_from_schema_name(schema: str) -> Sequence['cirq.Gate']:
+    """Gets dynamical decoupling sequence from a schema name."""
+    dd_sequence: Sequence['cirq.Gate']
+    match schema:
+        case 'XX_PAIR':
+            dd_sequence = (cirq.X, cirq.X)
+        case 'X_XINV':
+            dd_sequence = (cirq.X, cirq.X**-1)
+        case 'YY_PAIR':
+            dd_sequence = (cirq.Y, cirq.Y)
+        case 'Y_YINV':
+            dd_sequence = (cirq.Y, cirq.Y**-1)
+        case _:
+            raise ValueError('Invalid schema name.')
+    return dd_sequence
+
+
+def _validate_dd_sequence(dd_sequence: Sequence['cirq.Gate']) -> None:
+    """Validates a given dynamical decoupling sequence.
+
+    Args:
+        dd_sequence: Input dynamical sequence to be validated.
+
+    Returns:
+        A tuple containing:
+            - is_valid (bool): True if the dd sequence is valid, False otherwise.
+            - error_message (str): An error message if the dd sequence is invalid, else None.
+
+    Raises:
+        ValueError: If dd_sequence is not valid.
+    """
+    if len(dd_sequence) < 2:
+        raise ValueError('Invalid dynamical decoupling sequence. Expect more than one gates.')
+    matrices = [cirq.unitary(gate) for gate in dd_sequence]
+    product = reduce(np.matmul, matrices)
+
+    if not cirq.equal_up_to_global_phase(product, np.eye(2)):
+        raise ValueError(
+            'Invalid dynamical decoupling sequence. Expect sequence production equals'
+            f' identity up to a global phase, got {product}.'.replace('\n', ' ')
+        )
+
+
+def _parse_dd_sequence(schema: Union[str, Sequence['cirq.Gate']]) -> Sequence['cirq.Gate']:
+    """Parses and returns dynamical decoupling sequence from schema."""
+    if isinstance(schema, str):
+        dd_sequence = _get_dd_sequence_from_schema_name(schema)
+    else:
+        _validate_dd_sequence(schema)
+        dd_sequence = schema
+    return dd_sequence
+
+
+@transformer_api.transformer
+def add_dynamical_decoupling(
+    circuit: 'cirq.AbstractCircuit',
+    *,
+    context: Optional['cirq.TransformerContext'] = None,
+    schema: Union[str, Sequence['cirq.Gate']] = 'X_XINV',
+) -> 'cirq.Circuit':
+    """Adds dynamical decoupling gate operations to idle moments of a given circuit.
+    This transformer preserves the moment structure of the circuit.
+
+    Args:
+          circuit: Input circuit to transform.
+          context: `cirq.TransformerContext` storing common configurable options for transformers.
+          schema: Dynamical decoupling schema name or a dynamical decoupling sequence.
+            If a schema is specified, provided dynamical decouping sequence will be used.
+            Otherwise, customized dynamical decoupling sequence will be applied.
+
+    Returns:
+          A copy of the input circuit with dynamical decoupling operations.
+    """
+    last_busy_moment_by_qubits: Dict['cirq.Qid', int] = {q: 0 for q in circuit.all_qubits()}
+    insert_into: list[Tuple[int, 'cirq.OP_TREE']] = []
+
+    base_dd_sequence = _parse_dd_sequence(schema)
+
+    for moment_id, moment in enumerate(circuit):
+        for q in moment.qubits:
+            insert_gates = _repeat_sequence(
+                base_dd_sequence, num_idle_moments=moment_id - last_busy_moment_by_qubits[q] - 1
+            )
+            for idx, gate in enumerate(insert_gates):
+                insert_into.append((last_busy_moment_by_qubits[q] + idx + 1, gate.on(q)))
+            last_busy_moment_by_qubits[q] = moment_id
+
+    updated_circuit = circuit.unfreeze(copy=True)
+    updated_circuit.batch_insert_into(insert_into)
+    return updated_circuit

cirq/transformers/dynamical_decoupling_test.py

@@ -0,0 +1,123 @@
+# Copyright 2024 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 typing import Sequence, Union
+import cirq
+from cirq import add_dynamical_decoupling
+import pytest
+
+
+def assert_dd(
+    input_circuit: cirq.Circuit,
+    expected_circuit: cirq.Circuit,
+    schema: Union[str, Sequence['cirq.Gate']],
+):
+    updated_circuit = add_dynamical_decoupling(input_circuit, schema=schema)
+    cirq.testing.assert_same_circuits(updated_circuit, expected_circuit)
+
+
+def test_no_insert_due_to_no_consecutive_moments():
+    a = cirq.NamedQubit('a')
+    b = cirq.NamedQubit('b')
+
+    # No insertion as there is no room for a dd sequence.
+    assert_dd(
+        input_circuit=cirq.Circuit(
+            cirq.Moment(cirq.H(a)), cirq.Moment(cirq.CNOT(a, b)), cirq.Moment(cirq.H(b))
+        ),
+        expected_circuit=cirq.Circuit(
+            cirq.Moment(cirq.H(a)), cirq.Moment(cirq.CNOT(a, b)), cirq.Moment(cirq.H(b))
+        ),
+        schema='XX_PAIR',
+    )
+
+
+@pytest.mark.parametrize(
+    'schema,inserted_gates',
+    [
+        ('XX_PAIR', (cirq.X, cirq.X)),
+        ('X_XINV', (cirq.X, cirq.X**-1)),
+        ('YY_PAIR', (cirq.Y, cirq.Y)),
+        ('Y_YINV', (cirq.Y, cirq.Y**-1)),
+    ],
+)
+def test_insert_provided_schema(schema: str, inserted_gates: Sequence['cirq.Gate']):
+    a = cirq.NamedQubit('a')
+    b = cirq.NamedQubit('b')
+    c = cirq.NamedQubit('c')
+
+    input_circuit = cirq.Circuit(
+        cirq.Moment(cirq.H(a)),
+        cirq.Moment(cirq.CNOT(a, b)),
+        cirq.Moment(cirq.CNOT(b, c)),
+        cirq.Moment(cirq.CNOT(b, c)),
+        cirq.Moment(cirq.measure_each(a, b, c)),
+    )
+    expected_circuit = cirq.Circuit(
+        cirq.Moment(cirq.H(a)),
+        cirq.Moment(cirq.CNOT(a, b)),
+        cirq.Moment(cirq.CNOT(b, c), inserted_gates[0](a)),
+        cirq.Moment(cirq.CNOT(b, c), inserted_gates[1](a)),
+        cirq.Moment(cirq.measure_each(a, b, c)),
+    )
+
+    # Insert one dynamical decoupling sequence in idle moments.
+    assert_dd(input_circuit, expected_circuit, schema=schema)
+
+
+def test_insert_by_customized_dd_sequence():
+    a = cirq.NamedQubit('a')
+    b = cirq.NamedQubit('b')
+    c = cirq.NamedQubit('c')
+
+    assert_dd(
+        input_circuit=cirq.Circuit(
+            cirq.Moment(cirq.H(a)),
+            cirq.Moment(cirq.CNOT(a, b)),
+            cirq.Moment(cirq.CNOT(b, c)),
+            cirq.Moment(cirq.CNOT(b, c)),
+            cirq.Moment(cirq.CNOT(b, c)),
+            cirq.Moment(cirq.CNOT(b, c)),
+            cirq.Moment(cirq.measure_each(a, b, c)),
+        ),
+        expected_circuit=cirq.Circuit(
+            cirq.Moment(cirq.H(a)),
+            cirq.Moment(cirq.CNOT(a, b)),
+            cirq.Moment(cirq.CNOT(b, c), cirq.X(a)),
+            cirq.Moment(cirq.CNOT(b, c), cirq.X(a)),
+            cirq.Moment(cirq.CNOT(b, c), cirq.Y(a)),
+            cirq.Moment(cirq.CNOT(b, c), cirq.Y(a)),
+            cirq.Moment(cirq.measure_each(a, b, c)),
+        ),
+        schema=[cirq.X, cirq.X, cirq.Y, cirq.Y],
+    )
+
+
+@pytest.mark.parametrize(
+    'schema,error_msg_regex',
+    [
+        ('INVALID_SCHEMA', 'Invalid schema name.'),
+        ([cirq.X], 'Invalid dynamical decoupling sequence. Expect more than one gates.'),
+        (
+            [cirq.X, cirq.H],
+            'Invalid dynamical decoupling sequence. Expect sequence production equals identity'
+            ' up to a global phase, got',
+        ),
+    ],
+)
+def test_invalid_dd_schema(schema: Union[str, Sequence['cirq.Gate']], error_msg_regex):
+    a = cirq.NamedQubit('a')
+    input_circuit = cirq.Circuit(cirq.H(a))
+    with pytest.raises(ValueError, match=error_msg_regex):
+        add_dynamical_decoupling(input_circuit, schema=schema)

cirq/transformers/gauge_compiling/__init__.py

@@ -0,0 +1,26 @@
+# Copyright 2024 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 cirq.transformers.gauge_compiling.gauge_compiling import (
+    ConstantGauge,
+    Gauge,
+    GaugeSelector,
+    GaugeTransformer,
+)
+from cirq.transformers.gauge_compiling.sqrt_cz_gauge import SqrtCZGaugeTransformer
+from cirq.transformers.gauge_compiling.spin_inversion_gauge import SpinInversionGaugeTransformer
+from cirq.transformers.gauge_compiling.cz_gauge import CZGaugeTransformer
+from cirq.transformers.gauge_compiling.iswap_gauge import ISWAPGaugeTransformer
+from cirq.transformers.gauge_compiling.sqrt_iswap_gauge import SqrtISWAPGaugeTransformer

cirq/transformers/gauge_compiling/cz_gauge.py

@@ -0,0 +1,46 @@
+# Copyright 2024 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 Gauge Transformer for the CZ gate."""
+
+from cirq.transformers.gauge_compiling.gauge_compiling import (
+    GaugeTransformer,
+    GaugeSelector,
+    ConstantGauge,
+)
+from cirq.ops.common_gates import CZ
+from cirq import ops
+
+CZGaugeSelector = GaugeSelector(
+    gauges=[
+        ConstantGauge(two_qubit_gate=CZ, pre_q0=ops.I, pre_q1=ops.I, post_q0=ops.I, post_q1=ops.I),
+        ConstantGauge(two_qubit_gate=CZ, pre_q0=ops.I, pre_q1=ops.X, post_q0=ops.Z, post_q1=ops.X),
+        ConstantGauge(two_qubit_gate=CZ, pre_q0=ops.I, pre_q1=ops.Y, post_q0=ops.Z, post_q1=ops.Y),
+        ConstantGauge(two_qubit_gate=CZ, pre_q0=ops.I, pre_q1=ops.Z, post_q0=ops.I, post_q1=ops.Z),
+        ConstantGauge(two_qubit_gate=CZ, pre_q0=ops.X, pre_q1=ops.I, post_q0=ops.X, post_q1=ops.Z),
+        ConstantGauge(two_qubit_gate=CZ, pre_q0=ops.X, pre_q1=ops.X, post_q0=ops.Y, post_q1=ops.Y),
+        ConstantGauge(two_qubit_gate=CZ, pre_q0=ops.X, pre_q1=ops.Y, post_q0=ops.Y, post_q1=ops.X),
+        ConstantGauge(two_qubit_gate=CZ, pre_q0=ops.X, pre_q1=ops.Z, post_q0=ops.X, post_q1=ops.I),
+        ConstantGauge(two_qubit_gate=CZ, pre_q0=ops.Y, pre_q1=ops.I, post_q0=ops.Y, post_q1=ops.Z),
+        ConstantGauge(two_qubit_gate=CZ, pre_q0=ops.Y, pre_q1=ops.X, post_q0=ops.X, post_q1=ops.Y),
+        ConstantGauge(two_qubit_gate=CZ, pre_q0=ops.Y, pre_q1=ops.Y, post_q0=ops.X, post_q1=ops.X),
+        ConstantGauge(two_qubit_gate=CZ, pre_q0=ops.Y, pre_q1=ops.Z, post_q0=ops.Y, post_q1=ops.I),
+        ConstantGauge(two_qubit_gate=CZ, pre_q0=ops.Z, pre_q1=ops.I, post_q0=ops.Z, post_q1=ops.I),
+        ConstantGauge(two_qubit_gate=CZ, pre_q0=ops.Z, pre_q1=ops.X, post_q0=ops.I, post_q1=ops.X),
+        ConstantGauge(two_qubit_gate=CZ, pre_q0=ops.Z, pre_q1=ops.Y, post_q0=ops.I, post_q1=ops.Y),
+        ConstantGauge(two_qubit_gate=CZ, pre_q0=ops.Z, pre_q1=ops.Z, post_q0=ops.Z, post_q1=ops.Z),
+    ]
+)
+
+CZGaugeTransformer = GaugeTransformer(target=CZ, gauge_selector=CZGaugeSelector)

cirq/transformers/gauge_compiling/cz_gauge_test.py

@@ -0,0 +1,23 @@
+# Copyright 2024 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 cirq
+from cirq.transformers.gauge_compiling import CZGaugeTransformer
+from cirq.transformers.gauge_compiling.gauge_compiling_test_utils import GaugeTester
+
+
+class TestCZGauge(GaugeTester):
+    two_qubit_gate = cirq.CZ
+    gauge_transformer = CZGaugeTransformer

cirq/transformers/gauge_compiling/gauge_compiling.py

@@ -0,0 +1,214 @@
+# Copyright 2024 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.
+
+"""Creates the abstraction for gauge compiling as a cirq transformer."""
+
+from typing import Callable, Tuple, Optional, Sequence, Union, List
+import abc
+import itertools
+import functools
+
+from dataclasses import dataclass
+from attrs import frozen, field
+import numpy as np
+
+from cirq.transformers import transformer_api
+from cirq import ops, circuits
+
+
+class Gauge(abc.ABC):
+    """A gauge replaces a two qubit gate with an equivalent subcircuit.
+    0: pre_q0───────two_qubit_gate───────post_q0
+                        |
+    1: pre_q1───────two_qubit_gate───────post_q1
+
+    The Gauge class in general represents a family of closely related gauges
+    (e.g. random z-rotations); Use `sample` method to get a specific gauge.
+    """
+
+    def weight(self) -> float:
+        """Returns the relative frequency for selecting this gauge."""
+        return 1.0
+
+    @abc.abstractmethod
+    def sample(self, gate: ops.Gate, prng: np.random.Generator) -> "ConstantGauge":
+        """Returns a ConstantGauge sampled from a family of gauges.
+
+        Args:
+            gate: The two qubit gate to replace.
+            prng: A numpy random number generator.
+
+        Returns:
+            A ConstantGauge.
+        """
+
+
+@frozen
+class ConstantGauge(Gauge):
+    """A gauge that replaces a two qubit gate with a constant gauge."""
+
+    two_qubit_gate: ops.Gate
+    pre_q0: Tuple[ops.Gate, ...] = field(
+        default=(), converter=lambda g: (g,) if isinstance(g, ops.Gate) else tuple(g)
+    )
+    pre_q1: Tuple[ops.Gate, ...] = field(
+        default=(), converter=lambda g: (g,) if isinstance(g, ops.Gate) else tuple(g)
+    )
+    post_q0: Tuple[ops.Gate, ...] = field(
+        default=(), converter=lambda g: (g,) if isinstance(g, ops.Gate) else tuple(g)
+    )
+    post_q1: Tuple[ops.Gate, ...] = field(
+        default=(), converter=lambda g: (g,) if isinstance(g, ops.Gate) else tuple(g)
+    )
+    swap_qubits: bool = False
+
+    def sample(self, gate: ops.Gate, prng: np.random.Generator) -> "ConstantGauge":
+        return self
+
+    @property
+    def pre(self) -> Tuple[Tuple[ops.Gate, ...], Tuple[ops.Gate, ...]]:
+        """A tuple (ops to apply to q0, ops to apply to q1)."""
+        return self.pre_q0, self.pre_q1
+
+    @property
+    def post(self) -> Tuple[Tuple[ops.Gate, ...], Tuple[ops.Gate, ...]]:
+        """A tuple (ops to apply to q0, ops to apply to q1)."""
+        return self.post_q0, self.post_q1
+
+    def on(self, q0: ops.Qid, q1: ops.Qid) -> ops.Operation:
+        """Returns the operation that replaces the two qubit gate."""
+        if self.swap_qubits:
+            return self.two_qubit_gate(q1, q0)
+        return self.two_qubit_gate(q0, q1)
+
+
+@frozen
+class SameGateGauge(Gauge):
+    """Same as ConstantGauge but the new two-qubit gate equals the old gate."""
+
+    pre_q0: Tuple[ops.Gate, ...] = field(
+        default=(), converter=lambda g: (g,) if isinstance(g, ops.Gate) else tuple(g)
+    )
+    pre_q1: Tuple[ops.Gate, ...] = field(
+        default=(), converter=lambda g: (g,) if isinstance(g, ops.Gate) else tuple(g)
+    )
+    post_q0: Tuple[ops.Gate, ...] = field(
+        default=(), converter=lambda g: (g,) if isinstance(g, ops.Gate) else tuple(g)
+    )
+    post_q1: Tuple[ops.Gate, ...] = field(
+        default=(), converter=lambda g: (g,) if isinstance(g, ops.Gate) else tuple(g)
+    )
+    swap_qubits: bool = False
+
+    def sample(self, gate: ops.Gate, prng: np.random.Generator) -> ConstantGauge:
+        return ConstantGauge(
+            two_qubit_gate=gate,
+            pre_q0=self.pre_q0,
+            pre_q1=self.pre_q1,
+            post_q0=self.post_q0,
+            post_q1=self.post_q1,
+            swap_qubits=self.swap_qubits,
+        )
+
+
+def _select(choices: Sequence[Gauge], probabilites: np.ndarray, prng: np.random.Generator) -> Gauge:
+    return choices[prng.choice(len(choices), p=probabilites)]
+
+
+@dataclass(frozen=True)
+class GaugeSelector:
+    """Samples a gauge from a list of gauges."""
+
+    gauges: Sequence[Gauge]
+
+    @functools.cached_property
+    def _weights(self) -> np.ndarray:
+        weights = np.array([g.weight() for g in self.gauges])
+        return weights / np.sum(weights)
+
+    def __call__(self, prng: np.random.Generator) -> Gauge:
+        """Randomly selects a gauge with probability proportional to its weight."""
+        return _select(self.gauges, self._weights, prng)
+
+
+@transformer_api.transformer
+class GaugeTransformer:
+    def __init__(
+        self,
+        # target can be either a specific gate, gatefamily or gateset
+        # which allows matching parametric gates.
+        target: Union[ops.Gate, ops.Gateset, ops.GateFamily],
+        gauge_selector: Callable[[np.random.Generator], Gauge],
+    ) -> None:
+        """Constructs a GaugeTransformer.
+
+        Args:
+            target: Target two-qubit gate, a gate-family or a gate-set of two-qubit gates.
+            gauge_selector: A callable that takes a numpy random number generator
+                as an argument and returns a Gauge.
+        """
+        self.target = ops.GateFamily(target) if isinstance(target, ops.Gate) else target
+        self.gauge_selector = gauge_selector
+
+    def __call__(
+        self,
+        circuit: circuits.AbstractCircuit,
+        *,
+        context: Optional[transformer_api.TransformerContext] = None,
+        prng: Optional[np.random.Generator] = None,
+    ) -> circuits.AbstractCircuit:
+        rng = np.random.default_rng() if prng is None else prng
+        if context is None:
+            context = transformer_api.TransformerContext(deep=False)
+        if context.deep:
+            raise ValueError('GaugeTransformer cannot be used with deep=True')
+        new_moments = []
+        left: List[List[ops.Operation]] = []
+        right: List[List[ops.Operation]] = []
+        for moment in circuit:
+            left.clear()
+            right.clear()
+            center: List[ops.Operation] = []
+            for op in moment:
+                if isinstance(op, ops.TaggedOperation) and set(op.tags).intersection(
+                    context.tags_to_ignore
+                ):
+                    center.append(op)
+                    continue
+                if op.gate is not None and len(op.qubits) == 2 and op in self.target:
+                    gauge = self.gauge_selector(rng).sample(op.gate, rng)
+                    q0, q1 = op.qubits
+                    left.extend([g(q) for g in gs] for q, gs in zip(op.qubits, gauge.pre))
+                    center.append(gauge.on(q0, q1))
+                    right.extend([g(q) for g in gs] for q, gs in zip(op.qubits, gauge.post))
+                else:
+                    center.append(op)
+            if left:
+                new_moments.extend(_build_moments(left))
+            new_moments.append(center)
+            if right:
+                new_moments.extend(_build_moments(right))
+        return circuits.Circuit.from_moments(*new_moments)
+
+
+def _build_moments(operation_by_qubits: List[List[ops.Operation]]) -> List[List[ops.Operation]]:
+    """Builds moments from a list of operations grouped by qubits.
+
+    Returns a list of moments from a list whose ith element is a list of operations applied
+    to qubit i.
+    """
+    moments = []
+    for moment in itertools.zip_longest(*operation_by_qubits):
+        moments.append([op for op in moment if op is not None])
+    return moments

cirq/transformers/gauge_compiling/gauge_compiling_test.py

@@ -0,0 +1,41 @@
+# Copyright 2024 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 numpy as np
+import cirq
+from cirq.transformers.gauge_compiling import GaugeTransformer, CZGaugeTransformer
+
+
+def test_deep_transformation_not_supported():
+
+    with pytest.raises(ValueError, match="cannot be used with deep=True"):
+        _ = GaugeTransformer(target=cirq.CZ, gauge_selector=lambda _: None)(
+            cirq.Circuit(), context=cirq.TransformerContext(deep=True)
+        )
+
+
+def test_ignore_tags():
+    c = cirq.Circuit(cirq.CZ(*cirq.LineQubit.range(2)).with_tags('foo'))
+    assert c == CZGaugeTransformer(c, context=cirq.TransformerContext(tags_to_ignore={"foo"}))
+
+
+def test_target_can_be_gateset():
+    qs = cirq.LineQubit.range(2)
+    c = cirq.Circuit(cirq.CZ(*qs))
+    transformer = GaugeTransformer(
+        target=cirq.Gateset(cirq.CZ), gauge_selector=CZGaugeTransformer.gauge_selector
+    )
+    want = cirq.Circuit(cirq.Y.on_each(qs), cirq.CZ(*qs), cirq.X.on_each(qs))
+    assert transformer(c, prng=np.random.default_rng(0)) == want

cirq/transformers/gauge_compiling/gauge_compiling_test_utils.py

@@ -0,0 +1,83 @@
+# Copyright 2024 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 unittest.mock import patch
+import pytest
+
+import numpy as np
+
+import cirq
+from cirq.transformers.gauge_compiling import GaugeTransformer, GaugeSelector
+
+
+class GaugeTester:
+
+    two_qubit_gate: cirq.Gate
+    gauge_transformer: GaugeTransformer
+    must_fail: bool = False
+
+    @pytest.mark.parametrize(
+        ['generation_seed', 'transformation_seed'],
+        np.random.RandomState(0).randint(2**31, size=(5, 2)).tolist(),
+    )
+    def test_gauge_transformer(self, generation_seed, transformation_seed):
+        c = cirq.Circuit()
+        while not any(op.gate == self.two_qubit_gate for op in c.all_operations()):
+            c = cirq.testing.random_circuit(
+                qubits=3,
+                n_moments=3,
+                op_density=1,
+                gate_domain={self.two_qubit_gate: 2, cirq.X: 1, cirq.Y: 1, cirq.H: 1, cirq.Z: 1},
+                random_state=generation_seed,
+            )
+            generation_seed += 1
+        nc = self.gauge_transformer(c, prng=np.random.default_rng(transformation_seed))
+        if self.must_fail:
+            with pytest.raises(AssertionError):
+                cirq.testing.assert_circuits_have_same_unitary_given_final_permutation(
+                    nc, c, qubit_map={q: q for q in c.all_qubits()}
+                )
+        else:
+            cirq.testing.assert_circuits_have_same_unitary_given_final_permutation(
+                nc, c, qubit_map={q: q for q in c.all_qubits()}
+            )
+
+    @patch('cirq.transformers.gauge_compiling.gauge_compiling._select', autospec=True)
+    @pytest.mark.parametrize('seed', range(5))
+    def test_all_gauges(self, mock_select, seed):
+        assert isinstance(
+            self.gauge_transformer.gauge_selector, GaugeSelector
+        ), 'When using a custom selector, please override this method to properly test all gauges'
+        c = cirq.Circuit(self.two_qubit_gate(cirq.LineQubit(0), cirq.LineQubit(1)))
+        prng = np.random.default_rng(seed)
+        for gauge in self.gauge_transformer.gauge_selector.gauges:
+            mock_select.return_value = gauge
+            assert self.gauge_transformer.gauge_selector(prng) == gauge
+            nc = self.gauge_transformer(c, prng=prng)
+
+            if self.must_fail:
+                with pytest.raises(AssertionError):
+                    _check_equivalent_with_error_message(c, nc, gauge)
+            else:
+                _check_equivalent_with_error_message(c, nc, gauge)
+
+
+def _check_equivalent_with_error_message(c: cirq.AbstractCircuit, nc: cirq.AbstractCircuit, gauge):
+    try:
+        cirq.testing.assert_circuits_have_same_unitary_given_final_permutation(
+            nc, c, qubit_map={q: q for q in c.all_qubits()}
+        )
+    except AssertionError as ex:
+        raise AssertionError(f"{gauge=} didn't result in an equivalent circuit") from ex