Allow TesseractSinterDecoder to be compiled with different DEMs

README.md

@@ -212,6 +212,138 @@ print(f"Predicted errors indices: {predicted_errors}")
 for i in predicted_errors:
     print(f"    {i}: {decoder.errors[i]}")
 ```
+## Using Tesseract with Sinter
+
+Tesseract can be easily integrated into [Sinter](https://github.com/quantumlib/Stim/tree/main/glue/sample) workflows. Sinter is a tool for running and organizing quantum error correction simulations.
+
+Here's an example of how to use Tesseract as a decoder for multiple Sinter tasks:
+
+```python
+import stim
+import sinter
+from tesseract_decoder import make_tesseract_sinter_decoders_dict, TesseractSinterDecoder
+import tesseract_decoder
+
+if __name__ == "__main__":  
+    # Define a list of Sinter task(s) with different circuits/decoders.
+    tasks = []
+    # Depolarizing noise probability.
+    p = 0.005
+    # These are the sensible defaults given by make_tesseract_sinter_decoders_dict().
+    # Note that `tesseract-short-beam` and `tesseract-long-beam` are the two sets of parameters used in the [Tesseract paper](https://arxiv.org/pdf/2503.10988).
+    decoders = ['tesseract', 'tesseract-long-beam', 'tesseract-short-beam']
+    decoder_dict = make_tesseract_sinter_decoders_dict()
+    # You can also make your own custom Tesseract Decoder to-be-used with Sinter.
+    decoders.append('custom-tesseract-decoder')
+    decoder_dict['custom-tesseract-decoder'] = TesseractSinterDecoder(
+        det_beam=10,
+        beam_climbing=True,
+        no_revisit_dets=True,
+        merge_errors=True,
+        pqlimit=1_000,
+        num_det_orders=5,
+        det_order_method=tesseract_decoder.utils.DetOrder.DetIndex,
+        seed=2384753,
+    )
+
+    for distance in [3, 5, 7]:
+        for decoder in decoders:
+            circuit = stim.Circuit.generated(
+                "surface_code:rotated_memory_x",
+                distance=distance,
+                rounds=3,
+                after_clifford_depolarization=p
+            )
+            tasks.append(sinter.Task(
+                circuit=circuit,
+                decoder=decoder,
+                json_metadata={"d": distance, "decoder": decoder},
+            ))
+
+    # Collect decoding outcomes per task from Sinter.
+    results = sinter.collect(
+        num_workers=8,
+        tasks=tasks,
+        max_shots=10_000,
+        decoders=decoders,
+        custom_decoders=decoder_dict,
+        print_progress=True,
+    )
+
+    for result in results:
+        print(f"task metadata = {result.json_metadata}")
+        print(f" Shots run: {result.shots}")
+        print(f" Observed errors: {result.errors}")
+        print(f" Logical error rate: {result.errors / result.shots}")
+
+    # Should get something like:
+    # task metadata = {'d': 3, 'decoder': 'tesseract'}
+    #  Shots run: 10000
+    #  Observed errors: 48
+    #  Logical error rate: 0.0048
+    # task metadata = {'d': 3, 'decoder': 'custom-tesseract-decoder'}
+    #  Shots run: 10000
+    #  Observed errors: 64
+    #  Logical error rate: 0.0064
+    # task metadata = {'d': 5, 'decoder': 'tesseract-short-beam'}
+    #  Shots run: 10000
+    #  Observed errors: 13
+    #  Logical error rate: 0.0013
+    # task metadata = {'d': 5, 'decoder': 'custom-tesseract-decoder'}
+    #  Shots run: 10000
+    #  Observed errors: 12
+    #  Logical error rate: 0.0012
+    # task metadata = {'d': 3, 'decoder': 'tesseract-long-beam'}
+    #  Shots run: 10000
+    #  Observed errors: 42
+    #  Logical error rate: 0.0042
+    # task metadata = {'d': 3, 'decoder': 'tesseract-short-beam'}
+    #  Shots run: 10000
+    #  Observed errors: 39
+    #  Logical error rate: 0.0039
+    # task metadata = {'d': 5, 'decoder': 'tesseract'}
+    #  Shots run: 10000
+    #  Observed errors: 15
+    #  Logical error rate: 0.0015
+    # task metadata = {'d': 5, 'decoder': 'tesseract-long-beam'}
+    #  Shots run: 10000
+    #  Observed errors: 13
+    #  Logical error rate: 0.0013
+    # task metadata = {'d': 7, 'decoder': 'tesseract'}
+    #  Shots run: 10000
+    #  Observed errors: 5
+    #  Logical error rate: 0.0005
+    # task metadata = {'d': 7, 'decoder': 'tesseract-long-beam'}
+    #  Shots run: 10000
+    #  Observed errors: 1
+    #  Logical error rate: 0.0001
+    # task metadata = {'d': 7, 'decoder': 'tesseract-short-beam'}
+    #  Shots run: 10000
+    #  Observed errors: 3
+    #  Logical error rate: 0.0003
+    # task metadata = {'d': 7, 'decoder': 'custom-tesseract-decoder'}
+    #  Shots run: 10000
+    #  Observed errors: 3
+    #  Logical error rate: 0.0003
+```
+
+This example runs simulations for a repetition code with different distances [3, 5, 7] with different Tesseract default decoders. 
+
+Sinter can also be used at the command line. Here is an example of this using Tesseract:
+
+```bash
+sinter collect \
+    --circuits "example_circuit.stim" \
+    --decoders tesseract \
+    --custom_decoders_module_function "tesseract_decoder:make_tesseract_sinter_decoders_dict" \
+    --max_shots 100_000 \
+    --max_errors 100
+    --processes auto \
+    --save_resume_filepath "stats.csv" \
+```
+
+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`.
+
 ## Good Starting Points for Tesseract Configurations:
  The [Tesseract paper](https://arxiv.org/pdf/2503.10988) recommends two setup for starting your exploration with tesseract:
 

src/py/tesseract_sinter_compat_test.py

@@ -19,7 +19,7 @@
 import shutil
 from sinter._decoding._decoding import sample_decode
 
-from src.tesseract_decoder import tesseract_sinter_compat as tesseract_module
+from src.tesseract_decoder import TesseractSinterDecoder, make_tesseract_sinter_decoders_dict
 from src import tesseract_decoder
 import sinter
 
@@ -29,7 +29,7 @@ def test_tesseract_sinter_obj_exists():
     Sanity check to ensure the decoder object exists and has the required methods.
     """
 
-    decoder = tesseract_module.TesseractSinterDecoder()
+    decoder = TesseractSinterDecoder()
     assert hasattr(decoder, 'compile_decoder_for_dem')
     assert hasattr(decoder, 'decode_via_files')
 
@@ -51,11 +51,11 @@ def test_compile_decoder_for_dem(use_custom_config):
     """)
 
     if use_custom_config:
-        config = tesseract_decoder.tesseract.TesseractConfig()
-        config.verbose = True
-        decoder = tesseract_module.TesseractSinterDecoder(config=config)
+        decoder = TesseractSinterDecoder(
+            verbose=True,
+        )
     else:
-        decoder = tesseract_module.TesseractSinterDecoder()
+        decoder = TesseractSinterDecoder()
 
     compiled_decoder = decoder.compile_decoder_for_dem(dem=dem)
 
@@ -83,7 +83,7 @@ def test_decode_shots_bit_packed():
         error(0.1) D1 D2 L1
     """)
 
-    decoder = tesseract_module.TesseractSinterDecoder()
+    decoder = TesseractSinterDecoder()
     compiled_decoder = decoder.compile_decoder_for_dem(dem=dem)
 
     num_shots = 1
@@ -119,7 +119,7 @@ def test_decode_shots_bit_packed_multi_shot():
         error(0.1) D1 D2 L1
     """)
 
-    decoder = tesseract_module.TesseractSinterDecoder()
+    decoder = TesseractSinterDecoder()
     compiled_decoder = decoder.compile_decoder_for_dem(dem=dem)
 
     num_shots = 3
@@ -184,7 +184,7 @@ def test_decode_via_files_sanity_check():
     with open(dets_in_path, 'wb') as f:
         f.write(detection_events.tobytes())
 
-    tesseract_module.TesseractSinterDecoder().decode_via_files(
+    TesseractSinterDecoder().decode_via_files(
         num_shots=num_shots,
         num_dets=dem.num_detectors,
         num_obs=dem.num_observables,
@@ -247,11 +247,11 @@ def test_decode_via_files(use_custom_config):
         f.write(detection_events_np.tobytes())
 
     if use_custom_config:
-        config = tesseract_decoder.tesseract.TesseractConfig()
-        config.verbose = True
-        decoder = tesseract_module.TesseractSinterDecoder(config=config)
+        decoder = TesseractSinterDecoder(
+            verbose=True,
+        )
     else:
-        decoder = tesseract_module.TesseractSinterDecoder()
+        decoder = TesseractSinterDecoder()
 
     decoder.decode_via_files(
         num_shots=num_shots,
@@ -280,7 +280,7 @@ def test_decode_via_files(use_custom_config):
     if temp_dir.exists():
         shutil.rmtree(temp_dir)
 
-    assert decoder.config.verbose == use_custom_config
+    assert decoder.verbose == use_custom_config
 
 
 def test_decode_via_files_multi_shot():
@@ -332,7 +332,7 @@ def test_decode_via_files_multi_shot():
     with open(dets_in_path, 'wb') as f:
         f.write(detection_events_np.tobytes())
 
-    tesseract_module.TesseractSinterDecoder().decode_via_files(
+    TesseractSinterDecoder().decode_via_files(
         num_shots=num_shots,
         num_dets=num_detectors,
         num_obs=dem.num_observables,
@@ -378,7 +378,7 @@ def test_sinter_decode_repetition_code():
         dem_path=None,
         num_shots=1000,
         decoder="tesseract",
-        custom_decoders=tesseract_module.make_tesseract_sinter_decoders_dict(),
+        custom_decoders=make_tesseract_sinter_decoders_dict(),
     )
     assert result.discards == 0
     assert 0 <= result.errors <= 100
@@ -402,7 +402,7 @@ def test_sinter_decode_surface_code():
         dem_obj=circuit.detector_error_model(decompose_errors=True),
         dem_path=None,
         decoder="tesseract",
-        custom_decoders=tesseract_module.make_tesseract_sinter_decoders_dict(),
+        custom_decoders=make_tesseract_sinter_decoders_dict(),
     )
     assert result.discards == 0
     assert 0 <= result.errors <= 50
@@ -421,7 +421,7 @@ def test_sinter_empty():
         dem_path=None,
         num_shots=1000,
         decoder="tesseract",
-        custom_decoders=tesseract_module.make_tesseract_sinter_decoders_dict(),
+        custom_decoders=make_tesseract_sinter_decoders_dict(),
     )
     assert result.discards == 0
     assert result.shots == 1000
@@ -444,7 +444,7 @@ def test_sinter_no_observables():
         dem_path=None,
         num_shots=1000,
         decoder="tesseract",
-        custom_decoders=tesseract_module.make_tesseract_sinter_decoders_dict(),
+        custom_decoders=make_tesseract_sinter_decoders_dict(),
     )
     assert result.discards == 0
     assert result.shots == 1000
@@ -468,7 +468,7 @@ def test_sinter_invincible_observables():
         dem_path=None,
         num_shots=1000,
         decoder="tesseract",
-        custom_decoders=tesseract_module.make_tesseract_sinter_decoders_dict(),
+        custom_decoders=make_tesseract_sinter_decoders_dict(),
     )
     assert result.discards == 0
     assert result.shots == 1000
@@ -497,7 +497,7 @@ def test_sinter_detector_counting():
         num_shots=10000,
         decoder="tesseract",
         count_detection_events=True,
