Support multi moment gauge compiling #7501

babacry · 2025-07-17T00:07:37Z

Support multi moment gauge transformation, where target moments will be gauged with new moments, e.g.,

        q₀: ... ───LG0───╭───────────╮────RG0───...
                         │           │
        q₁: ... ───LG1───┤  moments  ├────RG1───...
                         │   to be   │
        q₂: ... ───LG2───┤ gauged on ├────RG2───...
                         │           │
        q₃: ... ───LG3───╰───────────╯────RG3───...

A common MultiMomentGaugeTransformer class is defined.
Implemented the CPhase multi moment gauge CPhaseGaugeTransformerMM.
A moment is a target moment if it contains at least one target op (CZPowGate) and all its operations are supported by this transformer.
A couple of single qubit gates are supported for CPhaseGaugeTransformerMM, e.g., Pauli Gates, ZPowGate etc. If these gates are detected, gauge will be calculated accordingly. Users can tweak their desired gates by instantiate their own transformer by transformer = CPhaseGaugeTransformerMM(supported_gates=ops.Gateset(g1,g2,g3)). By default _SUPPORTED_GATESET are used.

Example:

  Input:
                  ┌──┐
    0: ───@────────@─────H───Rz(-0.255π)───────────@───────@───────
          │        │                               │       │
    1: ───@^0.2────┼@──────────────────────────────@^0.1───@───────
                   ││
    2: ───@────────@┼────────@─────────────@───────@───────@───────
          │         │        │             │       │       │
    3: ───@─────────@────────@^0.2─────────@^0.2───@───────@^0.2───
                  └──┘
    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────────────────
                       └──┘

Usage

case 1: default setup, any moment with CZPowGate and optionally with _SUPPORTED_GATES will be gauged (see example above),

cphase_transformer = CPhaseGaugeTransformerMM()
output_circuit = cphase_transformer(input_circuit)

case 2: Only CZPowGate-only moments will be gauged (see test_gauge_on_czpow_only_moments test case),

cphase_transformer = CPhaseGaugeTransformerMM(supported_gates=cirq.Gateset())
output_circuit = cphase_transformer(input_circuit)

codecov · 2025-07-17T04:34:36Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.57%. Comparing base (f9489cd) to head (ba7b4d7).
⚠️ Report is 17 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7501      +/-   ##
==========================================
+ Coverage   97.53%   97.57%   +0.03%     
==========================================
  Files        1095     1104       +9     
  Lines       99016   100914    +1898     
==========================================
+ Hits        96580    98466    +1886     
- Misses       2436     2448      +12

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

babacry · 2025-07-17T05:21:35Z

Hey @eliottrosenberg @NoureldinYosri , here is multi moment gauge compiling!! After evaluating multiple strategies, this approach proves to be optimal regarding both execution speed and future extensibility.

Note gauges could be automatically added to circuits with default setup, wonder if the default setup is suitable for most use cases? (see Example section and Usage section in the description above)

eliottrosenberg

LGTM! Great work, @babacry!

NoureldinYosri

@babacry is there a way to reuse code you wrote before in _PauliAndZPow ?

cirq-core/cirq/transformers/gauge_compiling/multi_moment_gauge_compiling.py

NoureldinYosri · 2025-07-18T18:49:36Z

cirq-core/cirq/transformers/gauge_compiling/multi_moment_cphase_gauge.py

+        else:
+            self.zpow = ops.ZPowGate(exponent=-left.exponent + self.zpow.exponent)
+
+    def _merge_right_zpow(self, right: ops.ZPowGate):


didn't you implement the logic for pulling gates somewhere else? or is this specific to these gates?

Not really, existing functions only allow for pulling Pauli gates through Clifford gates. However, the cphase gate is non-Clifford. When a Pauli operator is pushed through a cphase gate, it transforms into a combination of a Pauli operator and a Z-rotation. To handle this, the method tracks both the Pauli operator and the additional Z-rotation throughout the moments.

NoureldinYosri · 2025-07-18T22:48:16Z

cirq-core/cirq/transformers/gauge_compiling/multi_moment_cphase_gauge.py

+
+
+class CPhaseGaugeTransformerMM(MultiMomentGaugeTransformer):
+


lets make both MultiMomentGaugeTransformer and CPhaseGaugeTransformerMM be @attrs.frozen

then here we can do

