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

cirq/transformers/gauge_compiling/multi_moment_cphase_gauge_test.py

@@ -0,0 +1,243 @@
+# 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 numpy as np
+import pytest
+
+import cirq
+from cirq import I, X, Y, Z, ZPowGate
+from cirq.transformers.gauge_compiling.multi_moment_cphase_gauge import (
+    _PauliAndZPow,
+    CPhaseGaugeTransformerMM,
+)
+
+
+def test_gauge_on_single_cphase():
+    """Test case.
+    Input:
+    0: ───@───────
+          │
+    1: ───@^0.2───
+    Example output:
+    0: ───X───@────────PhXZ(a=0,x=1,z=0)───
+              │
+    1: ───I───@^-0.2───Z^0.2───────────────
+    """
+    q0, q1 = cirq.LineQubit.range(2)
+
+    input_circuit = cirq.Circuit(cirq.Moment(cirq.CZ(q0, q1) ** 0.2))
+
+    class _TestCPhaseGaugeTransformerMM(CPhaseGaugeTransformerMM):
+        def sample_left_moment(
+            self,
+            active_qubits: frozenset[cirq.Qid],
+            rng: np.random.Generator = np.random.default_rng(),
+        ) -> cirq.Moment:
+            return cirq.Moment(g1(q0), g2(q1))
+
+    for g1 in [X, Y, Z, I]:
+        for g2 in [X, Y, Z, I]:  # Test with all possible samples of the left moment.
+            cphase_transformer = _TestCPhaseGaugeTransformerMM()
+            output_circuit = cphase_transformer(input_circuit)
+            cirq.testing.assert_circuits_have_same_unitary_given_final_permutation(
+                input_circuit, output_circuit, {q: q for q in input_circuit.all_qubits()}
+            )
+
+
+def test_gauge_on_cz_moments():
+    """Test case.
+    Input:
+              ┌──┐
+    0: ───@────@─────H───────@───@───
+          │    │             │   │
+    1: ───@────┼@────────────@───@───
+               ││
+    2: ───@────@┼────────@───@───@───
+          │     │        │   │   │
+    3: ───@─────@────────@───@───@───
+              └──┘
+    Example output:
+                  ┌──┐
+    0: ───X───@────@─────PhXZ(a=0,x=1,z=1)──────H───X───────@───@───PhXZ(a=0,x=1,z=2)────
+              │    │                                        │   │
+    1: ───I───@────┼@────Z──────────────────────────X───────@───@───PhXZ(a=2,x=1,z=-2)───
+                   ││
+    2: ───Y───@────@┼────PhXZ(a=1.5,x=1,z=-1)───────Z───@───@───@───Z────────────────────
+              │     │                                   │   │   │
+    3: ───Z───@─────@────Z^0────────────────────────I───@───@───@───Z^0──────────────────
+                  └──┘
+    """
+    q0, q1, q2, q3 = cirq.LineQubit.range(4)
+    input_circuit = cirq.Circuit(
+        cirq.Moment(cirq.CZ(q0, q1), cirq.CZ(q2, q3)),
+        cirq.Moment(cirq.CZ(q0, q2), cirq.CZ(q1, q3)),
+        cirq.Moment(cirq.H(q0)),
+        cirq.Moment(cirq.CZ(q2, q3)),
+        cirq.Moment(cirq.CZ(q0, q1), cirq.CZ(q2, q3)),
+        cirq.Moment(cirq.CZ(q0, q1), cirq.CZ(q2, q3)),
+    )
+    transformer = CPhaseGaugeTransformerMM()
+
+    output_circuit = transformer(input_circuit)
+    cirq.testing.assert_circuits_have_same_unitary_given_final_permutation(
+        input_circuit, output_circuit, {q: q for q in input_circuit.all_qubits()}
+    )
+
+
+def test_is_target_moment():
+    q0, q1, q2 = cirq.LineQubit.range(3)
+
+    target_moments = [
+        cirq.Moment(cirq.CZ(q0, q1) ** 0.2),
+        cirq.Moment(cirq.CZ(q0, q1) ** 0.2, cirq.X(q2)),
+    ]
+    non_target_moments = [
+        cirq.Moment(cirq.X(q0), cirq.Y(q1)),
+        cirq.Moment(cirq.CZ(q0, q1) ** 0.2, cirq.Rz(rads=-0.8).on(q2)),
+        cirq.Moment(cirq.CZ(q0, q1).with_tags("ignore")),
+        cirq.Moment(cirq.CZ(q0, q1)).with_tags("ignore"),
+    ]
+    cphase_transformer = CPhaseGaugeTransformerMM(supported_gates=cirq.Gateset(cirq.Pauli))
+    for m in target_moments:
+        assert cphase_transformer.is_target_moment(m)
+    for m in non_target_moments:
+        assert not cphase_transformer.is_target_moment(
+            m, cirq.TransformerContext(tags_to_ignore={'ignore'})
+        )
+
+
+def test_gauge_on_cphase_moments():
+    """Test case.
+    Input:
+                  ┌──┐
+    0: ───@────────@─────H───Rz(-0.255π)───────────@───────@───────
+          │        │                               │       │
+    1: ───@^0.2────┼@──────────────────────────────@^0.1───@───────
+                   ││
+    2: ───@────────@┼────────@─────────────@───────@───────@───────
+          │         │        │             │       │       │
+    3: ───@─────────@────────@^0.2─────────@^0.2───@───────@^0.2───
+                  └──┘
+    Example output:
+                       ┌──┐
+    0: ───Y───@─────────@─────PhXZ(a=0,x=1,z=0)───H───X───Rz(0.255π)────────────@───────@────────PhXZ(a=0,x=1,z=1.1)───
+              │         │                                                       │       │
+    1: ───I───@^-0.2────┼@────Z^0.2───────────────────Y─────────────────────────@^0.1───@────────PhXZ(a=0,x=1,z=0.1)───
+                        ││
+    2: ───X───@─────────@┼────PhXZ(a=0,x=1,z=1)───────X───@────────────@────────@───────@────────PhXZ(a=0,x=1,z=0)─────
+              │          │                                │            │        │       │
+    3: ───Z───@──────────@────I───────────────────────I───@^-0.2───────@^-0.2───@───────@^-0.2───Z^-0.4────────────────
+                       └──┘
+    """  # noqa: E501
+    q0, q1, q2, q3 = cirq.LineQubit.range(4)
+    cphase_transformer = CPhaseGaugeTransformerMM()
+    for seed in range(5):
+        input_circuit = cirq.Circuit(
+            cirq.Moment(cirq.CZ(q0, q1) ** 0.2, cirq.CZ(q2, q3)),
+            cirq.Moment(cirq.CZ(q0, q2), cirq.CZ(q1, q3)),
+            cirq.Moment(cirq.H(q0)),
+            cirq.Moment(cirq.CZ(q2, q3) ** 0.2, cirq.Rz(rads=-0.8).on(q0)),
+            cirq.Moment(cirq.CZ(q2, q3) ** 0.2),
+            cirq.Moment(cirq.CZ(q0, q1) ** 0.1, cirq.CZ(q2, q3)),
+            cirq.Moment(cirq.CZ(q0, q1), cirq.CZ(q2, q3) ** 0.2),
+        )
+
+        output_circuit = cphase_transformer(input_circuit, rng_or_seed=seed)
+        cirq.testing.assert_circuits_have_same_unitary_given_final_permutation(
+            input_circuit, output_circuit, {q: q for q in input_circuit.all_qubits()}
+        )
+
+
+def test_gauge_on_czpow_only_moments():
+    q0, q1, q2 = cirq.LineQubit.range(3)
+
+    input_circuit = cirq.Circuit(cirq.Moment(cirq.CZ(q0, q1) ** 0.2, X(q2)))
+    cphase_transformer = CPhaseGaugeTransformerMM(supported_gates=cirq.Gateset())
+    output_circuit = cphase_transformer(input_circuit)
+
+    # Since X isn't in supported_gates, the moment won't be gauged.
+    assert input_circuit == output_circuit
+
+
+def test_gauge_on_supported_gates():
+    q0, q1, q2, q3 = cirq.LineQubit.range(4)
+    cphase_transformer = CPhaseGaugeTransformerMM()
+    for g1 in [X, Z**0.6, I, Z]:
+        for g2 in [Y, cirq.Rz(rads=0.2), Z**0.7]:
+            input_circuit = cirq.Circuit(
+                cirq.Moment(cirq.CZ(q0, q1) ** 0.2, g1(q2), g2(q3)),
+                cirq.Moment(cirq.CZ(q0, q2), g2(q1), g1(q3)),
+            )
+            output_circuit = cphase_transformer(input_circuit)
+            cirq.testing.assert_circuits_have_same_unitary_given_final_permutation(
+                input_circuit, output_circuit, {q: q for q in input_circuit.all_qubits()}
+            )
+
+
+def test_gauge_on_unsupported_gates():
+    q0, q1, q2, q3 = cirq.LineQubit.range(4)
+
+    cphase_transformer = CPhaseGaugeTransformerMM(supported_gates=cirq.Gateset(cirq.CNOT))
+    with pytest.raises(ValueError, match="Gate type .* is not supported."):
+        cphase_transformer(cirq.Circuit(cirq.CNOT(q0, q1), cirq.CZ(q2, q3)))
+
+
+def test_pauli_and_phxz_util_str():
+    assert str(_PauliAndZPow(pauli=X)) == '─X──Z**0─'
+    assert str(_PauliAndZPow(pauli=X, zpow=Z**0.1)) == '─X──Z**0.1─'
+
+
+def test_pauli_and_phxz_util_gate_merges():
+    """Tests _PauliAndZPow's merge_left() and merge_right()."""
+    for left_pauli in [X, Y, Z, I]:
+        for right_pauli in [X, Y, Z, I]:
+            left = _PauliAndZPow(pauli=left_pauli, zpow=ZPowGate(exponent=0.2))
+            right = _PauliAndZPow(pauli=right_pauli, zpow=ZPowGate(exponent=0.6))
+            merge1 = right.merge_left(left)
+            merge2 = left.merge_right(right)
+
+            assert np.allclose(
+                cirq.unitary(merge1.to_single_qubit_gate()),
+                cirq.unitary(merge2.to_single_qubit_gate()),
+            )
+            q = cirq.LineQubit(0)
+            cirq.testing.assert_allclose_up_to_global_phase(
+                cirq.unitary(
+                    cirq.Circuit(
+                        left.to_single_qubit_gate().on(q), right.to_single_qubit_gate().on(q)
+                    )
+                ),
+                cirq.unitary(merge1.to_single_qubit_gate()),
+                atol=1e-6,
+            )
+
+
+def test_pauli_and_phxz_util_to_1q_gate():
+    """Tests _PauliAndZPow.to_single_qubit_gate()."""
+    q = cirq.LineQubit(0)
+    for pauli in [cirq.X, cirq.Y, cirq.Z, cirq.I]:
+        for zpow in [cirq.ZPowGate(exponent=exp) for exp in [0, 0.1, 0.5, 1, 10.2]]:
+            cirq.testing.assert_circuits_have_same_unitary_given_final_permutation(
+                cirq.Circuit(pauli(q), zpow(q)),
+                cirq.Circuit(_PauliAndZPow(pauli=pauli, zpow=zpow).to_single_qubit_gate().on(q)),
+                {q: q},
+            )
+
+
+def test_deep_not_supported():
+    with pytest.raises(ValueError, match="GaugeTransformer cannot be used with deep=True"):
+        t = CPhaseGaugeTransformerMM()
+        t(cirq.Circuit(), context=cirq.TransformerContext(deep=True))

