[WIP] `PauliProductMeasurement` instruction #15126

ShellyGarion · 2025-10-05T14:15:14Z

Summary

Adds rust and python support for PauliProductMeasurement instructions. This is a fundamental operation in fault-tolerant quantum computing [1].

Close #15104
Co-authored by @alexanderivrii

References:

Daniel Litinski. "A Game of Surface Codes: Large-Scale Quantum Computing with Lattice Surgery", https://arxiv.org/abs/1808.02892

Details and comments

The implementation is similar to the existing handling of unitary gates.

In rust:

There is a new variant PauliProductMeasurement for PackedOperationType. This increases the total number of types to 7.
There is a new struct PauliProductMeasurement defined in operations.rs. Currently it stores

/// This class represents a PauliProductMeasurement instruction.
#[derive(Clone, Debug)]
#[repr(align(8))]
pub struct PauliProductMeasurement {
    /// The z-component of the pauli.
    pub z: Vec<bool>,
    /// The x-component of the pauli.
    pub x: Vec<bool>,
    /// The phase of the pauli. This is an integer modulo 4.
    pub phase: u8,
}

but we are considering bitpacking the data structure.

There is a new variant PPM of OperationRef.
The synthesis crate contains a function synthesize_ppm, which is used in HighLevelSynthesis transpiler pass to synthesize PauliProductMeasurement instructions (this is very similar to handling unitary gates) and is also exposed to Python (allowing to extract definition on the python side).

In python:

There is a "mirror" class PauliProductMeasurement, which can be instantiated from a Pauli object:

ppm = PauliProductMeasurement(Pauli("-XYIZ"))

qc = QuantumCircuit(6, 2)
qc.append(ppm, [0, 1, 2, 3], [0])

Internally, the pauli data (pauli.z, pauli.x, pauli.phase) is stored in the params field, allowing to easily pass it down to rust.
QPY serialization works
Visualization is done using the label attribute. Currently this just draws a box over relevant quantum and classical bits.
Default and custom labels are preserved correct;y

Note that we support pauli product measurement instructions based on Paulis with some "I"-terms (except for all-"I"), since we believe that this might simplify user workflows. However, for efficiency it would be better for the users to avoid creating "I"s, and we will try to document this clearly both in the docstring and the release note

ToDo (in this PR)