supported_gates = attrs.field(default=_SUPPORTED_GATESET) target = attrs.field(default=_TARGET_GATESET, init=False, repr=False, eq=False, hash=False)

Frozen isn't very compatible with the level of flexibility we want to support, e.g., we want to allow the 3 use cases:

default setup that allows gauging on extra supported gates other than cphase gates

{required: cpahse, optional: _SUPPORTED_GATES}.

only gauge on cphase-only moments.

{required: cphase, optional: None}

users can specify what gates they would want to gauge on except cphase gates, e.g., user might want to gauge on moments with

{required: cphase, optional: X, Rz}.

Thus, I expose supported_gates in the init function of CPhaseGaugeTransformerMM.

See pr description for the first 2 use cases.

I am also okay with changing the user interface, what do you think?

you can still support these cases with an attrs.frozen, let me know if you need help structuring it

babacry · 2025-07-23T01:46:33Z

Thanks Nour for the insightful reivews!

We don't have a _PauliAndZPow support in cirq yet. If you are mentioning the PR I worked on to support a specific use case of multi moment gauge compiling, the pr is closed. The only pull-through support in cirq is pulling Pauli gates through Cliffords.

Could you help take another look? I've resolved some comments by committing changes, also left some comments for further discussions for the use of @attrs.frozen. @NoureldinYosri

NoureldinYosri

initial review of style ... I still haven't reviewed the logic of commuting gates

NoureldinYosri · 2025-07-30T02:52:47Z

cirq-core/cirq/transformers/gauge_compiling/multi_moment_cphase_gauge.py

+)
+
+
+class _PauliAndZPow:


lets make this a public attrs.frozen

NoureldinYosri · 2025-07-30T02:54:51Z

cirq-core/cirq/transformers/gauge_compiling/multi_moment_cphase_gauge.py

+
+
+class _PauliAndZPow:
+    """In pulling through, one qubit gate can be represented by a Pauli and an Rz gate.


Suggested change

"""In pulling through, one qubit gate can be represented by a Pauli and an Rz gate.

"""A gate represented by a Pauli followed by an Rz gate.

The order is --Pauli--ZPowGate--.

Attributes:

pauli: ...

zpow: ...

"""

NoureldinYosri · 2025-07-30T02:57:09Z

cirq-core/cirq/transformers/gauge_compiling/multi_moment_cphase_gauge.py

+    pauli: ops.Pauli | ops.IdentityGate = ops.I
+    zpow: ops.ZPowGate = ops.ZPowGate(exponent=0)
+
+    commuting_gates = {ops.I, ops.Z}  # I,Z Commute with ZPowGate and CZPowGate; X,Y anti-commute.


static class members are weired in python, lets make this a private global variable _COMMUTING_GATES

NoureldinYosri · 2025-07-30T02:57:25Z

cirq-core/cirq/transformers/gauge_compiling/multi_moment_cphase_gauge.py

