[rafaelha]

Stacked on #222 (stack #245). This PR's diff is against that branch.

Summary

This PR changes no behaviour. It is cleanup from the statevector review, made of one new test and three refactors. Samples are bit-identical after every commit. No feature or fix depends on it, so it can wait behind #222 and #219.

• Brute-force test for _Relations (test_pbc.py). _Relations is the GF(2) elimination that turns classical spiders into output parities. Until now it was only covered through whole-circuit distributions. The test builds 300 random small systems and sums the sign over the eliminated variables by enumeration. It then checks the reduced rows, and that the reduction raises exactly when no such rows exist.
• One symbol encoding (program.py, shared.py, shots.py; 13 lines added, 32 removed). The tape used to pack symbol sets into uint32 words, which lane_program unpacked again before packing them into uint64 lane words. The tape now keeps a boolean column per symbol. _pack, unpack_symbols and StatevectorComponent.num_words are gone, and num_symbols replaces num_words. The tape grows slightly: its symbol rows take 1.3 MB on d=5 cultivation, up from about 0.16 MB.
• No graves in run_lanes (shared.py; 161 lines added, 100 removed). A pruning now finishes the dying lanes' shots right away, with their outputs, coins and hidden bits, and drops them from live. Before, they waited in a grave buffer until the next random measurement or the end of the run. This removes graves, grave_at, dead_shot, dead_grave, the per-entry hidden masks and the -1 - grave codes. The per-shot work moves into _finish_shot, and lane_bytes counts two rows of lane symbols per lane instead of four.
• One sampling entry point (sampler.py). CompiledMeasurementSampler.sample and CompiledDetectorSampler.sample both call _sample_outputs(shots, batch_size, columns, bit_packed, mask, referenced). That method picks the shot-word or stabilizer-rank path once. The stabilizer-rank path's mask screening and reference XOR move into _sample_stabilizer_rank_outputs, so CompiledDetectorSampler.sample no longer duplicates them.

Open before merge

• Single-thread slowdown on the shared, unpruned path. Fixed in ad8d042: the end-of-run loop is inline again and has no hidden pass, and _finish_shot serves only pruned shots. On one thread, a width-7 component with 12 detectors, 2M shots and sharing on takes 0.031 s, against 0.033 s on Make postselection discards consistent across programs and components #222 and 0.045 s before this fix. Sample hashes are identical.
• The _Relations test checks the reduced echelon form (ad8d042, 04b7ae3): pivots are unique and in kept order, every row term is in kept, and no other row contains a pivot. Dropping the back-substitution and reversing the pivot priority both fail it now.
• Docstring nit in _sample_outputs, fixed in ad8d042.
• Stacked on Make postselection discards consistent across programs and components #222 in stack #245. Both branches are rebased linearly onto main at 6ee9e1b (Keep PauliString signs for every Pauli-product gate in Circuit.append #240), and the stack merges them together.
• Overlap with CUDA backend #219 (CUDA). It merges cleanly with this branch. Its new sample_postselected builds referenced/flip the same way _sample_outputs now does, so whichever PR lands second can reuse that code.

Verification

• After the rebase onto main at 6ee9e1b, the full suite passes locally (2367 passed) and pyright is clean. CX_d1=5_cult, with every detector postselected, gives the same hash as Make postselection discards consistent across programs and components #222 with sharing on and off. Before the rebase, CI was green on c221fea.

• Executor commits. A snapshot hashed exact samples and lane statistics for 48 circuits, with sharing on and off and three masks, plus two prune-heavy workloads. The hash is identical before and after.

• Sampler commit. A second snapshot covered both strategies and every combination of mask, both reference flags, bit_packed and observable layout. The hash is identical before and after.

• Review harness. 74,304 active_statevector cases and 4,788 cat5 cases produced identical hashes against the base branch. So did lane statistics on 62 more circuits.

• Timing. The table below uses cultivation, with every detector postselected, best of 5. Sample hashes are identical.

  Workload	Base	This PR
  CX_d1=5_cult, 2M shots, 1 thread, sharing on	1.38 s	1.31 s
  CX_d1=5_cult, 2M shots, 1 thread, sharing off	1.87 s	1.82 s
  CX_d1=5_cult, 2M shots, all threads, sharing on	0.18 s	0.19 s
  CX_d1=5_cult, 2M shots, all threads, sharing off	0.25 s	0.26 s
  Width-7 component, 12 detectors with half postselected, 400k shots, sharing on	0.05 s	0.05 s

  Pruning now scans the live shots each time a lane dies, instead of waiting for the next random measurement. That cost doesn't show up even on this prune-heavy workload. The only slowdown measured was the single-thread case without pruning, now fixed.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-28T04:17:30.581247Z	66883b9	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[github-actions]