Write release note once the implementation is a bit more stable.
Port the class to rust, the quantum circuit generation should be based on [Pauli Evolution].(https://github.com/Qiskit/qiskit/blob/main/crates/circuit_library/src/pauli_evolution.rs).
Add Tests to check that transpiler passes that handle measurements do not fail.
Minor fix to visualization (to print “PauliProductMeasurement” and not “Pauliproductmeasurement”).
Handle QPY serialization.
Improve the PauliProductMeasurement data structure (at least in Rust).
Double-check that the endianness of Pauli is consistent with the one in SparseObservable.

ToDo (in follow-ups)

Let visualization draw the double-wire down to the classical register, like the standard measurements do.
Update the LitinskiTransformation pass to produce PPMs in addition to PPRs (pauli product rotations).
Rethink and improve transpiler passes involving measurement instructions
Qasm?

Co-authored-by: Alexander Ivrii <[email protected]>

coveralls · 2025-10-05T14:58:42Z

Pull Request Test Coverage Report for Build 18442497358

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

For more information on this, see Tracking coverage changes with pull request builds.
To avoid this issue with future PRs, see these Recommended CI Configurations.
For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

192 of 257 (74.71%) changed or added relevant lines in 18 files are covered.
186 unchanged lines in 10 files lost coverage.
Overall coverage remained the same at 88.222%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
crates/circuit/src/converters.rs	0	1	0.0%
crates/transpiler/src/passes/basis_translator/mod.rs	1	2	50.0%
crates/transpiler/src/passes/high_level_synthesis.rs	1	2	50.0%
crates/circuit/src/circuit_data.rs	0	2	0.0%
crates/circuit/src/dag_node.rs	0	2	0.0%
crates/transpiler/src/target/mod.rs	0	2	0.0%
qiskit/qpy/binary_io/circuits.py	4	6	66.67%
qiskit/circuit/library/pauli_product_measurement.py	34	37	91.89%
crates/circuit/src/circuit_instruction.rs	22	28	78.57%
crates/synthesis/src/pauli_product_measurement.rs	87	93	93.55%

Files with Coverage Reduction	New Missed Lines	%
crates/circuit/src/dag_circuit.rs	1	84.53%
crates/circuit/src/packed_instruction.rs	1	91.64%
crates/circuit/src/parameter/parameter_expression.rs	1	81.99%
crates/circuit/src/parameter/symbol_expr.rs	1	72.82%
crates/qasm2/src/lex.rs	1	92.54%
crates/transpiler/src/passes/unitary_synthesis.rs	1	92.4%
crates/transpiler/src/passes/optimize_1q_gates_decomposition.rs	15	91.4%
qiskit/visualization/circuit/text.py	17	93.62%
qiskit/circuit/quantumcircuit.py	73	94.34%
crates/transpiler/src/passes/basis_translator/mod.rs	75	82.9%

Totals
Change from base Build 18229727033:	0.0%
Covered Lines:	93380
Relevant Lines:	105847

💛 - Coveralls

* Conversions between rust and python classes * Synthesis of PauliProductMeasurement instructions * Exposing synthesis function to python * Usage of synthesis function in HLS * QPY support * Some additional python tests

Cryoris

The overall structure LGTM, my main comment is about the internal Pauli representation. Do we want to generally adopt a dense ZX formulation for Cliffords and PBC? If yes, we (1) need to ensure we can build the PPMs from the string output of the Litinski transformation, and (2) it would be nice to investigate bitpacking (e.g. bitvec package?).

Cryoris · 2025-10-13T09:32:13Z

qiskit/circuit/library/pauli_product_measurement.py

+        """
+        Args:
+            pauli: A tensor product of Pauli operators defining the measurement,
+                for example ``Pauli("XY")`` or ``Pauli("-XYIZ)``.


Suggested change

for example ``Pauli("XY")`` or ``Pauli("-XYIZ)``.

for example ``Pauli("XY")`` or ``Pauli("-XYIZ")``.

Cryoris · 2025-10-13T09:32:45Z

qiskit/circuit/library/pauli_product_measurement.py

+            While Paulis involving "I"-terms are fully supported, it is recommended to remove
+            "I"-terms from the Pauli when creating a ``PauliProductMeasurement`` instruction,


Suggested change

While Paulis involving "I"-terms are fully supported, it is recommended to remove

"I"-terms from the Pauli when creating a ``PauliProductMeasurement`` instruction,

While Paulis involving ``"I"``-terms are fully supported, it is recommended to remove

``"I"``-terms from the Pauli when creating a ``PauliProductMeasurement`` instruction,

Cryoris · 2025-10-13T09:33:30Z

qiskit/circuit/library/pauli_product_measurement.py

+
+        """
+
+        if not isinstance(pauli, Pauli):


We generally don't have these type checks in the circuit library -- the type hint is clear here so it's on the user to provide the right type.

Cryoris · 2025-10-13T09:44:53Z

test/python/circuit/library/test_ppm.py

+        with self.assertRaises(CircuitError):
+            _ = PauliProductMeasurement(Pauli(p))
+
+    @data("", "II", "-III")


Arguably "" is not the identity string 😉 A separate error here seems better.

Cryoris · 2025-10-13T09:47:39Z

test/python/circuit/library/test_ppm.py

+        qc3.append(PauliProductMeasurement(Pauli("XZ")), [4, 1], [0])
+
+        qc4 = QuantumCircuit(5, 2)
+        qc4.append(PauliProductMeasurement(Pauli("ZX")), [4, 1], [1])


It would be good to add a case here that checks that reverting the Pauli labels and qubit indices evaluates to True.

Cryoris · 2025-10-13T11:13:44Z

crates/circuit/src/operations.rs

    Instruction(&'a PyInstruction),
    Operation(&'a PyOperation),
    Unitary(&'a UnitaryGate),
+    PPM(&'a PauliProductMeasurement),


Could we spell PPM out? No other gates are abbreviated and it'll be more consistent with PauliEvolutionGate or PauliRotationGate.

Cryoris · 2025-10-13T11:22:54Z

crates/circuit/src/operations.rs

+#[repr(align(8))]
+pub struct PauliProductMeasurement {
+    /// The z-component of the pauli.
+    pub z: Vec<bool>,


Are there alternatives to storing boolean vectors, i.e. 1 byte per term if we'd only need 1 bit? E.g. the bitvec package seems to have a convenient interface. I assume @jakelishman has some opinions here 🙂

Cryoris · 2025-10-13T11:24:35Z

crates/circuit/src/operations.rs

+
+/// This class represents a PauliProductMeasurement instruction.
+#[derive(Clone, Debug)]
+#[repr(align(8))]


In the current format I don't think we need this, since bool and u8 are both a byte long. But if we change to bitvec or some bitpacking we might need to keep it?

Cryoris · 2025-10-13T11:34:36Z

crates/circuit/src/operations.rs

+/// This class represents a PauliProductMeasurement instruction.
+#[derive(Clone, Debug)]
+#[repr(align(8))]
+pub struct PauliProductMeasurement {


We'll need to construct the PPMs in the Rust Litinski transformation code, which currently outputs the Pauli in a sparse string format (sign, Paulistring, indices). If we use ZX bits as internal representation we'll also need a converter from Pauli string to ZX in Rust.

Cryoris · 2025-10-13T11:37:56Z

test/python/circuit/library/test_ppm.py

+        with self.assertRaises(CircuitError):
+            _ = PauliProductMeasurement(Pauli("XYZ")).inverse()
+
+    def test_qpy(self):


+1 for thinking of qpy 👍🏻 I guess for qasm export it'll just define the instruction?

ShellyGarion added 3 commits October 5, 2025 09:10

add PauliProductMeasurement class.

b3b80a7

Co-authored-by: Alexander Ivrii <[email protected]>

update init file

a62a155

add tests for pauli product measurement

ed9831e

ShellyGarion added this to the 2.3.0 milestone Oct 5, 2025

ShellyGarion added the fault tolerance related to fault tolerance compilation label Oct 5, 2025

fix definition, handle I in the lsb qubits, fix test

3d8556f

jakelishman assigned Cryoris Oct 8, 2025

alexanderivrii added 2 commits October 12, 2025 11:19

Implementing PauliProductMeasurement also in Rust

703c35b

* Conversions between rust and python classes * Synthesis of PauliProductMeasurement instructions * Exposing synthesis function to python * Usage of synthesis function in HLS * QPY support * Some additional python tests

cleanup and more tests

d3d0557

ShellyGarion added the Rust This PR or issue is related to Rust code in the repository label Oct 12, 2025

Cryoris reviewed Oct 13, 2025

View reviewed changes

	for example ``Pauli("XY")`` or ``Pauli("-XYIZ)``.
	for example ``Pauli("XY")`` or ``Pauli("-XYIZ")``.

		While Paulis involving "I"-terms are fully supported, it is recommended to remove
		"I"-terms from the Pauli when creating a ``PauliProductMeasurement`` instruction,

[WIP] PauliProductMeasurement instruction #15126

Are you sure you want to change the base?

[WIP] PauliProductMeasurement instruction #15126

Uh oh!

Conversation

ShellyGarion commented Oct 5, 2025 • edited by alexanderivrii Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Details and comments

ToDo (in this PR)

ToDo (in follow-ups)

Uh oh!

coveralls commented Oct 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 18442497358

Warning: This coverage report may be inaccurate.

Details

💛 - Coveralls

Uh oh!

Cryoris 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

[WIP] `PauliProductMeasurement` instruction #15126

[WIP] `PauliProductMeasurement` instruction #15126

ShellyGarion commented Oct 5, 2025 •

edited by alexanderivrii

Loading

coveralls commented Oct 5, 2025 •

edited

Loading