Merge branch 'main' into main

Author: noajshu

README.md

@@ -170,13 +170,15 @@ This repository contains the C++ implementation of the Tesseract quantum error c
 The following example demonstrates how to create and use the Tesseract decoder using the Python interface.
 
 ```python
-import tesseract_decoder.tesseract as tesseract
+from tesseract_decoder import tesseract
 import stim
+import numpy as np
+
 
 # 1. Define a detector error model (DEM)
 dem = stim.DetectorErrorModel("""
-    error(0.1) D0 D1
-    error(0.2) D1 D2 L0
+    error(0.1) D0 D1 L0
+    error(0.2) D1 D2 L1
     detector(0, 0, 0) D0
     detector(1, 0, 0) D1
     detector(2, 0, 0) D2
@@ -185,15 +187,24 @@ dem = stim.DetectorErrorModel("""
 # 2. Create the decoder configuration
 config = tesseract.TesseractConfig(dem=dem, det_beam=50)
 
-# 3. Configure and create a decoder instance
-decoder = tesseract.TesseractDecoder(config)
+# 3. Create a decoder instance
+decoder = config.compile_decoder()
 
-# 4. Simulate detection events and decode it
-detections = [1, 2]
-flipped_observables = decoder.decode(detections)
+# 4. Simulate detection events
+syndrome = [0, 1, 1]
 
-print(f"Detections: {detections}")
+# 5a. Decode to observables
+flipped_observables = decoder.decode(syndrome)
 print(f"Flipped observables: {flipped_observables}")
+
+# 5b. Alternatively, decode to errors
+decoder.decode_to_errors(np.where(syndrome)[0])
+predicted_errors = decoder.predicted_errors_buffer
+# Indices of predicted errors
+print(f"Predicted errors indices: {predicted_errors}")
+# Print properties of predicted errors
+for i in predicted_errors:
+    print(f"    {i}: {decoder.errors[i]}")
 ```
 
 

docs/tutorial.ipynb

@@ -846,7 +846,7 @@
         "    pqlimit=1000,\n",
         "    # no_revisit_dets=False,\n",
         "    # at_most_two_errors_per_detector = False,\n",
-        "    det_penalty = False,\n",
+        "    det_penalty = 0,\n",
         "    # det_orders=tesseract_decoder.utils.build_det_orders(\n",
         "    #     dem, num_det_orders=2, det_order_bfs=True, seed=2384753),\n",
         ")\n",
@@ -1613,4 +1613,4 @@
   },
   "nbformat": 4,
   "nbformat_minor": 0
-}
+}

src/common.cc

@@ -29,7 +29,6 @@ common::Error::Error(const stim::DemInstruction& error) {
     throw std::invalid_argument(
         "Error must be loaded from an error dem instruction, but received: " + error.str());
   }
