Added CLI example, and made make_tesseract_sinter_decoders_dic and

TesseractSinterDecoder visible from the root module.

Author: dandragona-dev

README.md

@@ -214,18 +214,18 @@ for i in predicted_errors:
 ```
 ## Using Tesseract with Sinter
 
-Tesseract can be easily integrated into [Sinter](https://github.com/quantumlib/Sinter) workflows. Sinter is a tool for running and organizing quantum error correction simulations. The `tesseract_sinter_compat` module provides the necessary interface.
+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 tesseract_sinter_compat
+from tesseract_decoder import make_tesseract_sinter_decoders_dict
 
 # Define a list of Sinter task(s) with different circuits/decoders.
 tasks = []
-# These are the sensible defaults given by tesseract_module.make_tesseract_sinter_decoders_dict().
+# These are the sensible defaults given by make_tesseract_sinter_decoders_dict().
 decoders = ['tesseract', 'tesseract-long-beam', 'tesseract-short-beam']
 for i, distance in enumerate([3, 5, 7]):
     circuit = stim.Circuit.generated(
@@ -270,7 +270,22 @@ for result in results:
 #  Logical error rate: 0.0153
 ```
 
-This example runs simulations for a repetition code with different distances [3, 5, 7] with different Tesseract default decoders. 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`.
+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:
-        decoder = tesseract_module.TesseractSinterDecoder(
+        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:
-        decoder = tesseract_module.TesseractSinterDecoder(
+        decoder = TesseractSinterDecoder(
             verbose=True,
         )
     else:
-        decoder = tesseract_module.TesseractSinterDecoder()
+        decoder = TesseractSinterDecoder()
 
     decoder.decode_via_files(
         num_shots=num_shots,
@@ -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
@@ -597,7 +597,7 @@ def test_decode_shots_bit_packed_vs_decode_batch(det_beam, beam_climbing, no_rev
     dem = circuit.detector_error_model()
 
     # 2. Compile the Sinter-compatible decoder with the parameterized values for the DEM.
-    sinter_decoder = tesseract_module.TesseractSinterDecoder(
+    sinter_decoder = TesseractSinterDecoder(
         det_beam=det_beam,
         beam_climbing=beam_climbing,
         no_revisit_dets=no_revisit_dets,
@@ -661,7 +661,7 @@ def test_sinter_collect_different_dems():
         tasks=tasks,
         decoders=["tesseract-long-beam"],
         max_shots=100,  # Reduced max_shots for testing
-        custom_decoders=tesseract_module.make_tesseract_sinter_decoders_dict()
+        custom_decoders=make_tesseract_sinter_decoders_dict()
     )
 
     assert len(all_results) == len(tasks)

src/tesseract_sinter_compat.pybind.h

@@ -377,20 +377,24 @@ void pybind_sinter_compat(py::module& root) {
       []() -> py::object {
         auto result = py::dict();
         result["tesseract"] = TesseractSinterDecoder{};
-        result["tesseract-short-beam"] = TesseractSinterDecoder(
-            /*det_beam=*/10, /*beam_climbing=*/false, /*no_revisit_dets=*/true,
-            /*verbose=*/false, /*merge_errors=*/true, /*pqlimit=*/DEFAULT_PQLIMIT,
-            /*det_penalty=*/0.0, /*create_visualization=*/false,
-            /*num_det_orders=*/0, /*det_order_method=*/DetOrder::DetBFS, /*seed=*/2384753);
         result["tesseract-long-beam"] = TesseractSinterDecoder(
-            /*det_beam=*/1000, /*beam_climbing=*/false, /*no_revisit_dets=*/true,
-            /*verbose=*/false, /*merge_errors=*/true, /*pqlimit=*/DEFAULT_PQLIMIT,
+            /*det_beam=*/20, /*beam_climbing=*/true, /*no_revisit_dets=*/true,
+            /*verbose=*/false, /*merge_errors=*/true, /*pqlimit=*/1000000,
             /*det_penalty=*/0.0, /*create_visualization=*/false,
-            /*num_det_orders=*/0, /*det_order_method=*/DetOrder::DetBFS, /*seed=*/2384753);
+            /*num_det_orders=*/21, /*det_order_method=*/DetOrder::DetIndex, /*seed=*/2384753);
+        result["tesseract-short-beam"] = TesseractSinterDecoder(
+            /*det_beam=*/15, /*beam_climbing=*/true, /*no_revisit_dets=*/true,
+            /*verbose=*/false, /*merge_errors=*/true, /*pqlimit=*/200000,
+            /*det_penalty=*/0.0, /*create_visualization=*/false,
+            /*num_det_orders=*/16, /*det_order_method=*/DetOrder::DetIndex, /*seed=*/2384753);
         return result;
       },
       R"pbdoc(
         Returns a dictionary mapping decoder names to sinter.Decoder-style objects.
         This allows Sinter to easily discover and use Tesseract as a custom decoder.
       )pbdoc");
+
+  // Aliases that are visible from the root module.
+  root.attr("TesseractSinterDecoder") = m.attr("TesseractSinterDecoder");
+  root.attr("make_tesseract_sinter_decoders_dict") = m.attr("make_tesseract_sinter_decoders_dict");
 }