Add drop_diagonal_before_measurement transformer

[Vivek1106-04]

Description
Implemented the drop_diagonal_before_measurement transformer as requested in #4935.

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.