PR Preview Action v1.8.2
🚀 View preview at https://queracomputing.github.io/tsim/pr-preview/pr-223/
Built to branch gh-pages at 2026-11-03 20:22 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[Copilot]

🟢 Approval recommended

No active review issues were identified for the statevector simplification and shared sampler dispatch refactor.

No open issues 🎉

What changed in this PR

This PR builds on #222’s postselection fixes to simplify statevector execution and centralize sampler backend dispatch, while preserving sampling behavior.

Changes:

• Adds 300 randomized brute-force checks for _Relations elimination and reduction.
• Replaces packed tape symbols with boolean columns and finalizes pruned shots immediately, removing grave buffers.
• Routes both public samplers through a shared _sample_outputs entry point.

File	Description
test/​unit/​statevector/​test_shots.py	Updates symbol handling and lane-memory expectations.
test/​unit/​statevector/​test_program.py	Verifies boolean symbol columns instead of packed words.
test/​unit/​statevector/​test_pbc.py	Adds brute-force validation of relation reduction.
test/​helpers/​statevector.py	Reads boolean output symbols directly.
src/​tsim/​statevector/​shots.py	Builds shot layouts from boolean symbol columns.
src/​tsim/​statevector/​shared.py	Removes symbol unpacking and grave buffers; finalizes pruned shots immediately.
src/​tsim/​statevector/​program.py	Lowers plans into boolean-column tapes.
src/​tsim/​sampler.py	Centralizes backend dispatch, reference handling, and mask screening.
CHANGELOG.md	Documents the behavior-preserving internal refactors.

_{Review effort: Balanced}

[github-actions]

☂️ Code Coverage

current status: ✅

Overall Coverage

Statements	Covered	Coverage	Threshold	Status
4547	3987	88%	0%	🟢

New Files

No new covered files...

Modified Files

File	Coverage	Status
src/tsim/sampler.py	90%	🟢
src/tsim/statevector/program.py	100%	🟢
src/tsim/statevector/shared.py	34%	🟢
src/tsim/statevector/shots.py	86%	🟢
TOTAL	78%	🟢

updated for commit: 2912950 by action🐍

[rafaelha]

I checked that samples are bit-identical, ran timings, and tried mutations on the new test.

Bit-identity holds. I wrote my own harness and ran it against this branch and the base (fix/statevector-discard-consistency) with the same seeds. Both trees produced identical hashes in every case:

• active_statevector: 74,304 cases over the 8 helper circuits plus 40 random circuits. The circuits have T gates, mid-circuit M/MR/MX, X and depolarizing noise, and several components. Each circuit ran with sharing on and off, 2 seeds, and 4 masks (none, all, random, empty). Each mask ran with all 4 reference-flag combinations, bit_packed on and off, 4 observable layouts and batch sizes None/1/37. The harness also checks the measurement sampler, shots=0, and repeated calls on one sampler.
• Lane statistics (groups, peak lanes, lanes, dead) were also identical on 60 more random circuits and 2 hand-written ones. That run covers pruning before the first action, every lane dying, and a pruning right after a split (498 programs).
• cat5: 4,788 cases were identical. On the DIRECT_FLIPS circuit, every one of the 8 masks with every reference combination chose the same path (screened or _sample_batches_with_postselection) and gave the same samples.

I also read the new _prune for the alive update, coins for pruned shots, hidden at action -1, and code_row remapping across splits. I found no behaviour change. The relevant unit tests pass (612).

Two things are worth fixing. Details are inline.

1. The non-inlined per-shot _finish_shot call makes the shared, unpruned path about 1.7x slower on one thread.
2. The _Relations test does not check the echelon form, so two reduce mutations pass it.

Review by a Claude subagent.

[rafaelha]

Per-shot slowdown on the sharing path. This loop now makes one out-of-line call to the cached _finish_shot per shot. It also builds a pattern[...] row view per shot and runs an extra &= ~hidden pass even though hidden is all zeros. Before, all of this was inline.

I timed it with NUMBA_NUM_THREADS=1, best of 5, on a width-7 component with 12 repeated-measurement detectors and 2M shots, sharing on:

• No mask: base 0.085 s, this PR 0.145 s.
• Every second detector masked: base 0.105 s, this PR 0.14 s.

