Skip to content

feat(experimental): determined measurements of non-Clifford circuits - #306

Draft
rafaelha wants to merge 6 commits into
feat/shortest-errorsfrom
feat/determined-measurements
Draft

rafaelha wants to merge 6 commits into
feat/shortest-errorsfrom
feat/determined-measurements

Conversation

@rafaelha

@rafaelha rafaelha commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Stacked on #305 (feat/shortest-errors), whose Branches tape walk this reuses.

What

This adds non-Clifford versions of Stim's count_determined_measurements and missing_detectors to tsim.experimental, plus one function Stim has no counterpart for:

count_determined_measurements(circuit, *, unknown_input=False, shots=None, seed=None) -> int
missing_detectors(circuit, *, unknown_input=False, shots=None, seed=None) -> stim.Circuit
nondeterministic_detectors(circuit, ...) -> list[stim.DemTarget]  # declared detectors/observables that are random without noise
  • Determined parity: a parity of measurements that every noiseless shot gives the same value. Their count is the number of measurements minus the dimension of the records' affine span, which is Stim's count for Clifford circuits. A measurement that earlier ones predict only nonlinearly, such as a Toffoli AND, is not counted, because no detector can use it.
  • Exact (shots=None):
    • Compiles the noiseless circuit and walks each tape's measurement branches with Branches.support.
    • Fair coins that no rotation reads add their output flips as directions instead of branches.
    • With unknown_input=True, it starts with X_ERROR(0.5) on every qubit, enumerates the input bits that set independent rotation signs, and walks each tape once per distinct sign pattern.
  • Sampled (shots=n): spans the differences of n noiseless shots. It warns if a new direction still appeared in the second half of the shots.
  • Healing: missing_detectors lists determined parities of random detectors first. For example, if D1 and D2 became random but D1 ⊕ D2 did not, that parity is returned. This repairs circuits whose S gates became T gates.

Changes to Branches

  • Threshold (correctness): an outcome is now dropped when its probability given the lane is below IMPOSSIBLE. Previously the lane's absolute weight was compared. Example: R_X with probability 1e-7 on two qubits, then CCX: the joint outcome has probability 1e-14 but is possible. This affects shortest_errors as well.
  • New support(f) and coin_rows.

Literature checks

One-off runs on published circuits; the exact and sampled (1000 shots) methods agree on all of them. Only Chan et al.'s uncorrected d=5 circuit is kept as an integration test (test/data/determined, whose README gives its source and license).

Source Result
Chan et al. 2609.17706, uncorrected d=5 with S→T 106/108 determined; D69, D91, D97, D102 random; healed as D91⊕D97 and D91⊕D102 (flagged version similar)
Chan et al., corrected circuits; Wan & Zapirain 2609.18922 inputs every detector determined, none missing
Clifft 2604.27058 convert_s_to_t.py S→T swap only: 6 random detectors; with the errata flips: 4; full conversion: 0
Clifft converter, feedforward sources of the 7 sources, (6,2), (4,5), (4,1) are determined alone and the other 4 are random, with S as well as with T. This contradicts the converter's rule-3 docstring
Gidney et al. Fig. 22 GHZ XXXX parity after four T gates is determined with value −1
Litinski 15-to-1 4 checks determined; one wrong T gate randomizes 3
5-to-1 distillation (noiseless acceptance 1/6) no syndrome determined

Performance

The GF(2) span, its annihilator, and the overlaps of declarations with directions run in numba on packed 64-bit words. Healing works only on the random declarations.

Case Time Peak memory
surface code d=17 (5185 measurements), exact 1.8 s, mostly compilation —
surface code d=25 (16225 measurements), exact 6.5 s 0.6 GB RSS
surface code d=25, 200k shots 19 s —
16 unknown-input sign bits 0.26 s (was 75 s before review) —

Tests

  • Clifford circuits match Stim (Stim's docstring examples; surface, color and repetition codes), with and without unknown_input, both exact and sampled.
  • Random small T circuits: the exact and sampled counts agree.
  • Chan et al.'s uncorrected d=5 circuit: count, random detectors and healed detectors, exact and sampled.

Notes

  • Stim 1.16's count_determined_measurements rejects MPAD, and its type stub says missing_detectors returns an int.
  • .gitignore gains !test/data/**/*.stim so the test circuits are tracked.

🤖 Generated with Claude Code

rafaelha and others added 2 commits November 18, 2026 14:54
Add tsim.experimental.count_determined_measurements and missing_detectors,
the non-Clifford counterparts of Stim's methods, and
nondeterministic_detectors, which lists the declared detectors and
observables that are random without noise.

A parity is determined when every noiseless record gives it the same value,
so the determined parities annihilate the directions of the records' affine
span. The exact path compiles the noiseless circuit and walks each tape's
branches (Branches.support), adding unread fair coins as directions; unknown
inputs enumerate their independent rotation signs, one walk per distinct
signs of each tape. The sampled path spans the shots' differences.
missing_detectors puts determined parities of random detectors first, which
heals circuits whose S gates became T gates.

Branches now drops an outcome by its probability given the lane, not by the
lane's absolute weight, and gains support() and coin_rows.

Integration tests reproduce published cultivation circuits: Chan et al.'s
uncorrected and corrected d=5 circuits, each rule of Clifft's S-to-T
converter, and Wan & Zapirain's d=3 and d=5 inputs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The repository ignores *.stim; the test data are an exception.

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

codecov Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 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
7171 6148 86% 0% 🟢

New Files

File Coverage Status
src/tsim/determined.py 100% 🟢
src/tsim/utils/gf2_span.py 100% 🟢
TOTAL 100% 🟢

Modified Files

File Coverage Status
src/tsim/experimental.py 100% 🟢
src/tsim/statevector/branches.py 100% 🟢
TOTAL 100% 🟢

updated for commit: 1c82b67 by action🐍

rafaelha and others added 4 commits November 18, 2026 16:13
The other nine circuits checked claims of their papers; the unit tests
cover correctness. Keep Chan et al.'s uncorrected d=5 circuit, a
cultivation-sized T circuit with random detectors to heal.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tors with a reference sample

Each public function compiles the circuit; cache the span by the noiseless
circuit text (not for shots without a seed) so calling all three compiles
once. The missing-detector docstring and test sample with
use_detector_reference_sample=True, since a Tsim detector is its raw parity.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Warn about too few shots after the cache lookup, so a cache hit warns too.
- Ignore the seed in the exact path's cache key.
- Drop the exact path's single-pass batch loop and Span.contains.
- Build declarations from record sets; share the random-declaration helper.
- Suggest sampling when the exact walk exceeds its branch limit.
- Compute each lane's weight once in Branches; test properties, not pivots.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Coverage cannot trace numba kernels, so the GF(2) span tests and one
determined-measurement test also run them through py_func. Also test
refused Pauli declarations and the support walk with split lanes.

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