cirq/transformers/gauge_compiling/multi_moment_gauge_compiling.py

@@ -0,0 +1,151 @@
+# 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.
+
+"""Defines the abstraction for multi-moment gauge compiling as a cirq transformer."""
+
+import abc
+
+import attrs
+import numpy as np
+
+from cirq import circuits, ops
+from cirq.transformers import transformer_api
+
+
+@transformer_api.transformer
+@attrs.frozen
+class MultiMomentGaugeTransformer(abc.ABC):
+    """A gauge transformer that wraps target blocks of moments with single-qubit gates.
+
+    In detail, a "gauging moment" of single-qubit gates is inserted before a target block of
+    moments. These gates are then commuted through the block, resulting in a corresponding
+    moment of gates after it.
+
+        q₀: ... ───LG0───╭───────────╮────RG0───...
+                         │           │
+        q₁: ... ───LG1───┤  moments  ├────RG1───...
+                         │   to be   │
+        q₂: ... ───LG2───┤ gauged on ├────RG2───...
+                         │           │
+        q₃: ... ───LG3───╰───────────╯────RG3───...
+
+    Attributes:
+        target: The target gate, gate family or gateset, must exist in each of the moment in
+          the "moments to be gauged".
+        supported_gates: The gates that are supported in the "moments to be gauged".
+    """
+
+    target: ops.GateFamily | ops.Gateset
+    supported_gates: ops.GateFamily | ops.Gateset
+
+    @abc.abstractmethod
+    def sample_left_moment(
+        self, active_qubits: frozenset[ops.Qid], prng: np.random.Generator
+    ) -> circuits.Moment:
+        """Samples a random single-qubit moment to be inserted before the target block.
+
+        Args:
+            active_qubits: The qubits on which the sampled gates should be applied.
+            prng: A pseudorandom number generator.
+
+        Returns:
+            The sampled moment.
+        """
+
+    @abc.abstractmethod
+    def gauge_on_moments(
+        self, moments_to_gauge: list[circuits.Moment], prng: np.random.Generator
+    ) -> list[circuits.Moment]:
+        """Gauges a block of moments.
+
+        Args:
+            moments_to_gauge: A list of moments to be gauged.
+            prng: A pseudorandom number generator.
+
+        Returns:
+            A list of moments after gauging.
+        """
+
+    def is_target_moment(
+        self, moment: circuits.Moment, context: transformer_api.TransformerContext | None = None
+    ) -> bool:
+        """Checks if a moment is a target for gauging.
+
+        A moment is a target moment if it contains at least one target op and
+        all its operations are supported by this transformer.
+        """
+        # skip the moment if the moment is tagged to be ignored
+        if context and set(moment.tags).intersection(context.tags_to_ignore):
+            return False
+
+        has_target_gates: bool = False
+        for op in moment:
+            if (
+                context
+                and isinstance(op, ops.TaggedOperation)
+                and set(op.tags).intersection(context.tags_to_ignore)
+            ):  # skip the moment if the op is tagged to be ignored
+                return False
+            if op.gate:
+                if op in self.target:
+                    has_target_gates = True
+                elif op not in self.supported_gates:
+                    return False
+        return has_target_gates
+
+    def __call__(
+        self,
+        circuit: circuits.AbstractCircuit,
+        *,
+        context: transformer_api.TransformerContext | None = None,
+        rng_or_seed: np.random.Generator | int | None = None,
+    ) -> circuits.AbstractCircuit:
+        """Apply the transformer to the given circuit.
+
+        Args:
+            circuit: The circuit to transform.
+            context: `cirq.TransformerContext` storing common configurable options for transformers.
+            prng: A pseudorandom number generator.
+
+        Returns:
+            The transformed circuit.
+
+        Raises:
+            ValueError: if the TransformerContext has deep=True.
+
+        """
+        if context is None:
+            context = transformer_api.TransformerContext(deep=False)
+        if context.deep:
+            raise ValueError('GaugeTransformer cannot be used with deep=True')
+        rng = (
+            rng_or_seed
+            if isinstance(rng_or_seed, np.random.Generator)
+            else np.random.default_rng(rng_or_seed)
+        )
+
+        output_moments: list[circuits.Moment] = []
+        moments_to_gauge: list[circuits.Moment] = []
+        for moment in circuit:
+            if self.is_target_moment(moment, context):
+                moments_to_gauge.append(moment)
+            else:
+                if moments_to_gauge:
+                    output_moments.extend(self.gauge_on_moments(moments_to_gauge, rng))
+                    moments_to_gauge.clear()
+                output_moments.append(moment)
+        if moments_to_gauge:
+            output_moments.extend(self.gauge_on_moments(moments_to_gauge, rng))
+
+        return circuits.Circuit.from_moments(*output_moments)

