Add sparse_matrix() to PauliString and PauliSum by ToastCheng · Pull Request #8127 · quantumlib/Cirq

ToastCheng · 2026-06-07T06:53:19Z

For each PauliString term, row/col indices and phases are computed directly via bitwise ops on basis states to avoid Kron product.

For PauliSum, uses COO triplet accumulation instead of repeated CSR addition to avoid merging multiple sparse matrices.

Fixes #3057

codecov · 2026-06-07T07:02:08Z

Codecov Report

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

Additional details and impacted files

@@           Coverage Diff            @@
##             main    #8127    +/-   ##
========================================
  Coverage   99.60%   99.60%            
========================================
  Files        1118     1118            
  Lines      100957   101112   +155     
========================================
+ Hits       100557   100712   +155     
  Misses        400      400

☔ View full report in Codecov by Harness.
📢 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.

For each PauliString term, row/col indices and phases are computed directly via bitwise ops on basis states to avoid Kron product. For PauliSum, uses COO triplet accumulation instead of repeated CSR addition to avoid merging multiple sparse matrices.

mhucka · 2026-06-09T06:27:23Z

@ToastCheng Thank you for this work!

mhucka

Thank you for working on this!

I have some very small requests; otherwise, it looks good to me. I think @pavoljuhas had better review this too.

In addition, update implementation details: - use np.where parity check for phases - iterate self.items() directly

mhucka · 2026-06-17T05:16:47Z

@ToastCheng Thanks again for this contribution. Apart from agreeing with Pavol's point above, about adding an asserion, it's good to go from my perspective.

pavoljuhas · 2026-06-17T18:27:17Z

Thank you @mhucka. I asked @dstrain115 for a one quick look, so let's allow some time for that. Otherwise this looks good to me too.

dstrain115

Would recommend tightening up the test for pauli sum sparse matrix a bit, but otherwise I approve.

dstrain115 · 2026-06-18T14:58:37Z

    assert np.allclose(H3, paulisum.matrix([q[1], q[2], q[0]]))


+def test_pauli_sum_sparse_matrix() -> None:


I would recommend parameterizing this test case and passing in a variety of pauli sums.

@dstrain115 when you get a chance, would you review & approve the PR if it's ready?

pavoljuhas

I have a couple of minor suggestions, otherwise this looks great. Thank you @ToastCheng for contributing this!

pavoljuhas · 2026-06-24T01:51:00Z

+        (cirq.X(q0) * cirq.I(q1) + cirq.Z(q1), None),
+    ),
+)
+def test_pauli_sum_sparse_matrix(paulisum, qubits) -> None:


Nit - let us annotate the argument types here:

def test_pauli_sum_sparse_matrix(paulisum: cirq.PauliSum, qubits: list[cirq.Qid] | None) -> None:

pavoljuhas · 2026-06-24T01:56:35Z

+def test_pauli_sum_sparse_matrix(paulisum, qubits) -> None:
+    actual = paulisum.sparse_matrix(qubits).toarray()
+    expected = paulisum.matrix(qubits)
+    assert np.allclose(actual, expected)


Nit - we should use np.array_equal here to ensure the shapes of compared arrays are the same. (All tested coefficients have exact binary representation so there should be no problem with roundoffs)

pavoljuhas · 2026-06-24T01:59:10Z

+def test_pauli_sum_sparse_matrix_empty() -> None:
+    q = cirq.LineQubit.range(2)
+    empty = cirq.PauliSum.from_pauli_strings([])
+    assert np.allclose(empty.sparse_matrix(q).toarray(), np.zeros((4, 4)))


We should use array_equal as above and we should also check the default sparse_matrix:

assert np.array_equal(empty.sparse_matrix().toarray(), np.zeros((1, 1))) assert np.array_equal(empty.sparse_matrix(q).toarray(), np.zeros((4, 4)))

pavoljuhas · 2026-06-24T02:03:26Z

+
+        Raises:
+            NotImplementedError: If this `PauliString` is parameterized.
+            AssertionError: If an unexpected Pauli gate instance is encountered.


Nit - perhaps we should leave AssertionError from the docstring. Assertions are supposed to be always true regardless of user input; they should only pop up if there is a breaking change in the code or some unexpected code pathway.

ToastCheng requested a review from a team as a code owner June 7, 2026 06:53

ToastCheng requested a review from tanujkhattar June 7, 2026 06:53

github-actions Bot added the size: M 50< lines changed <250 label Jun 7, 2026

ToastCheng force-pushed the i3057-sparse2 branch from 1c32d58 to 1d4865b Compare June 7, 2026 07:21

ToastCheng force-pushed the i3057-sparse2 branch from 1d4865b to 127bcb4 Compare June 7, 2026 07:30

ToastCheng mentioned this pull request Jun 7, 2026

Add sparse_matrix method to PauliSum #3057

Open

mhucka self-assigned this Jun 9, 2026

mhucka requested changes Jun 10, 2026

View reviewed changes

mhucka requested a review from pavoljuhas June 10, 2026 04:43

Fix comment format and wording in sparse_matrix implementations

e4e84ae

In addition, update implementation details: - use np.where parity check for phases - iterate self.items() directly

ToastCheng force-pushed the i3057-sparse2 branch from ee039de to e4e84ae Compare June 10, 2026 15:19

pavoljuhas self-assigned this Jun 10, 2026

pavoljuhas added the priority/before-1.7 Finish before the Cirq 1.7 release label Jun 11, 2026

pavoljuhas requested a review from dstrain115 June 17, 2026 02:22

pavoljuhas reviewed Jun 17, 2026

View reviewed changes

Comment thread cirq-core/cirq/ops/pauli_string.py

mhucka approved these changes Jun 17, 2026

View reviewed changes

dstrain115 reviewed Jun 18, 2026

View reviewed changes

Add assertion guard and parameterize sparse matrix test

a4faba8

ToastCheng force-pushed the i3057-sparse2 branch from bb1956c to a4faba8 Compare June 19, 2026 07:16

pavoljuhas approved these changes Jun 24, 2026

View reviewed changes

		assert np.allclose(H3, paulisum.matrix([q[1], q[2], q[0]]))


		def test_pauli_sum_sparse_matrix() -> None:

Conversation

ToastCheng commented Jun 7, 2026 • edited by pavoljuhas Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Jun 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

mhucka commented Jun 9, 2026

Uh oh!

mhucka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mhucka commented Jun 17, 2026

Uh oh!

pavoljuhas commented Jun 17, 2026

Uh oh!

dstrain115 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dstrain115 Jun 18, 2026

Choose a reason for hiding this comment

Uh oh!

ToastCheng Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

mhucka Jun 21, 2026

Choose a reason for hiding this comment

Uh oh!

pavoljuhas left a comment

Choose a reason for hiding this comment

Uh oh!

pavoljuhas Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

pavoljuhas Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pavoljuhas Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pavoljuhas Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ToastCheng commented Jun 7, 2026 •

edited by pavoljuhas

Loading

codecov Bot commented Jun 7, 2026 •

edited

Loading

pavoljuhas Jun 24, 2026 •

edited

Loading

pavoljuhas Jun 24, 2026 •

edited

Loading