Repository navigation
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
Conversation
…tection fix, and scratch buffers
samtan-googlequantumai
requested review from
viathor
and removed request for
a team
November 12, 2026 01:10
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR optimizes
TesseractDecoderinitialization and A* search memory/CPU overhead while preserving identical decoding order and logical accuracy:VisitedTable(src/tesseract.h,src/tesseract.cc):std::unordered_map<size_t, std::unordered_set<boost::dynamic_bitset<>>> visited_detectorswith deterministic SplitMix64 Zobrist hashing (next_det_hash ^= zobrist_[d], stored onErrorChainNode::det_hash) and a flat open-addressedVisitedTablepaired with 16-bit generation tags (gens).hash == 0), lazyinit(1024)on first insertion (0bytes allocated whenno_revisit_dets = false), andO(1)reset between detector-ordering trials via generation increment (with automaticstd::fillwraparound every 65,535 clears).no_revisit_dets = true, a 64-bit collision acrossensure_eneighbors(size_t ei)(src/tesseract.h,src/tesseract.cc):O(E * D)boost::dynamic_bitset<>construction of 2-hop detector neighborhoods ininitialize_structures()with on-demand generation-stamped deduplication (eneighbor_seen_) when an erroreiis first expanded during A*.get_eneighbors()materializes any remaining unexpanded entries so external callers inspecting the full adjacency table see identical output.src/tesseract.h,src/tesseract.cc)*:initial_detectors_,scratch_detectors_,initial_dct_,scratch_dct_,scratch_next_dct_, generation-stampedscratch_det_cost_cache_/scratch_det_cost_stamp_, andpq_container_across shots and ordering trials, eliminating per-pop heap allocations and bitset copies on candidate edges.ensure_det_order_ranks) so selectingmin_detectoriterates only over active syndrome bits (find_first()/find_next()), and automatically invalidates/rebuilds the cache ifconfig.detector_orders/config.det_ordersis mutated after decoder construction.std::unordered_set<int>inget_flipped_observableswith a flat parity vector.src/tesseract.cc):decode_to_errors_with_graphandbuild_sparse_d2e(e.g.,[d, d]cancels to the empty syndrome) instead of miscountingmin_num_detsand throwing at search termination.Multi-Pass Tesseract Compatibility
error_count,error_symptom,error_probability,dem_error_index) andd2e/edetscost-sorting invariants relied upon byMultiPassTesseractDecoder(apply_error_probability_updates,update_internal_costs,restore_error_probabilities).ensure_eneighbors(ei)depends only on the static bipartite incidence(d2e, edets)and not onerror_costs, per-shot probability reweighting in multi-pass requires zeroeneighborsrecomputation.Unit Tests
src/tesseract.test.cc:VisitedTableFull64BitSentinelFreeAndGenerationWraparound: Tests uninitialized lookup,0ULLhash insertion, low-16-bit collision resistance, table growth/rehashing, and 65,540clear()cycles acrossuint16_tgeneration wraparound.LazyEneighborsMatchesOnDemandExpansion: Verifies on-demand expansion duringdecode()and full materialization viaget_eneighbors().PostCompileDetectorOrderMutationAndDuplicateDetections: Tests growing/replacing/shrinkingconfig.detector_ordersafter construction and mod-2 cancellation of duplicate detection events.src/py/tesseract_test.py:test_duplicate_detections_cancel_mod_2(withsparsify_errors=FalseandTrue) andtest_post_compile_det_orders_mutation_rebuilds_ranks.Benchmarks on
testdata/(SI1000p = 0.001, 0.002,21DetBFS orders,det_beam = 15)24/241-pass +26/262-pass--multipass) produce bit-for-bit identical logical failure counts (0low_confidence) tomain.--multipassDecode Speedup:1.10x–1.85xacross all 26 runs (median1.41x; Surface1.49x–1.85x, Color1.13x–1.33x, Bivariate Bicycle1.10x–1.20x).0.93x–1.13xacross 24 runs (median1.05x; Surface1.04x–1.11x, Color0.99x–1.05x,BB [[72,12,6]]1.13xatp = 0.002).TesseractDecoder(config)) Speedup:3.24x–13.36x(median6.82x):testdata/Circuit FamilymainInit (ms)surfacecodessurfacecodessurface_code_trans_cx_circuitscolorcodescolorcodesbivariatebicyclecodes([[72,12,6]])bivariatebicyclecodes([[144,12,10]])bivariatebicyclecodes([[144,12,12]])