cirq/transformers/gauge_compiling/sqrt_cz_gauge.py

@@ -16,8 +16,9 @@
 
 from __future__ import annotations
 
+from collections.abc import Sequence
 from numbers import Real
-from typing import Sequence, TYPE_CHECKING
+from typing import TYPE_CHECKING
 
 from cirq.ops import CZ, CZPowGate, Gate, Gateset, S, X
 from cirq.transformers.gauge_compiling.gauge_compiling import (

cirq/transformers/heuristic_decompositions/gate_tabulation_math_utils.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import itertools
-from typing import Sequence
+from collections.abc import Sequence
 
 import numpy as np
 

cirq/transformers/heuristic_decompositions/gate_tabulation_math_utils_test.py

@@ -14,15 +14,15 @@ from cirq.transformers.heuristic_decompositions.gate_tabulation_math_utils impor
 )
 
 
-def test_weyl_chamber_mesh_spacing_too_small_throws_error():
+def test_weyl_chamber_mesh_spacing_too_small_throws_error() -> None:
     with pytest.raises(ValueError, match='may cause system to crash'):
         weyl_chamber_mesh(spacing=5e-4)
 
 
-def test_kak_vector_infidelity_ignore_equivalent_nontrivial():
+def test_kak_vector_infidelity_ignore_equivalent_nontrivial() -> None:
     x, y, z = np.pi / 4, 1, 0.5
