Add drop_diagonal_before_measurement transformer

[Vivek1106-04]

Description
Implemented the drop_diagonal_before_measurement transformer .

This transformer identifies diagonal gates (Z, S, T, CZ, etc.) that are immediately followed by measurements. Since diagonal gates commute with the computational basis measurement, they can be removed without affecting the outcome probabilities.

Implementation Details:

1. Pre-processing: Runs eject_z first to push Z gates as far right as possible (handling the Z-CZ commutation case described in the issue).
2. Safety Logic: Uses strict safety checks. A diagonal gate is only removed if ALL qubits it acts on are being measured.
   • Example: CZ(q0, q1) followed by Measure(q0) is NOT removed (to preserve q1's phase).
   • Example: CZ(q0, q1) followed by Measure(q0), Measure(q1) IS removed.

Testing:
Added diagonal_optimization_test.py covering:

• Single qubit removal (Z, S chains).
• Multi-qubit safety (CZ removal vs retention).
• Commutation blocking (Z blocked by X).
• The specific use cases mentioned in the issue.

Fixes #4935

[mhucka]

Discussed in Cirq Cynq: there is concern about whether this is valid for all types of measurements, or only valid for terminal measurements.

[Vivek1106-04]

Theoretical Justification & Safety Against Phase Kickback

To address the discussion regarding phase effects and safety, here is the theoretical basis for this optimization and how the implementation explicitly handles the "phase preservation" concerns.

1. The Core Principle: Commutation with Projectors A measurement in the computational basis corresponds to applying the projectors P0​=∣0⟩⟨0∣ and P1​=∣1⟩⟨1∣. Diagonal gates D (like Z, S, T, Rz​, CZ) are diagonal in this basis, meaning they commute with these projectors:
   [D,Pi​]=0

Because they commute, the probability distribution of the measurement outcomes is invariant under the application of D:
⟨ψ∣D†Pi​D∣ψ⟩=⟨ψ∣Pi​D†D∣ψ⟩=⟨ψ∣Pi​∣ψ⟩

(Since D is unitary, D†D=I).

2. Addressing the "Phase Loss" Concern (Safety Mechanism) It was raised in triage that phase is not always "lost" upon measurement. This is correct in the context of entanglement and phase kickback, and my implementation explicitly guards against this.

   The Danger: If we have a multi-qubit diagonal gate like CZ(q0​,q1​) and we only measure q1​, the phase interaction Z is "kicked back" onto the unmeasured qubit q0​ (depending on q1​'s state). Removing the CZ here would corrupt the state of q0​.

   The Solution: The transformer uses a strict all() check:

if all(q in measured_qubits for q in op.qubits):
    # Only remove if ALL entangled partners are being measured.

This ensures we never remove a gate that is needed to kick phase back to a surviving qubit.

3. Mid-Circuit Measurements & Global Phase For the measured qubits themselves, the measurement collapses the state to ∣0⟩ or ∣1⟩. While a preceding Z gate might technically leave the post-measurement state as −∣1⟩ instead of ∣1⟩, this difference is a Global Phase on the collapsed subspace. Since global phase is physically unobservable, operations following the measurement (mid-circuit) will behave identically regardless of whether the diagonal gate was present.

Summary: The transformer is safe because it only removes diagonal gates when all their logical influence (phase) flows into a measurement that discards it, preventing any corruption of unmeasured wires via entanglement.

[codrut3]

Following up on the discussion in the sync meeting, with the condition that all qubits acted on by the gate are measured, it seems to me ok to remove the gate mid-circuit.

My proof is like this: if there are $n$ qubits with $N := 2^n$, the state just before the gate is applied can be written as a linear combination of basis states:
$\sum_{k=0}^{N - 1} \alpha_k |k\rangle$.
Assume the gate is on qubits $1,2,\ldots, m$. Because the gate is diagonal, applying the gate multiplies $\alpha_k$ by a value $\beta_{k \mod 2^m}$, so we get a state:
$\sum_{k=0}^{N - 1} \alpha_k\beta_{k \mod 2^m} |k\rangle.$
If we measure the first $m$ qubits and get a value $y$, then only the basis states with $k \mod 2^m = y$ remain after measurement:
$\sum_{k\mod 2^m = y} \alpha_k\beta_y |k\rangle,$
and we can factor out $\beta_y$:
$\beta_y\left(\sum_{k\mod 2^m = y} \alpha_k |k\rangle\right).$

So in the end the gate + measurement only changes global phase.

About the implementation, I am concerned that _is_diagonal is expensive because it computes the unitary matrix and checks it is close to a diagonal matrix. This method is called for all operations in the circuit. My suggestion would be to remove only gates Z and CZ, and don't attempt to compute the unitary. For other gates, eject_z is ineffective anyway.

[Vivek1106-04]

@codrut3 thanks for your review , i will make changes .

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.57%. Comparing base (1467a32) to head (3125991).
⚠️ Report is 8 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff            @@
##             main    #7790    +/-   ##
========================================
  Coverage   99.57%   99.57%            
========================================
  Files        1102     1104     +2     
  Lines       98638    98876   +238     
========================================
+ Hits        98218    98455   +237     
- Misses        420      421     +1     

☔ 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.

[codrut3]

Perhaps _is_z_or_cz_pow_gate is a better name because it conveys better what it checks.

[codrut3]

The docstring should be updated to reflect the code. A diagonal gate is dropped only if all its qubits are measured. So the CZ(q0, q1) - Z(q1) - measure(q1) example is not correct, because the CZ gate can't be removed. If q0 is also measured then it can be removed.

[codrut3]

This should still include the CZ gate.

[codrut3]

ALL

[codrut3]

Can you add a test for this? A CZ gate followed by a diagonal 4x4 unitary followed by measurement on both qubits.

[codrut3]

Update the docstring: the CZ gate can't be removed if only q1 is measured

[codrut3]

Clarify that only Z, CZ and their powers are removed.

[codrut3]

Thank you for this PR, @Vivek1106-04 ! I left some comments, but someone from the Cirq team needs to review. @pavoljuhas maybe you can have a look?

[Vivek1106-04]

"Done! I updated the docstrings and added the test for unrecognized gates.

I also added a test_diagonal_gates_commute_before_measurement case just to double-check that the commutation logic holds up when multiple diagonal gates are stacked. Let me know if that looks good."