-  assert(error.type == stim::DemInstructionType::DEM_ERROR);
   double probability = error.arg_data[0];
   if (probability < 0 || probability > 1) {
     throw std::invalid_argument("Probability must be between 0 and 1, but received: " +

src/common.test.cc

@@ -98,16 +98,16 @@ TEST(common, RemoveZeroProbabilityErrors) {
 
 // Helper function to compare the two methods.
 void assert_merged_probabilities_are_equal(double p1, double p2) {
-  // Method 1: Merge probabilities directly using the exclusive OR formula.
+  // Merge probabilities using the exclusive OR formula.
   double merged_p_direct = p1 + p2 - 2 * p1 * p2;
 
-  // Method 2: Convert to likelihood costs, merge them, then convert back.
+  // Convert to likelihood costs, merge, and then convert back.
   double cost1 = std::log(p1 / (1 - p1));
   double cost2 = std::log(p2 / (1 - p2));
   double merged_cost = common::merge_weights(cost1, cost2);
   double merged_p_via_costs = 1 / (1 + std::exp(merged_cost));
 
-  // The two methods should produce nearly identical results.
+  // The two methods should produce nearly same results.
   ASSERT_NEAR(merged_p_direct, merged_p_via_costs, 1e-12);
 }
 
@@ -131,7 +131,6 @@ TEST(CommonTest, merge_weights_is_equivalent_to_probability_xor) {
 // Helper function to create a simple DEM with two identical errors.
 stim::DetectorErrorModel create_dem_with_two_errors(double p1, double p2) {
   stim::DetectorErrorModel dem;
-
   std::vector<stim::DemTarget> targets = {stim::DemTarget::relative_detector_id(0)};
 
   dem.append_error_instruction(p1, targets, "");

src/py/common_test.py

@@ -66,7 +66,6 @@ def test_as_dem_instruction_targets():
 def test_error_from_dem_instruction():
     di = stim.DemInstruction("error", [0.125], [stim.target_logical_observable_id(3)])
     error = tesseract_decoder.common.Error(di)
-
     assert str(error) == "Error{cost=1.945910, symptom=Symptom{}}"
 
 def test_error_get_set_probability():

src/py/shared_decoding_tests.py

@@ -10,7 +10,7 @@ def shared_test_compile_decoder(config_class, decoder_class):
     dem_string = "error(0.1) D0 D1 L0"
     dem = stim.DetectorErrorModel(dem_string)
     config = config_class(dem)
-    
+    config.merge_errors = False
     decoder = config.compile_decoder()
 
     assert isinstance(decoder, decoder_class)
@@ -24,31 +24,41 @@ def shared_test_cost_from_errors(decoder_class, config_class):
     predicted error chain. The cost is calculated as the sum of the log-odds
     ratio for each error mechanism.
     """
+
     dem_string = f'''
-        error(0.1) D0 D1 L0
-        error(0.2) D0 L1
-        error(0.05) D1
+        error(0.1) D0 L0
+        error(0.2) D1 L1
+        error(0.3) D2
+        error(0.4) D3 L0 L1
     '''
     dem = stim.DetectorErrorModel(dem_string)
     config = config_class(dem)
+    config.merge_errors = False
     decoder = decoder_class(config)
-    if hasattr(decoder, 'init_ilp'):
-        decoder.init_ilp()
 
-    # Case 1: Test with a single error.
-    # The cost should be ln((1 - 0.1) / 0.1) = ln(9)
-    cost1 = decoder.cost_from_errors([0])
-    assert cost1 == pytest.approx(math.log(9))
+    # Case 1: A single error mechanism that flips one observable (L0).
+    errors1 = [0]
+    decoder.predicted_errors_buffer = errors1
+    cost1 = decoder.cost_from_errors(errors1)
+    assert cost1 == pytest.approx(math.log((1 - 0.1) / 0.1))
 
-    # Case 2: Test with multiple errors.
-    # The cost should be ln(9) + ln((1 - 0.2) / 0.2) = ln(9) + ln(4) +
-    # ln((1 - 0.05) / 0.05) = ln(9) + ln(4) + ln(19)
-    cost2 = decoder.cost_from_errors([0, 1, 2])
-    assert cost2 == pytest.approx(math.log(9) + math.log(4) + math.log(19))
+    # Case 2: A single error mechanism that flips multiple observables (L0, L1).
+    errors2 = [3]
+    decoder.predicted_errors_buffer = errors2
+    cost2 = decoder.cost_from_errors(errors2)
+    assert cost2 == pytest.approx(math.log((1 - 0.4) / 0.4))
 
-    # Case 3: Test with no errors.
-    cost3 = decoder.cost_from_errors([])
-    assert cost3 == pytest.approx(0)
+    # Case 3: Multiple error mechanisms whose effects cancel out (L0 from error 0, L0 from error 3).
+    errors3 = [0, 3]
+    decoder.predicted_errors_buffer = errors3
+    cost3 = decoder.cost_from_errors(errors3)
+    assert cost3 == pytest.approx(math.log((1 - 0.1) / 0.1) + math.log((1 - 0.4) / 0.4))
+
+    # Case 4: No errors.
+    errors4 = []
+    decoder.predicted_errors_buffer = errors4
+    cost4 = decoder.cost_from_errors(errors4)
+    assert cost4 == pytest.approx(0)
 
 def shared_test_get_observables_from_errors(decoder_class, config_class):
     """
@@ -63,45 +73,41 @@ def shared_test_get_observables_from_errors(decoder_class, config_class):
     '''
     dem = stim.DetectorErrorModel(dem_string)
     config = config_class(dem)
+    config.merge_errors = False
     decoder = decoder_class(config)
-    
     num_observables = dem.num_observables
 
     # Case 1: A single error mechanism that flips one observable (L0).
     errors1 = [0]
-    expected1 = np.array([True, False], dtype=bool)
-    predicted1_list = decoder.get_observables_from_errors(errors1)
-    assert isinstance(predicted1_list, list)
-    predicted1_arr = np.array(predicted1_list, dtype=bool)
-    assert predicted1_arr.shape[0] == num_observables
-    assert np.array_equal(predicted1_arr, expected1)
+    predicted_list1 = decoder.get_observables_from_errors(errors1)
+    assert isinstance(predicted_list1, list)
+    predicted_array1 = np.array(predicted_list1, dtype=bool)
+    assert predicted_array1.shape[0] == num_observables
+    assert np.array_equal(predicted_array1, np.array([True, False], dtype=bool))
 
     # Case 2: A single error mechanism that flips multiple observables (L0, L1).
     errors2 = [3]
-    expected2 = np.array([True, True], dtype=bool)
-    predicted2_list = decoder.get_observables_from_errors(errors2)
-    assert isinstance(predicted2_list, list)
-    predicted2_arr = np.array(predicted2_list, dtype=bool)
-    assert predicted2_arr.shape[0] == num_observables
-    assert np.array_equal(predicted2_arr, expected2)
+    predicted_list2 = decoder.get_observables_from_errors(errors2)
+    assert isinstance(predicted_list2, list)
+    predicted_array2 = np.array(predicted_list2, dtype=bool)
+    assert predicted_array2.shape[0] == num_observables
+    assert np.array_equal(predicted_array2, np.array([True, True], dtype=bool))
 
     # Case 3: Multiple error mechanisms whose effects cancel out (L0 from error 0, L0 from error 3).
     errors3 = [0, 3]
-    expected3 = np.array([False, True], dtype=bool)
-    predicted3_list = decoder.get_observables_from_errors(errors3)
-    assert isinstance(predicted3_list, list)
-    predicted3_arr = np.array(predicted3_list, dtype=bool)
-    assert predicted3_arr.shape[0] == num_observables
-    assert np.array_equal(predicted3_arr, expected3)
+    predicted_list3 = decoder.get_observables_from_errors(errors3)
+    assert isinstance(predicted_list3, list)
+    predicted_array3 = np.array(predicted_list3, dtype=bool)
+    assert predicted_array3.shape[0] == num_observables
+    assert np.array_equal(predicted_array3, np.array([False, True], dtype=bool))
 
     # Case 4: No errors.
     errors4 = []
-    expected4 = np.zeros(num_observables, dtype=bool)
-    predicted4_list = decoder.get_observables_from_errors(errors4)
-    assert isinstance(predicted4_list, list)
-    predicted4_arr = np.array(predicted4_list, dtype=bool)
-    assert predicted4_arr.shape[0] == num_observables
-    assert np.array_equal(predicted4_arr, expected4)
+    predicted_list4 = decoder.get_observables_from_errors(errors4)
+    assert isinstance(predicted_list4, list)
+    predicted_array4 = np.array(predicted_list4, dtype=bool)
+    assert predicted_array4.shape[0] == num_observables
+    assert np.array_equal(predicted_array4, np.zeros(num_observables, dtype=bool))
 
 
 def shared_test_decoder_predicts_various_observable_flips(decoder_class, config_class):
@@ -118,8 +124,6 @@ def shared_test_decoder_predicts_various_observable_flips(decoder_class, config_
         config = config_class(dem)
         decoder = decoder_class(config)
 
-        if hasattr(decoder, 'init_ilp'):
-            decoder.init_ilp()
         syndrome = np.zeros(dem.num_detectors, dtype=bool)
         syndrome[0] = True
         predicted_logical_flips_array = decoder.decode(syndrome)
@@ -142,8 +146,6 @@ def shared_test_decode_from_detection_events(decoder_class, config_class):
     dem = stim.DetectorErrorModel(dem_string)
     config = config_class(dem)
     decoder = decoder_class(config)
-    if hasattr(decoder, 'init_ilp'):
-        decoder.init_ilp()
 
     # Case 1: Detections corresponding to the D0 D1 L0 error
     detections1 = [0, 1]
@@ -177,8 +179,6 @@ def shared_test_decode(decoder_class, config_class):
     dem = stim.DetectorErrorModel(dem_string)
     config = config_class(dem)
     decoder = decoder_class(config)
-    if hasattr(decoder, 'init_ilp'):
-        decoder.init_ilp()
 
     syndrome1 = np.array([True, True], dtype=bool)
     predicted1 = decoder.decode(syndrome1)
@@ -205,8 +205,6 @@ def shared_test_decode_complex_dem(decoder_class, config_class):
     dem = stim.DetectorErrorModel(dem_string)
     config = config_class(dem)
     decoder = decoder_class(config)
-    if hasattr(decoder, 'init_ilp'):
-        decoder.init_ilp()
 
     syndrome = np.array([True, True, False], dtype=bool)
     predicted = decoder.decode(syndrome)
@@ -225,8 +223,6 @@ def shared_test_decode_batch_with_invalid_dimensions(decoder_class, config_class
     dem = stim.DetectorErrorModel(dem_string)
     config = config_class(dem)
     decoder = decoder_class(config)
-    if hasattr(decoder, 'init_ilp'):
-        decoder.init_ilp()
     invalid_syndrome = np.array([True, True], dtype=bool)
     with pytest.raises(RuntimeError, match="Input syndromes must be a 2D NumPy array."):
         decoder.decode_batch(invalid_syndrome)
@@ -243,14 +239,12 @@ def shared_test_decode_batch(decoder_class, config_class):
     dem = stim.DetectorErrorModel(dem_string)
     config = config_class(dem)
     decoder = decoder_class(config)
-    if hasattr(decoder, 'init_ilp'):
-        decoder.init_ilp()
-
     syndromes = np.array([
         [True, True],
         [True, False],
         [False, True],
     ], dtype=bool)
+
     predictions = decoder.decode_batch(syndromes)
     assert isinstance(predictions, np.ndarray)
     assert predictions.dtype.type == np.bool_
@@ -276,9 +270,6 @@ def shared_test_decode_batch_with_complex_model(decoder_class, config_class):
     dem = stim.DetectorErrorModel(dem_string)
     config = config_class(dem)
     decoder = decoder_class(config)
-    if hasattr(decoder, 'init_ilp'):
-        decoder.init_ilp()
-
     batch_syndromes = np.array([
         [True, True, False, False],
         [True, False, True, False],
@@ -298,3 +289,70 @@ def shared_test_decode_batch_with_complex_model(decoder_class, config_class):
         [False, False, False],
     ], dtype=bool)
     assert np.array_equal(predictions, expected_predictions)
+
+
+
+def shared_test_merge_errors_affects_cost(decoder_class, config_class):
+    """
+    Test that the error's cost changes based on the 'merge_errors' setting.
+    """
+    dem = stim.DetectorErrorModel(
+        """
+        error(0.1) D0
+        error(0.01) D0
+        """
+    )
+    detections = [0]
+    
+    config_no_merge = config_class(dem, merge_errors=False)
+    decoder_no_merge = decoder_class(config_no_merge)
+    predicted_errors_no_merge = decoder_no_merge.decode_to_errors(detections)
+    cost_no_merge = decoder_no_merge.cost_from_errors(decoder_no_merge.predicted_errors_buffer)
+        
+    config_merge = config_class(dem, merge_errors=True)
+    decoder_merge = decoder_class(config_merge)
+    predicted_errors_merge = decoder_merge.decode_to_errors(detections)
+    cost_merge = decoder_merge.cost_from_errors(decoder_merge.predicted_errors_buffer)
+    
+    p_merged = 0.1 * (1 - 0.01) + 0.01 * (1 - 0.1)
+    expected_cost_no_merge = math.log((1 - 0.1) / 0.1)
+    expected_cost_merge = math.log((1 - p_merged) / p_merged)
+
+    assert predicted_errors_no_merge == predicted_errors_merge
+    assert cost_no_merge == pytest.approx(expected_cost_no_merge)
+    assert cost_merge == pytest.approx(expected_cost_merge)
+    assert cost_no_merge != cost_merge
+
+def shared_test_decode_with_mismatched_syndrome_size(decoder_class, config_class):
+    """
+    Tests that `decode` raises an error when the input syndrome's length does
+    not match the number of detectors in the DEM.
+    """
+    dem_string = f'''
+        error(0.1) D0 D1
+    '''
+    dem = stim.DetectorErrorModel(dem_string)
+    config = config_class(dem)
+    decoder = decoder_class(config)
+
+    # Syndrome has 1 detector, but DEM has 2
+    invalid_syndrome = np.array([True], dtype=bool)
+    with pytest.raises(ValueError, match=r"Syndrome array size \(1\) does not match the number of detectors in the decoder \(2\)\."):
+        decoder.decode(invalid_syndrome)
+
+def shared_test_decode_batch_with_mismatched_syndrome_size(decoder_class, config_class):
+    """
+    Tests that `decode_batch` raises an error when the input syndromes' width
+    does not match the number of detectors in the DEM.
+    """
+    dem_string = f'''
+        error(0.1) D0 D1
+    '''
+    dem = stim.DetectorErrorModel(dem_string)
+    config = config_class(dem)
+    decoder = decoder_class(config)
+
+    # Syndrome batch has 1 column, but DEM has 2
+    invalid_syndromes = np.array([[True], [False]], dtype=bool)
+    with pytest.raises(ValueError, match=r"The number of detectors in the input array \(1\) does not match the number of detectors in the decoder \(2\)."):
+        decoder.decode_batch(invalid_syndromes)