As an experiment I inlined only this final loop: e = code_row[row[i]], XOR pattern[e, w], then the coin loop, with no hidden pass. That brought the no-mask case back to 0.088 s. With 24 threads the difference is within noise at this size, and the PR's width-7, 400k-shot benchmark doesn't show it.

Suggested fix: inline the loop here and keep _finish_shot for _prune only. If you keep the helper, pass the 2-D pattern plus the row index, and skip the hidden pass when nothing is hidden.

[rafaelha]

Fixed in ad8d042. The end-of-run loop in run_lanes is inline again and has no hidden pass; _finish_shot now serves only pruned shots. On one thread, a width-7 component with 12 detectors, 2M shots and sharing on now takes 0.031 s, against 0.033 s on #222 and 0.045 s before this fix. Sample hashes are identical across all three. Claude

[rafaelha]

The test checks the solution set of rows but not its form. It never checks that rows is in reduced echelon form with pivots taken in order. That form is what reduce promises and what callers rely on. Two one-line mutations of reduce pass all 300 cases, and each is caught only by test_ops_match_stabilizer_rank[True-midcircuit_feedforward]:

• Dropping the back-substitution loop (for bit in _bits(mask & below): ...).
• Reversing pivot priority (position = {v: i ...} and variable = list(order)).

Adding these assertions before this loop catches both mutants (10 and 18 failures). Unmutated, all 300 cases pass:

    for p, mask, _ in rows:
        assert mask >> p & 1
        assert min((v for v in kept if mask >> v & 1), key=kept.index) == p
        assert not any(m >> p & 1 for q, m, _ in rows if q != p)

[rafaelha]

Added in ad8d042, then tightened in 04b7ae3. The test now checks that pivots are unique and in kept order, that every row term is in kept with the pivot as its first term in kept order, and that no other row contains a pivot. Dropping the back-substitution fails 18 of the 300 cases, and reversing the pivot priority fails 10. Claude

[rafaelha]

Nit: "one array per list" should probably read "one array per entry of columns".

[rafaelha]

Reworded in ad8d042: "an array per entry of columns". Claude

[rafaelha]

Do we need this PR? It isn't required: no fix or feature depends on it. I still think it's worth merging once the open items below are fixed, after #222.

• The _Relations test is cheap and covers the part of the reader that is hardest to get right. Keep it, with the echelon-form assertions from the earlier comment.
• The single symbol encoding removes a pack/unpack round trip for little cost. The tape's symbol rows grow to 1.3 MB on d=5 cultivation, from about 0.16 MB packed.
• The single _sample_outputs is the most useful commit. It removes the second copy of mask screening and reference handling from CompiledDetectorSampler.sample. #219's sample_postselected builds referenced/flip the same way again, so whichever PR lands second should reuse it.
• Dropping the graves is the weakest trade. shared.py grows by about 60 lines, and _prune now takes 16 arguments. In exchange it drops the negative codes, the deferred dead-shot lists and half of the lane-symbol memory. That's worth it only if the end-of-run loop is inlined again (see the earlier comment). Without that fix I'd leave this commit out.

Extra checks on c221fea. I timed cultivation with every detector postselected, 2M shots, best of 5. Pruning now scans the live shots each time a lane dies, and I wanted to see whether that costs anything. It doesn't, and the samples are identical:

CX_d1=5_cult	Base	This PR
1 thread, sharing on	1.38 s	1.31 s
1 thread, sharing off	1.87 s	1.82 s
All threads, sharing on	0.18 s	0.19 s
All threads, sharing off	0.25 s	0.26 s

CX_d1=3_cult with 200k shots also had identical hashes and times.

Before merge:

• Fix the two earlier comments: inline the final shot loop, and add the echelon-form assertions.
• Rebase onto main once #222 lands. CHANGELOG.md and test_pbc.py conflict with #224.

I updated the PR description to match.

Review by Claude.

[Copilot]

🟡 Changes recommended

The change introduces a measured per-shot performance regression, and the reduction tests omit pivot invariants needed to guard against _Reading failures.

2 open issues

• Inline the final shot-output loop to avoid a 2M-shot regression · New
• Assert pivot uniqueness and reduced-echelon row constraints · New

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No active review issues are recorded for the statevector executor and sampler dispatch refactor.

No open issues 🎉

2 resolved since last review

• Assert pivot uniqueness and reduced-echelon row constraints
• Inline the final shot-output loop to avoid a 2M-shot regression

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

The review identifies no active issues in the statevector executor and sampler dispatch changes.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

The review identifies no active issues with the statevector simplification and centralized sampler dispatch.

No open issues 🎉

_{Review effort: Balanced}