Skip to content

perf(tesseract): replace bitset visited set with 64-bit Zobrist table, lazy eneighbors, and pre-allocated A* scratch - #345

Open
samtan-googlequantumai wants to merge 1 commit into
quantumlib:mainfrom
samtan-googlequantumai:pr1-perf-zobrist-lazy-scratch
Open

samtan-googlequantumai wants to merge 1 commit into
quantumlib:mainfrom
samtan-googlequantumai:pr1-perf-zobrist-lazy-scratch

Conversation

@samtan-googlequantumai

Copy link
Copy Markdown

Summary

This PR optimizes TesseractDecoder initialization and A* search memory/CPU overhead while preserving identical decoding order and logical accuracy:

  1. Incremental 64-bit Zobrist VisitedTable (src/tesseract.h, src/tesseract.cc):
    • Replaces std::unordered_map<size_t, std::unordered_set<boost::dynamic_bitset<>>> visited_detectors with deterministic SplitMix64 Zobrist hashing (next_det_hash ^= zobrist_[d], stored on ErrorChainNode::det_hash) and a flat open-addressed VisitedTable paired with 16-bit generation tags (gens).
    • Supports sentinel-free lookup (including hash == 0), lazy init(1024) on first insertion (0 bytes allocated when no_revisit_dets = false), and O(1) reset between detector-ordering trials via generation increment (with automatic std::fill wraparound every 65,535 clears).
    • Under no_revisit_dets = true, a 64-bit collision across $N \le 2 \times 10^5$ visited states in a single trial occurs with probability $\approx \binom{N}{2} / 2^{64} \le 1.1 \times 10^{-9}$ and acts at worst as one extra heuristic visited prune in that trial.
  2. Lazy 2-hop ensure_eneighbors(size_t ei) (src/tesseract.h, src/tesseract.cc):
    • Replaces eager O(E * D) boost::dynamic_bitset<> construction of 2-hop detector neighborhoods in initialize_structures() with on-demand generation-stamped deduplication (eneighbor_seen_) when an error ei is first expanded during A*.
    • get_eneighbors() materializes any remaining unexpanded entries so external callers inspecting the full adjacency table see identical output.
  3. Pre-allocated A scratch buffers & inverse detector-rank cache (src/tesseract.h, src/tesseract.cc)*:
    • Reuses initial_detectors_, scratch_detectors_, initial_dct_, scratch_dct_, scratch_next_dct_, generation-stamped scratch_det_cost_cache_ / scratch_det_cost_stamp_, and pq_container_ across shots and ordering trials, eliminating per-pop heap allocations and bitset copies on candidate edges.
    • Precomputes inverse detector-order ranks (ensure_det_order_ranks) so selecting min_detector iterates only over active syndrome bits (find_first() / find_next()), and automatically invalidates/rebuilds the cache if config.detector_orders / config.det_orders is mutated after decoder construction.
    • Replaces std::unordered_set<int> in get_flipped_observables with a flat parity vector.
  4. Duplicate detection ID mod-2 cancellation fix (src/tesseract.cc):
    • Toggles duplicate detector IDs mod 2 in decode_to_errors_with_graph and build_sparse_d2e (e.g., [d, d] cancels to the empty syndrome) instead of miscounting min_num_dets and throwing at search termination.

Multi-Pass Tesseract Compatibility

  • Preserves all retained-error accessors (error_count, error_symptom, error_probability, dem_error_index) and d2e / edets cost-sorting invariants relied upon by MultiPassTesseractDecoder (apply_error_probability_updates, update_internal_costs, restore_error_probabilities).
  • Because ensure_eneighbors(ei) depends only on the static bipartite incidence (d2e, edets) and not on error_costs, per-shot probability reweighting in multi-pass requires zero eneighbors recomputation.

Unit Tests

  • src/tesseract.test.cc:
    • VisitedTableFull64BitSentinelFreeAndGenerationWraparound: Tests uninitialized lookup, 0ULL hash insertion, low-16-bit collision resistance, table growth/rehashing, and 65,540 clear() cycles across uint16_t generation wraparound.
    • LazyEneighborsMatchesOnDemandExpansion: Verifies on-demand expansion during decode() and full materialization via get_eneighbors().
    • PostCompileDetectorOrderMutationAndDuplicateDetections: Tests growing/replacing/shrinking config.detector_orders after construction and mod-2 cancellation of duplicate detection events.
  • src/py/tesseract_test.py:
    • test_duplicate_detections_cancel_mod_2 (with sparsify_errors=False and True) and test_post_compile_det_orders_mutation_rebuilds_ranks.

Benchmarks on testdata/ (SI1000 p = 0.001, 0.002, 21 DetBFS orders, det_beam = 15)

PR 1 Tradeoff Arrows

  • Exact Accuracy Parity: 50 / 50 benchmarked configurations (24/24 1-pass + 26/26 2-pass --multipass) produce bit-for-bit identical logical failure counts (0 low_confidence) to main.
  • 2-Pass --multipass Decode Speedup: 1.10x–1.85x across all 26 runs (median 1.41x; Surface 1.49x–1.85x, Color 1.13x–1.33x, Bivariate Bicycle 1.10x–1.20x).
  • 1-Pass Decode Speedup: 0.93x–1.13x across 24 runs (median 1.05x; Surface 1.04x–1.11x, Color 0.99x–1.05x, BB [[72,12,6]] 1.13x at p = 0.002).
  • Decoder Construction (TesseractDecoder(config)) Speedup: 3.24x–13.36x (median 6.82x):
testdata/ Circuit Family Distance $d$ Qubits $q$ Retained Errors $E$ main Init (ms) PR 1 Init (ms) Init Speedup
surfacecodes 7 97 5,473 18.22 5.62 3.24x
surfacecodes 11 241 24,485 92.00 23.58 3.90x
surface_code_trans_cx_circuits 11 482 102,839 1,193.00 107.68 11.08x
colorcodes 9 121 21,277 157.11 30.86 5.09x
colorcodes 11 181 41,044 493.30 57.77 8.54x
bivariatebicyclecodes ([[72,12,6]]) 6 144 16,164 159.11 33.52 4.75x
bivariatebicyclecodes ([[144,12,10]]) 10 216 41,958 842.52 82.22 10.25x
bivariatebicyclecodes ([[144,12,12]]) 12 288 67,752 1,942.14 145.33 13.36x

@samtan-googlequantumai
samtan-googlequantumai requested a review from a team as a code owner November 12, 2026 01:10
@samtan-googlequantumai
samtan-googlequantumai requested review from viathor and removed request for a team November 12, 2026 01:10
@viathor
viathor requested a review from LalehB November 12, 2026 16:48

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