-    kak_0 = cirq.kak_canonicalize_vector(x, y, z).interaction_coefficients
-    kak_1 = cirq.kak_canonicalize_vector(x - 1e-3, y, z).interaction_coefficients
+    kak_0 = np.asarray(cirq.kak_canonicalize_vector(x, y, z).interaction_coefficients)
+    kak_1 = np.asarray(cirq.kak_canonicalize_vector(x - 1e-3, y, z).interaction_coefficients)
 
     inf_check_equivalent = kak_vector_infidelity(kak_0, kak_1, False)
     inf_ignore_equivalent = kak_vector_infidelity(kak_0, kak_1, True)
@@ -30,7 +30,7 @@ def test_kak_vector_infidelity_ignore_equivalent_nontrivial():
     assert inf_check_equivalent < inf_ignore_equivalent
 
 
-def test_random_qubit_unitary_shape():
+def test_random_qubit_unitary_shape() -> None:
     rng = value.parse_random_state(11)
     actual = random_qubit_unitary((3, 4, 5), True, rng).ravel()
     rng = value.parse_random_state(11)
@@ -38,7 +38,7 @@ def test_random_qubit_unitary_shape():
     np.testing.assert_almost_equal(actual, expected)
 
 
-def test_random_qubit_default():
+def test_random_qubit_default() -> None:
     rng = value.parse_random_state(11)
     actual = random_qubit_unitary(randomize_global_phase=True, rng=rng).ravel()
     rng = value.parse_random_state(11)

cirq/transformers/heuristic_decompositions/two_qubit_gate_tabulation.py

@@ -17,9 +17,10 @@ with a product A k A."""
 
 from __future__ import annotations
 
+from collections.abc import Sequence
 from dataclasses import dataclass
 from functools import reduce
-from typing import NamedTuple, Sequence
+from typing import NamedTuple
 
 import numpy as np
 
@@ -109,7 +110,7 @@ class TwoQubitGateTabulation:
         success = infidelities[nearest_ind] < self.max_expected_infidelity
 
         # shape (n,2,2,2)
-        inner_gates = np.array(self.single_qubit_gates[nearest_ind])
+        inner_gates: np.ndarray = np.array(self.single_qubit_gates[nearest_ind])
 
         if inner_gates.size == 0:  # Only need base gate
             kR, kL, actual = _outer_locals_for_unitary(unitary, self.base_gate)

cirq/transformers/measurement_transformers.py

@@ -16,7 +16,8 @@ from __future__ import annotations
 
 import itertools
 from collections import defaultdict
-from typing import Any, cast, Iterable, Sequence, TYPE_CHECKING
+from collections.abc import Iterable, Sequence
+from typing import Any, cast, TYPE_CHECKING
 
 import numpy as np