Multi pass decoding

[oscarhiggott]

Summary

This adds one- and two-pass decoding with exactly two detector components. Each component has its own Tesseract decoder. In two-pass mode, predictions from the first pass reweight errors in the other component before the final pass. The component decoders are constructed once and reused across shots.

Causal scheduling is the default: only component decodes needed for the final logical prediction are scheduled. Experimental static scheduling runs both components in each pass. More than two components or two passes is out of scope.

Decoder interface

MultiPassTesseractDecoder takes a MultiPassTesseractConfig, separately from TesseractDecoder(TesseractConfig). Both, and SimplexDecoder, implement the common Decoder interface and return a DecodeResult. The result carries predictions, cost, low confidence, and an explicit flag indicating whether predicted error indices are populated.

Multipass owns the DEM splitting, component decoding, scheduling, and cross-component reweighting. Generated detector orders resolve separately against each component DEM, using the DetectorOrder infrastructure from #277. The CLI chooses the decoder during construction; the worker loop uses the common interface and initialization remains parallel. Execution-plan statistics are computed on demand by get_execution_plan().

Python and Sinter

The ordinary workflow is:

from multi_pass_sinter_decoders import MultiPassSinterDecoder, get_sinter_decoders

decoder = MultiPassSinterDecoder()
custom_decoders = get_sinter_decoders()

Standard Tesseract configuration keywords can be passed directly. Unknown keywords raise. The existing long-beam registry names remain available. Custom X/Z classification is one optional keyword, detector_basis_classifier; detector_classifier remains a compatibility alias for integer component labels.

GARI, the Python DEM decomposer, and multipass share the detector-basis interface. The named automatic classifier checks, in order:

1. Top-level measure_basis.
2. md.measure_basis.
3. Top-level basis.
4. md.basis.
5. Chromobius fourth coordinate: exactly 0/1/2 means X and 3/4/5 means Z.

An invalid reached metadata field blocks fallback. Nonintegral fourth coordinates are rejected. Stim surface-code parity is an explicit named adapter, not an automatic fallback; the decomposer's generic last-coordinate adapter remains available without claiming its labels are necessarily X/Z.

Python resolves classification once and passes a component vector to native code. Users do not need to normalize their DEM manually for Python/Sinter.

CLI

--multipass selects multipass decoding, with --num-passes 1|2 (default 2) and --multipass-strategy causal|static. --print-multipass-plan prints model statistics and the schedule on demand. --multipass --dem-out is rejected.

The standalone CLI accepts only canonical top-level JSON basis tags:

detector[{"basis":"X"}](0, 0, 0) D0
detector[{"basis":"Z"}](1, 0, 0) D1

Canonically tagged circuit DETECTOR instructions survive circuit-to-DEM conversion, so tagged .stim input works too. Otherwise, demutil.annotate_detector_bases(...) produces a canonical DEM in Python. It preserves coordinates, instruction order, repeats, shifts, errors and their tags, and unrelated JSON metadata. Conflicts and non-JSON tags that would be overwritten are errors.

Reweighting and correctness

The reweighting rule is a correlated-matching-style heuristic, not an exact conditional probability. It divides the XOR-combined probability of mechanisms containing both symptoms by the XOR-combined probability of the source symptom. One-sided mechanisms contribute to the denominator; independent coincidences are not included in the numerator. Reweighted probabilities are capped at 0.499 to keep costs positive.

Two-pass decoding requires merge_errors=True: the heuristic acts on aggregate symptoms, so applying its probability separately to duplicate unmerged mechanisms would be incorrect. One-pass decoding still supports merge_errors=False.

Existing ^ decomposition groups retain their boundaries and tags; each group must belong to one component. For undecomposed mixed-component errors, observable assignment must have exactly one solution. Impossible or ambiguous assignments, logical-only groups, and other detectorless groups are rejected with context rather than silently reinterpreted.

Temporary cost updates validate indices, use deterministic tie ordering, and restore costs even when decoding throws. Repeated and sparse shots must not inherit reweighting state. Reported cost comes only from the final pass; low confidence is aggregated across passes and propagated through Sinter's discard byte. Packed NumPy inputs support arbitrary strides.

Tests

Coverage includes observable-assignment uniqueness, existing decomposition groups, the reweighting formula and probability cap, merged/unmerged policies, cost restoration and sparse decoding, basis precedence and normalization, tagged circuit input, component detector orders, Sinter discards and strided arrays, and zero-configuration Python/Sinter use. The full bazel test --jobs=1 src/... suite passed during implementation, as did the benchmark-workflow and tutorial-sync tests.