Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -574,6 +574,9 @@ sinter collect \

Sinter efficiently manages the execution of these tasks, and Tesseract is used for decoding. For more usage examples, see the tests in `src/py/tesseract_sinter_compat_test.py`.

The compiled Sinter integration reports low-confidence decoding outcomes as discards. Use
`errors + discards` when calculating a conservative logical failure count.

## Good Starting Points for Tesseract Configurations

The [Tesseract paper](https://arxiv.org/pdf/2503.10988) recommends two setups for starting your exploration with Tesseract:
Expand Down
3 changes: 3 additions & 0 deletions src/py/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -511,6 +511,9 @@ print(estimated_dem)
### Sinter Integration
The Tesseract Python interface is compatible with the Sinter framework, which is a powerful tool for large-scale decoding, benchmarking, and error-rate estimation.

The compiled Sinter integration reports low-confidence decoding outcomes as discards. Use
`errors + discards` when calculating a conservative logical failure count.

#### The TesseractSinterDecoder Object
All Sinter examples rely on this utility function to provide the Sinter-compatible Tesseract decoder.
The default decoder dictionary also includes sparsified variants:
Expand Down
141 changes: 88 additions & 53 deletions src/py/tesseract_sinter_compat_test.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,13 +20,34 @@
import sinter
import stim
import tesseract_decoder
from sinter._decoding._decoding import sample_decode
from sinter._decoding._stim_then_decode_sampler import StimThenDecodeSampler
from tesseract_decoder import (
TesseractSinterDecoder,
make_tesseract_sinter_decoders_dict,
)


def sample_decode_with_discards(
*,
circuit,
num_shots,
dem=None,
decoder="tesseract",
count_detection_events=False,
):
if dem is None:
dem = circuit.detector_error_model(decompose_errors=True)
sampler = StimThenDecodeSampler(
decoder=make_tesseract_sinter_decoders_dict()[decoder],
count_observable_error_combos=False,
count_detection_events=count_detection_events,
tmp_dir=None,
).compiled_sampler_for_task(
sinter.Task(circuit=circuit, detector_error_model=dem)
)
return sampler.sample(num_shots)


def test_tesseract_sinter_obj_exists():
"""
Check to ensure the decoder object exists and has the required methods.
Expand Down Expand Up @@ -138,7 +159,7 @@ def test_decode_shots_bit_packed():

# Extract the expected predictions from the DEM
expected_predictions = np.zeros(
(num_shots, (dem.num_observables + 7) // 8), dtype=np.uint8
(num_shots, (dem.num_observables + 7) // 8 + 1), dtype=np.uint8
)
expected_predictions[0][0] |= 1 << 0 # Logical observable L0 is flipped

Expand Down Expand Up @@ -183,7 +204,7 @@ def test_decode_shots_bit_packed_multi_shot():
)

expected_predictions = np.zeros(
(num_shots, (dem.num_observables + 7) // 8), dtype=np.uint8
(num_shots, (dem.num_observables + 7) // 8 + 1), dtype=np.uint8
)
# Expected flip for shot 0 is L0
expected_predictions[0][0] |= 1 << 0
Expand Down Expand Up @@ -231,10 +252,59 @@ def test_decode_shots_bit_packed_honors_both_numpy_strides(layout):

assert np.array_equal(
predictions,
np.array([[0b01], [0b10], [0b11]], dtype=np.uint8),
np.array([[0b01, 0], [0b10, 0], [0b11, 0]], dtype=np.uint8),
)


def test_decode_shots_bit_packed_marks_low_confidence_shots_for_discard():
dem = stim.DetectorErrorModel("""
error(0.1) D0 L0
detector(0, 0, 0) D0
detector(0, 0, 1) D1
""")
compiled_decoder = TesseractSinterDecoder().compile_decoder_for_dem(dem=dem)
detections = np.array([[0b01], [0b10]], dtype=np.uint8)

predictions = compiled_decoder.decode_shots_bit_packed(
bit_packed_detection_event_data=detections
)

expected_predictions = np.array(
[
[0b1, 0],
[0, 1],
],
dtype=np.uint8,
)
assert np.array_equal(predictions, expected_predictions)


def test_sinter_discards_low_confidence_shots():
circuit = stim.Circuit("""
R 0 1
X_ERROR(1) 0
M 0 1
DETECTOR rec[-2]
DETECTOR rec[-1]
OBSERVABLE_INCLUDE(0) rec[-2]
""")
dem = stim.DetectorErrorModel("""
error(0.1) D1 L0
detector D0
detector D1
""")

result = sample_decode_with_discards(
circuit=circuit,
dem=dem,
num_shots=5,
)

assert result.shots == 5
assert result.discards == 5
assert result.errors == 0


def test_decode_via_files_sanity_check():
"""
Tests the 'decode_via_files' method by simulating a small circuit and
Expand Down Expand Up @@ -456,14 +526,9 @@ def test_sinter_decode_repetition_code():
after_clifford_depolarization=0.05,
)

