Add exact Clifford-to-Pauli-exponent decomposition

Cargo.toml

@@ -5,6 +5,7 @@ members = [
     "paulimer",
     "paulimer/bindings/python",
     "pauliverse",
+    "test-utils/dense-oracle",
     "deq/deq_runtime",
     "deq/deq_decoder_abi",
     "deq/deq_decoder_abi/reference_plugin",

README.md

@@ -12,7 +12,7 @@ This repository contains several interconnected crates:
 
 - [binar](binar): A high-performance bit manipulation library providing bit vectors, bit matrices, and bitwise operations over GF(2).
 - [paulimer](paulimer): A library for Pauli operators and Clifford gates, built on binar.
-- [pauliverse](pauliverse): Fast stabilizer simulators.
+- [pauliverse](pauliverse): Fast stabilizer simulators, including exact global-phase tracking (`PhasedOutcomeCompleteSimulation`) for verifying parameterised circuits.
 - [deq](deq): A dynamic and generic QEC decoding system, including the `.deq` DSL, transpiler, JIT runtime (Rust), CLI, and an anywidget-based visualizer.
 
 ### Python Bindings
@@ -136,6 +136,26 @@ let image = clifford.image(&x0);
 assert_eq!(image, "XX".parse::<DensePauli>().unwrap());
 ```
 
+### Stabilizer Simulation (pauliverse)
+
+```rust
+use pauliverse::{PhasedOutcomeCompleteSimulation, Simulation};
+use paulimer::{SparsePauli, UnitaryOp};
+
+// Track the exact global phase while simulating all measurement-outcome branches.
+let mut sim = PhasedOutcomeCompleteSimulation::new(2);
+sim.unitary_op(UnitaryOp::Hadamard, &[0]);
+sim.unitary_op(UnitaryOp::Hadamard, &[1]);
+
+// Apply a symbolic rotation e^{i·alpha·Z0Z1} around a higher-weight (two-qubit) Pauli.
+let alpha = sim.allocate_symbolic_angle();
+sim.symbolic_pauli_exp(&"Z0 Z1".parse::<SparsePauli>().unwrap(), alpha);
+```
+
+The phase-aware `phased_action` of two circuits can then be compared for exact equality — see the
+[pauliverse README](pauliverse/README.md) and the Python
+[example notebooks](paulimer/bindings/python/examples).
+
 ## Benchmarks
 
 This repository uses [Criterion](https://github.com/bheisler/criterion.rs) for Rust benchmarks and [ASV](https://asv.readthedocs.io/) for Python benchmarks.

paulimer/Cargo.toml

@@ -39,6 +39,7 @@ criterion = { version = "0.5", features = ["html_reports"] }
 proptest = "1.0"
 serde_json = "1.0"
 jsonschema = { version = "0.29" }
+dense-oracle = { path = "../test-utils/dense-oracle" }
 
 [[bench]]
 name = "pauli_benchmark"

paulimer/README.md

@@ -21,6 +21,9 @@ the building blocks for stabilizer quantum mechanics and quantum error correctio
 - **Clifford Unitaries**: Efficient representation enabling fast operations
   - [`CliffordUnitary`]: O(n²) Pauli conjugation via binary symplectic matrix
   - Supports all standard Clifford gates (H, S, CNOT, etc.)
+  - [`clifford_to_pauli_exponents`]: exact decomposition into `π/4` Pauli exponents (the full
+    tableau, including image signs), so replaying it with exact phase tracking yields a well-defined
+    global phase
 
 Based on algorithms from [arXiv:2309.08676](https://arxiv.org/abs/2309.08676).
 
@@ -94,6 +97,15 @@ assert_eq!(image, "XX".parse::<DensePauli>().unwrap());
 let mut circuit = CliffordUnitary::identity(2);
 circuit.left_mul(UnitaryOp::Hadamard, &[0]);
 circuit.left_mul(UnitaryOp::ControlledX, &[0, 1]);
+
+// Decompose a Clifford into an ordered product of π/4 Pauli exponents (exact, sign-preserving)
+use paulimer::clifford::clifford_to_pauli_exponents;
+let exponents = clifford_to_pauli_exponents(&circuit);
+let mut rebuilt = CliffordUnitary::identity(2);
+for pauli in &exponents {
+    rebuilt.left_mul_pauli_exp(pauli);
+}
+assert_eq!(rebuilt, circuit);
 ```
 
 ## When to Use Each Type
@@ -171,6 +183,7 @@ Key documentation:
 - [`SparsePauli`](src/pauli/sparse.rs) - Sparse Pauli representation for large systems
 - [`PauliGroup`](src/pauli_group.rs) - Subgroup operations and stabilizer groups
 - [`CliffordUnitary`](src/clifford.rs) - Clifford gates and Pauli conjugation
+- [`clifford_to_pauli_exponents`](src/clifford/decomposition.rs) - Exact decomposition of a Clifford into `π/4` Pauli exponents
 - [Trait documentation](src/lib.rs) - `Pauli`, `Clifford`, and other core traits
 
 ## Contributing

paulimer/bindings/python/README.md

@@ -29,16 +29,71 @@ sim.apply_unitary(paulimer.UnitaryOpcode.ControlledX, [0, 1])
 sim.measure(paulimer.SparsePauli("Z0"))
 ```
 
+### Verifying parameterised circuits with symbolic angles
+
+`PhasedOutcomeCompleteSimulation` tracks the exact global phase, so two circuits that share the same
+free rotation angles can be checked for exact equality — even for exponents of higher-weight Paulis:
+
+```python
+from paulimer import PhasedOutcomeCompleteSimulation, SparsePauli, UnitaryOpcode
+
+
+def prepared_action(build):
+    sim = PhasedOutcomeCompleteSimulation(2)
+    for qubit in range(2):
+        sim.apply_unitary(UnitaryOpcode.Hadamard, [qubit])  # |++>
+    build(sim)
+    return sim.phased_action([], [0, 1])  # state-preparation action
+
+
+def direct(sim):  # e^{i alpha Z0 Z1} |++>
+    alpha = sim.allocate_symbolic_angle()
+    sim.apply_symbolic_pauli_exp(SparsePauli("Z_0 Z_1"), alpha)
+
+
+def conjugated(sim):  # CNOT . e^{i alpha Z1} . CNOT |++>
+    sim.apply_unitary(UnitaryOpcode.ControlledX, [0, 1])
+    alpha = sim.allocate_symbolic_angle()
+    sim.apply_symbolic_pauli_exp(SparsePauli("Z_1"), alpha)
+    sim.apply_unitary(UnitaryOpcode.ControlledX, [0, 1])
+
+
+assert prepared_action(direct).is_equivalent(prepared_action(conjugated))
+```
+
+### Decomposing a Clifford into pi/4 Pauli exponents
+
+`CliffordUnitary.to_pauli_exponents()` returns an ordered product of `pi/4` Pauli exponents that
+reproduces the Clifford exactly, including the Pauli-image signs — so replaying it with exact phase
+tracking yields a well-defined global phase:
+
+```python
+from paulimer import CliffordUnitary, UnitaryOpcode
+
+clifford = CliffordUnitary.identity(2)
+clifford.left_mul(UnitaryOpcode.Hadamard, [0])
+clifford.left_mul(UnitaryOpcode.ControlledX, [0, 1])
+
+exponents = clifford.to_pauli_exponents()  # list[SparsePauli], each factor exp(+-i pi/4 P)
+
+rebuilt = CliffordUnitary.identity(2)
+for pauli in exponents:
+    rebuilt.left_mul_pauli_exp(pauli)
+assert rebuilt == clifford
+```
+
 ## Features
 
 - **DensePauli / SparsePauli** - Pauli operators with phase tracking and multiplication
 - **CliffordUnitary** - Clifford gates with conjugation and composition
+  (including `to_pauli_exponents()`, an exact decomposition into `pi/4` Pauli exponents)
 - **PauliGroup** - Group operations including membership testing and factorization
 - **Stabilizer Simulation** - Noiseless (OutcomeComplete, OutcomeFree, OutcomeSpecific) and noisy (Faulty) modes
+- **PhasedOutcomeCompleteSimulation** - Outcome-complete simulation that additionally tracks the exact global phase, enabling exact equality checking of parameterised (symbolic-angle) circuits
 
 ## Use Cases
 
-Designed for quantum error correction research, including stabilizer circuit analysis and Clifford circuit verification.
+Designed for quantum error correction research, including stabilizer circuit analysis and Clifford circuit verification. `PhasedOutcomeCompleteSimulation` extends this to exact verification of non-stabilizer circuits built from symbolic Pauli rotations `e^{i alpha P}`.
 
 ## Performance