Skip to content

feat(experimental): exact fault-distance search for non-Clifford circuits - #305

Draft
rafaelha wants to merge 3 commits into
mainfrom
feat/shortest-errors
Draft

rafaelha wants to merge 3 commits into
mainfrom
feat/shortest-errors

Conversation

@rafaelha

Copy link
Copy Markdown
Collaborator

Adds tsim.experimental.shortest_errors, the non-Clifford analogue of Stim's shortest_graphlike_error.

from tsim.experimental import shortest_errors

errors = shortest_errors(circuit, max_weight=3)   # every minimum-weight logical error
len(errors[0])                                    # the fault distance
errors[0].undetected_probability                  # P(no detector flips | these faults)
errors[0].logical_flip_probability                # P(no detector flips and an observable does)
errors[0].faults[0].circuit_error_locations       # stim.CircuitErrorLocation, as in Stim

The search is exhaustive, so an empty result proves the distance is above max_weight.

How it works

  • Tsim compiles the noise to error-basis bits f = T e, and nothing else about the noise reaches the outputs. Circuit errors with equal f-bits are one fault.
  • Direct detectors are single f-bits. Sets whose direct detectors cancel are found by joining two tables of smaller sets on a linear hash, a meet in the middle.
  • The statevector components decide each candidate exactly. statevector/branches.py walks every measurement branch of the tape and prunes on detectors as soon as they are known.
  • The builder now records each noise channel's instruction and target range (Site, channel_sites, chain_links), so faults are explained with Stim's own location type.

Results

These are the T circuits of Chan et al., arXiv:2609.17706, on the whole circuit with no region hint:

circuit paper shortest_errors time
d3a6 2 2 (9 errors) 0.02 s
d3a6f2 (Z-flagged) 3 3 0.4 s
d5a19 3 3 (9 errors) 7 s
d5a19f13 (Z-flagged) 4 4 (84 errors) 160 s
d5a19r4 3 3 7 s
d5a19r4f13 (Z-flagged) 5 none up to weight 4 240 s

Checks

  • Exact probabilities: found errors, written into the circuit as fixed Paulis, sample to the reported probabilities in Clifft and in Tsim's sampler.
  • Clifford circuits: the distance equals what Stim's search_for_undetectable_logical_errors finds, and the circuit error locations equal Stim's.
  • Tape walk: Branches matches the dense ops_distribution reference on the test circuits.
  • Suite: 2719 passed, 103 skipped; ruff, black, isort and pyright are clean.

Open

  • Weight 4 is dominated by the Python tape walk, at about 15k distinct inputs per second. Weight 5 on d=5 is refused (MAX_COMBINATIONS).
  • Instruction offsets index circuit.flattened(), which matches Stim only for circuits without REPEAT.
  • API placement: tsim.experimental for now, possibly a Circuit method later.

🤖 Generated with Claude Code

shortest_errors(circuit, max_weight=k) returns every smallest set of faults
that can flip an observable without flipping a detector, with the exact
probabilities that the set goes undetected and flips an observable.

Circuit errors with equal error-basis bits act identically, so they form one
fault. Direct detectors are single f-bits, so sets whose direct detectors
cancel are found by joining two tables of smaller sets on a linear hash; the
statevector components then decide each candidate exactly by walking every
measurement branch of their tape (statevector/branches.py).

The builder now records each noise channel's instruction and target range,
so faults are explained with stim.CircuitErrorLocation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@codecov

codecov Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 99.56395% with 3 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
src/tsim/noise/fault_join.py 98.46% 3 Missing ⚠️

📢 Thoughts on this report? Let us know!

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

☂️ Code Coverage

current status: ✅

Overall Coverage

Statements Covered Coverage Threshold Status
6873 5850 85% 0% 🟢

New Files

File Coverage Status
src/tsim/noise/fault_join.py 98% 🟢
src/tsim/noise/faults.py 100% 🟢
src/tsim/statevector/branches.py 100% 🟢
TOTAL 99% 🟢

Modified Files

File Coverage Status
src/tsim/core/builder.py 100% 🟢
src/tsim/core/parse.py 97% 🟢
src/tsim/experimental.py 100% 🟢
TOTAL 99% 🟢

updated for commit: e3e11e6 by action🐍

…umba

The tape reads a set's f-bits only through its rotation signs and a linear
flip of its outputs, and few distinct signs occur: 3,864 among the 18M
weight-4 candidates of Z-flagged d=5 cultivation. Branches.outcomes now gives
the exact output distribution per distinct signs, and a numba join
(noise/fault_join.py) streams the larger half of each set instead of storing
it, in two passes: one collects the distinct signs, the other keeps the sets
whose signs and output flips can flip an observable undetected.

d=5 cultivation to weight 3 goes from 10 s to 0.7 s, Z-flagged d=5 to weight
4 from 160 s to 5 s, and weight 5 is now within reach. max_errors keeps only
the most likely errors.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…lane splits

Codecov does not trace numba, so a test runs the join kernels' py_funcs and
checks them against the compiled join.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant