Stabilizer tableau circuit simulation using backtracking method from Stim #551

sagnikpal2004 · 2025-07-11T19:13:48Z

This PR introduces a new method backtrajectory, implementing an efficient stabilizer simulation algorithm inspired by Craig Gidney’s Stim paper (Quantum, 2021). Instead of evolving stabilizer states forward through the circuit, this method incrementally folds inverse operations into an identity tableau, resolving measurements in reverse to efficiently extract outcomes.

Currently, the simulator can perform the following operations:

<:AbstractCliffordOperator (anything supported by apply_right!)
<:AbstractMeasurement -> PauliMeasurement, sMX, sMY, sMZ
<:AbstractReset -> sRX, sRY, sRZ
(measure and reset) -> sMRX, sMRY, sMRZ

Not supported yet

Reset, BellMeasurement, NoisyCircuits

Checklist:

The code is properly formatted and commented.
Substantial new functionality is documented within the docs.
All new functionality is tested.
All of the automated tests on github pass.

Changelog:

added BacktrackRegister

Notes:

Added three new symbolic operations under <:AbstractReset -> sRX, sRY, sRZ
Possibility of using the Register interface for returning results
Need advice on naming of functions in backtrajectory.jl
Need advice for measurement convention
Possiblity of having a unified simulations interface for various simulators
Hashing issues - should they hash in the type also?

Dependency:

apply_right! PR apply_right #561

References:
Gidney, C. (2021). Stim: A fast stabilizer circuit simulator. Quantum, 5, 497. https://doi.org/10.22331/q-2021-07-06-497

codecov · 2025-07-27T05:24:31Z

Codecov Report

❌ Patch coverage is 49.18478% with 187 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.81%. Comparing base (d86ff67) to head (f7fda1b).
⚠️ Report is 3 commits behind head on master.

Files with missing lines	Patch %	Lines
src/backtrajectory.jl	0.00%	148 Missing ⚠️
src/apply_right.jl	84.97%	32 Missing ⚠️
src/classical_register.jl	0.00%	3 Missing ⚠️
src/symbolic_cliffords.jl	0.00%	3 Missing ⚠️
src/affectedqubits.jl	0.00%	1 Missing ⚠️

❗ There is a different number of reports uploaded between BASE (d86ff67) and HEAD (f7fda1b). Click for more details.

HEAD has 2 uploads less than BASE

Flag BASE (d86ff67) HEAD (f7fda1b)

10 8

Additional details and impacted files

@@             Coverage Diff             @@
##           master     #551       +/-   ##
===========================================
- Coverage   84.46%   73.81%   -10.66%     
===========================================
  Files          95      103        +8     
  Lines        5956     6610      +654     
===========================================
- Hits         5031     4879      -152     
- Misses        925     1731      +806

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

Krastanov · 2025-07-28T13:59:53Z

src/backtrajectory.jl

+resolved by transforming their observables to the initial state; deterministic measurements are directly computed from tableau signs,
+while random measurements are simplified and simulated with randomized gate insertions.
+
+Reference:


for references we have @cite and a bibtex file

Krastanov · 2025-07-28T14:03:11Z

src/backtrajectory.jl

+
+
+
+function do_op!(T, op::sMX)


to not explode the name space, let's either use a name like _backtraj_do_meas or put this in a module from which we just make backtrajectory available

Krastanov · 2025-07-28T14:06:21Z

src/backtrajectory.jl

+    T = one(CliffordOperator, n)
+    result = Register(one(Stabilizer, n), falses(m))


these guys together seem to represent something, so a structure that has them together might be useful, e.g. BacktrajectoryRegister

Krastanov · 2025-07-28T14:07:50Z

src/backtrajectory.jl

+        if op isa AbstractCliffordOperator
+            apply_right!(T, op)
+        elseif op isa AbstractMeasurement
+            res = do_op!(T, op)
+            op.bit!=0 && (bitview(result)[op.bit] = res)
+        elseif typeof(op) ∈ [sMRX, sMRY, sMRZ]
+            res = do_op!(T, op)
+            op.bit!=0 && (bitview(result)[op.bit] = res)
+        elseif op isa AbstractReset
+            do_op!(T, op)
+        else
+            error("Unsupported operation: $(typeof(op))")


if you are using isa you are probably doing something unidiomatic. This whole if/else tree should probably be multimethods

(and we will need to discuss issues with "union splitting" and "sum types" later on)

Krastanov · 2025-07-28T14:08:58Z

src/backtrajectory.jl

+    return pivot
+end
+
+@inline is_deterministic_x(T, q::Int) = all(getxbytes(T, q) .== 0)


the T would lead folks to think this is a Type

Krastanov · 2025-07-28T14:09:41Z

src/QuantumClifford.jl

    SparseGate,