+
+    commuting_gates = {ops.I, ops.Z}  # I,Z Commute with ZPowGate and CZPowGate; X,Y anti-commute.
+
+    def __init__(


you can drop this when you use @attrs.frozen

NoureldinYosri · 2025-07-30T03:03:11Z

cirq-core/cirq/transformers/gauge_compiling/multi_moment_cphase_gauge.py

+
+
+class CPhaseGaugeTransformerMM(MultiMomentGaugeTransformer):
+


you can still support these cases with an attrs.frozen, let me know if you need help structuring it

NoureldinYosri · 2025-07-30T03:04:14Z

cirq-core/cirq/transformers/gauge_compiling/multi_moment_cphase_gauge.py

+            [
+                rng.choice(
+                    np.array([ops.I, ops.X, ops.Y, ops.Z], dtype=ops.Gate),
+                    p=[0.25, 0.25, 0.25, 0.25],


rng.choice is uniform by default so you can remove the p parameter.

NoureldinYosri · 2025-07-30T03:06:07Z

cirq-core/cirq/transformers/gauge_compiling/multi_moment_cphase_gauge.py

+        return circuits.Moment(
+            [
+                rng.choice(
+                    np.array([ops.I, ops.X, ops.Y, ops.Z], dtype=ops.Gate),


this will create this array every time we call this method ... lets instead create a private global variable _PAULIS = ... and here do _PAULIS[np.choice(4)]

NoureldinYosri · 2025-07-30T03:06:19Z

cirq-core/cirq/transformers/gauge_compiling/multi_moment_cphase_gauge.py

+            ]
+        )
+
+    def gauge_on_moments(self, moments_to_gauge) -> list[circuits.Moment]:


NoureldinYosri · 2025-07-30T03:09:05Z

cirq-core/cirq/transformers/gauge_compiling/multi_moment_gauge_compiling.py

+        q₃: ... ───LG3───╰───────────╯────RG3───...
+    """
+
+    def __init__(


since this is an abstract class I don't think it needs an init

NoureldinYosri · 2025-07-30T03:11:44Z

cirq-core/cirq/transformers/gauge_compiling/multi_moment_gauge_compiling.py

+              are permitted within the gauge moments. If a moment contains a gate not found
+              in either target or supported_gates, it won't be gauged.
+        """
+        self.target = ops.GateFamily(target) if isinstance(target, ops.Gate) else target


either let mypy know about the existance of these properities by just declaring them

class MultiMomentGaugeTransformer: target: ops.GateFamily supported_gates: ops.GateFamily

or by making abstract methods that return them

github-actions bot added the size: L 250< lines changed <1000 label Jul 17, 2025

babacry force-pushed the gc_mm branch 7 times, most recently from c182892 to cc2b38a Compare July 17, 2025 04:21

babacry force-pushed the gc_mm branch 3 times, most recently from 32c5bb3 to 05cc48b Compare July 17, 2025 05:12

babacry marked this pull request as ready for review July 17, 2025 05:12

babacry requested review from vtomole and a team as code owners July 17, 2025 05:12

babacry requested a review from MichaelBroughton July 17, 2025 05:12

babacry force-pushed the gc_mm branch from 05cc48b to 7be2dd6 Compare July 17, 2025 05:14

babacry assigned eliottrosenberg and NoureldinYosri Jul 17, 2025

babacry mentioned this pull request Jul 17, 2025

Support multi-moment gauge compiling transformers. #7468

Open

babacry force-pushed the gc_mm branch from 7be2dd6 to 80412d6 Compare July 17, 2025 05:32

eliottrosenberg approved these changes Jul 17, 2025

View reviewed changes

eliottrosenberg requested a review from NoureldinYosri July 17, 2025 07:46

NoureldinYosri reviewed Jul 18, 2025

View reviewed changes

pavoljuhas added the priority/after-1.6 Leave for after the Cirq 1.6 release label Jul 22, 2025

Support multi moment gauge compiling

ecb67a0

babacry force-pushed the gc_mm branch from 80412d6 to a9be7d7 Compare July 23, 2025 00:22

remove rng from class var

ba7b4d7

babacry force-pushed the gc_mm branch from a9be7d7 to ba7b4d7 Compare July 23, 2025 00:41

babacry requested a review from NoureldinYosri July 23, 2025 01:46

NoureldinYosri requested changes Jul 30, 2025

View reviewed changes

babacry closed this Aug 6, 2025

babacry deleted the gc_mm branch August 6, 2025 01:10

babacry restored the gc_mm branch August 6, 2025 20:56

babacry reopened this Aug 6, 2025



		class CPhaseGaugeTransformerMM(MultiMomentGaugeTransformer):



		class _PauliAndZPow:
		"""In pulling through, one qubit gate can be represented by a Pauli and an Rz gate.

-    """In pulling through, one qubit gate can be represented by a Pauli and an Rz gate.
+    """A gate represented by a Pauli followed by an Rz gate.
+    The order is --Pauli--ZPowGate--.
+    Attributes:
+        pauli: ...
+        zpow: ...
+    """


		commuting_gates = {ops.I, ops.Z} # I,Z Commute with ZPowGate and CZPowGate; X,Y anti-commute.

		def __init__(

Support multi moment gauge compiling #7501

Are you sure you want to change the base?

Support multi moment gauge compiling #7501

Conversation

babacry commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

babacry commented Jul 17, 2025

Uh oh!

eliottrosenberg left a comment

Choose a reason for hiding this comment

Uh oh!

NoureldinYosri left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

babacry commented Jul 23, 2025

Uh oh!

NoureldinYosri left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

babacry commented Jul 17, 2025 •

edited

Loading

codecov bot commented Jul 17, 2025 •

edited

Loading