result = sample_decode(
circuit_obj=circuit,
circuit_path=None,
dem_obj=circuit.detector_error_model(decompose_errors=True),
dem_path=None,
result = sample_decode_with_discards(
circuit=circuit,
num_shots=1000,
decoder="tesseract",
custom_decoders=make_tesseract_sinter_decoders_dict(),
)
assert result.discards == 0
assert 0 <= result.errors <= 100
Expand All @@ -480,14 +545,9 @@ def test_sinter_decode_surface_code():
rounds=15,
after_clifford_depolarization=0.001,
)
result = sample_decode(
result = sample_decode_with_discards(
circuit=circuit,
num_shots=1000,
circuit_obj=circuit,
circuit_path=None,
dem_obj=circuit.detector_error_model(decompose_errors=True),
dem_path=None,
decoder="tesseract",
custom_decoders=make_tesseract_sinter_decoders_dict(),
)
assert result.discards == 0
assert 0 <= result.errors <= 50
Expand All @@ -499,14 +559,9 @@ def test_sinter_empty():
Tests the 'tesseract' decoder on an empty circuit.
"""
circuit = stim.Circuit()
result = sample_decode(
circuit_obj=circuit,
circuit_path=None,
dem_obj=circuit.detector_error_model(decompose_errors=True),
dem_path=None,
result = sample_decode_with_discards(
circuit=circuit,
num_shots=1000,
decoder="tesseract",
custom_decoders=make_tesseract_sinter_decoders_dict(),
)
assert result.discards == 0
assert result.shots == 1000
Expand All @@ -522,14 +577,9 @@ def test_sinter_no_observables():
M 0
DETECTOR rec[-1]
""")
result = sample_decode(
circuit_obj=circuit,
circuit_path=None,
dem_obj=circuit.detector_error_model(decompose_errors=True),
dem_path=None,
result = sample_decode_with_discards(
circuit=circuit,
num_shots=1000,
decoder="tesseract",
custom_decoders=make_tesseract_sinter_decoders_dict(),
)
assert result.discards == 0
assert result.shots == 1000
Expand All @@ -546,14 +596,9 @@ def test_sinter_invincible_observables():
DETECTOR rec[-2]
OBSERVABLE_INCLUDE(1) rec[-1]
""")
result = sample_decode(
circuit_obj=circuit,
circuit_path=None,
dem_obj=circuit.detector_error_model(decompose_errors=True),
dem_path=None,
result = sample_decode_with_discards(
circuit=circuit,
num_shots=1000,
decoder="tesseract",
custom_decoders=make_tesseract_sinter_decoders_dict(),
)
assert result.discards == 0
assert result.shots == 1000
Expand All @@ -573,16 +618,10 @@ def test_sinter_detector_counting():
OBSERVABLE_INCLUDE(0) rec[-1]
OBSERVABLE_INCLUDE(1) rec[-1] rec[-2]
""")
result = sample_decode(
circuit_obj=circuit,
circuit_path=None,
dem_obj=circuit.detector_error_model(decompose_errors=True),
dem_path=None,
post_mask=None,
result = sample_decode_with_discards(
circuit=circuit,
num_shots=10000,
decoder="tesseract",
count_detection_events=True,
custom_decoders=make_tesseract_sinter_decoders_dict(),
)
assert result.discards == 0
assert result.custom_counts["detectors_checked"] == 20000
Expand Down Expand Up @@ -883,14 +922,10 @@ def test_sinter_decode_with_sparsify_decoders(decoder_name):
after_clifford_depolarization=0.01,
)

result = sample_decode(
circuit_obj=circuit,
circuit_path=None,
dem_obj=circuit.detector_error_model(decompose_errors=True),
dem_path=None,
result = sample_decode_with_discards(
circuit=circuit,
num_shots=100,
decoder=decoder_name,
custom_decoders=make_tesseract_sinter_decoders_dict(),
)
assert result.discards == 0
assert result.shots == 100
Expand Down
8 changes: 5 additions & 3 deletions src/tesseract_sinter_compat.pybind.h
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ struct TesseractSinterCompiledDecoder {
const py::array_t<uint8_t>& bit_packed_detection_event_data) {
return decode_sinter_shots_bit_packed(*decoder, num_detectors, num_observables,
bit_packed_detection_event_data,
SinterOutputFormat::Predictions);
SinterOutputFormat::PredictionsAndDiscard);
}
};

Expand Down Expand Up @@ -283,8 +283,10 @@ void pybind_sinter_compat(py::module& root) {
`(num_shots, ceil(num_detectors / 8))`. Each byte contains
8 bits of detection event data. A `1` in bit `k` of byte `j`
indicates that detector `8j + k` fired.
:return: A 2D numpy array of shape `(num_shots, ceil(num_observables / 8))`
containing the predicted observable flips in a bit-packed format.
:return: A 2D numpy array of shape
`(num_shots, ceil(num_observables / 8) + 1)`. The first bytes contain
predicted observable flips in bit-packed format. The final byte is nonzero
when Sinter should discard the shot because decoding had low confidence.
)pbdoc")
.def_readwrite("num_detectors", &TesseractSinterCompiledDecoder::num_detectors,
R"pbdoc(The number of detectors in the decoder's underlying DEM.)pbdoc")
Expand Down
Loading