-    sMX, sMY, sMZ, PauliMeasurement, Reset, sMRX, sMRY, sMRZ,
+    sMX, sMY, sMZ, PauliMeasurement, 
+    Reset, sMRX, sMRY, sMRZ, sRX, sRY, sRZ,


let's not export the new resets until their API is fully implemented

Krastanov

some minor suggestions for changes

let's discuss again when the tests are done

Krastanov · 2025-08-09T12:26:21Z

src/QuantumClifford.jl

 using LinearAlgebra: inv, mul!, rank, Adjoint, dot, tr
 import DataStructures
-using DataStructures: DefaultDict, Accumulator
+using DataStructures: DefaultDict, Accumulator, counter


double check that the recent 0.19 does not break this

src/QuantumClifford.jl

src/backtrajectory.jl

Krastanov · 2025-08-09T12:37:56Z

src/backtrajectory.jl

+
+nqubits(r::StimRegister) = nqubits(r.inv_circuit)
+bitview(r::StimRegister) = r.bits
+quantumstate(r::StimRegister) = apply_inv!(one(Stabilizer, nqubits(r)), r.inv_circuit)


maybe add a docstring that using this is not a view and it requires calling inv(::CliffordOperator) which is relatively slow?

you should add a header to make it more obvious that it is for this method. DocStringExtensions provides an automated way to do that

Krastanov · 2025-08-09T12:39:50Z

src/backtrajectory.jl

+@inline getxrow(s::Tableau, r::Int) = s.xzs[1:2:end, r]
+@inline getzrow(s::Tableau, r::Int) = s.xzs[2:2:end, r]


is there elsewhere in the codebase that functions like this are defined, maybe in the linalg file or somewhere near where Tableau is defined -- just double check that there is no better place to put them

Krastanov · 2025-08-09T12:40:24Z

test/test_backtraj.jl

@@ -0,0 +1,4 @@
+@testitem "test backtrajectory" begin
+


let's discuss again after we have the tests

…ford.jl into backtraj

sagnikpal2004 mentioned this pull request Jul 15, 2025

apply_right! and apply_inv_right! #555

Closed

sagnikpal2004 added 3 commits July 23, 2025 15:15

initial commit

fe3ae66

fixed more gates

f1f22ab

complete single-qubit

adc4eb2

sagnikpal2004 mentioned this pull request Jul 23, 2025

apply_right #561

Merged

4 tasks

sagnikpal2004 force-pushed the backtraj branch from efbeecd to 99ccd91 Compare July 25, 2025 20:43

sagnikpal2004 added 10 commits July 26, 2025 02:23

updated names

5b1c6da

complete two-qubit gates

3a5f82a

initial commit

e3e84d8

minor fixes

2d349a5

fix collapse_z phase randomness

09f9f44

collapse_x fixes

9663a0f

sMY and sMRY

b4cda36

reset

4abcabc

better method for calcuting number of qubits required

4fbcdc9

naming changes

1bec6dd

sagnikpal2004 force-pushed the backtraj branch from 99ccd91 to 1bec6dd Compare July 26, 2025 01:31

sagnikpal2004 added 5 commits July 27, 2025 02:24

pauli measurements for backtraj

c34c6b4

naming changes

06cdd26

remove sSQRTZ, update tests

82d5e8d

Merge remote-tracking branch 'origin/apply_right' into backtraj

0daec50

switch to using registers

f7fda1b

Krastanov reviewed Jul 28, 2025

View reviewed changes

sagnikpal2004 added 3 commits July 29, 2025 00:53

add tests

848642b

updated function names

21dd0dd

fix mctrajectory_keepstates counting issue

21031c0

Krastanov requested changes Aug 9, 2025

View reviewed changes

sagnikpal2004 added 2 commits August 10, 2025 13:07

resets are now measure-reset aliases

e3a7c62

rename to BacktrackingRegister

1ea084f

sagnikpal2004 added 5 commits August 11, 2025 11:20

set initial state

7c8a89d

Merge branch 'master' of https://github.com/QuantumSavory/QuantumClif…

26cb1d5

…ford.jl into backtraj

implement noise, rename to BacktrackRegister

1d44505

remove redundant resets

c219720

tests - not working

4b00700

		T = one(CliffordOperator, n)
		result = Register(one(Stabilizer, n), falses(m))

		@inline getxrow(s::Tableau, r::Int) = s.xzs[1:2:end, r]
		@inline getzrow(s::Tableau, r::Int) = s.xzs[2:2:end, r] No newline at end of file

Stabilizer tableau circuit simulation using backtracking method from Stim #551

Are you sure you want to change the base?

Stabilizer tableau circuit simulation using backtracking method from Stim #551

Uh oh!

Conversation

sagnikpal2004 commented Jul 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Jul 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

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!

Krastanov left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

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!

2 participants

sagnikpal2004 commented Jul 11, 2025 •

edited

Loading

codecov bot commented Jul 27, 2025 •

edited

Loading