-        custom_decoders=tesseract_module.make_tesseract_sinter_decoders_dict(),
+        custom_decoders=make_tesseract_sinter_decoders_dict(),
     )
     assert result.discards == 0
     assert result.custom_counts['detectors_checked'] == 20000
@@ -513,7 +513,7 @@ def test_full_scale():
         tasks=[sinter.Task(circuit=stim.Circuit())],
         decoders=["tesseract"],
         max_shots=1000,
-        custom_decoders=tesseract_module.make_tesseract_sinter_decoders_dict(),
+        custom_decoders=make_tesseract_sinter_decoders_dict(),
     )
     assert result.discards == 0
     assert result.shots == 1000
@@ -535,7 +535,7 @@ def test_full_scale_one_worker():
         tasks=[sinter.Task(circuit=circuit)],
         decoders=["tesseract"],
         max_shots=1000,
-        custom_decoders=tesseract_module.make_tesseract_sinter_decoders_dict(),
+        custom_decoders=make_tesseract_sinter_decoders_dict(),
     )
 
     assert result.discards == 0
@@ -596,20 +596,25 @@ def test_decode_shots_bit_packed_vs_decode_batch(det_beam, beam_climbing, no_rev
     circuit = relabel_logical_observables(circuit=circuit, relabel_dict={0: 3})
     dem = circuit.detector_error_model()
 
-    # 2. Create the Tesseract configuration object with the parameterized values.
-    config = tesseract_decoder.tesseract.TesseractConfig(
-        dem=dem,
+    # 2. Compile the Sinter-compatible decoder with the parameterized values for the DEM.
+    sinter_decoder = TesseractSinterDecoder(
+        det_beam=det_beam,
+        beam_climbing=beam_climbing,
+        no_revisit_dets=no_revisit_dets,
+        merge_errors=merge_errors,
     )
-    config.det_beam = det_beam
-    config.beam_climbing = beam_climbing
-    config.no_revisit_dets = no_revisit_dets
-    config.merge_errors = merge_errors
 
     # 3. Compile the Sinter-compatible decoder.
-    sinter_decoder = tesseract_module.TesseractSinterDecoder(config=config)
     compiled_sinter_decoder = sinter_decoder.compile_decoder_for_dem(dem=dem)
 
-    # 4. Compile the raw Tesseract decoder directly from the config.
+    # 4. Obtain the compiled decoder from the config.
+    config = tesseract_decoder.tesseract.TesseractConfig(
+        dem=dem,
+        det_beam=det_beam,
+        beam_climbing=beam_climbing,
+        no_revisit_dets=no_revisit_dets,
+        merge_errors=merge_errors,
+    )
     decoder = config.compile_decoder()
 
     # 5. Generate a batch of shots and unpack them for comparison.
@@ -630,5 +635,40 @@ def test_decode_shots_bit_packed_vs_decode_batch(det_beam, beam_climbing, no_rev
     assert np.array_equal(predictions_sinter, predictions_decode_batch)
 
 
+def test_sinter_collect_different_dems():
+    """
+    Ensures that Sinter tasks compile with different DEMs before collection.
+    """
+    # Create a repetition code circuit to test the decoder.
+    min_distance = 3
+    max_distance = 7
+    tasks = [
+        sinter.Task(
+            circuit=stim.Circuit.generated(
+                "repetition_code:memory",
+                distance=d,
+                rounds=3,
+                after_clifford_depolarization=0.1,
+            ),
+            json_metadata={"d": d},
+        )
+        for d in range(min_distance, max_distance + 1, 2)
+    ]
+
+    # Use sinter.collect to run the decoding task.
+    all_results = sinter.collect(
+        num_workers=1,
+        tasks=tasks,
+        decoders=["tesseract-long-beam"],
+        max_shots=100,  # Reduced max_shots for testing
+        custom_decoders=make_tesseract_sinter_decoders_dict()
+    )
+
+    assert len(all_results) == len(tasks)
+    expected_distances = [3,5,7]
+    for i, results in enumerate(all_results):
+        assert results.json_metadata['d'] == expected_distances[i]
+
+
 if __name__ == "__main__":
     raise SystemExit(pytest.main([__file__]))