Refactor det order creation, restore optional index-based det ordering (#112)

noajshu · NoureldinYosri · web-flow · commit 129471096e8a · 2025-08-29T14:21:20.000-07:00
In the paper we used detector indices to sort them and make the det orders. This was actually an accident where we were trying to use the 3d coordinates (xyt) from Stim but used Stim incorrectly (my bad). This got fixed in a77f5e7 where we started using the actual xyt coordinates. This seems to offer a better tradeoff between beam and error rate, but also led to issue #103 because at the same large beam we get worse performance (likely because there are more distinct orderings which means more ways to get stuck) We also added BFS det ordering in bf62f84 and then made it the default in 0471d4e Unfortunately due to a bug in p-ranav's argparse: p-ranav/argparse#413 flags with implicit_value(false) do not work with store_into, which means the `--no-det-order-bfs` arg had no effect. Here, we refactor the det order creation to have 3 arguments: ``` --det-order-bfs Use BFS-based detector ordering (default if no method specified) --det-order-index Randomly choose increasing or decreasing detector index order --det-order-coordinate Random geometric detector orientation ordering ``` We also eliminate `--no-det-order-bfs` which had no effect anyways. This is an example where the `--det-order-index` is faster: ``` bazel build src:all ./bazel-bin/src/tesseract --sample-num-shots 100 --circuit testdata/colorcodes/r\=11\,d\=11\,p\=0.001\,noise\=si1000\,c\=superdense_color_code_X\,q\=181\,gates\=cz.stim --sample-seed 71734 --threads 64 --beam 20 --beam-climbing --num-det-orders 21 --pqlimit 1000000 --det-order-seed 2384257 --print-stats --no-revisit-dets --det-order-coordinate num_shots = 100 num_low_confidence = 0 num_errors = 0 total_time_seconds = 340.9752209999999 ./bazel-bin/src/tesseract --sample-num-shots 100 --circuit testdata/colorcodes/r\=11\,d\=11\,p\=0.001\,noise\=si1000\,c\=superdense_color_code_X\,q\=181\,gates\=cz.stim --sample-seed 71734 --threads 64 --beam 20 --beam-climbing --num-det-orders 21 --pqlimit 1000000 --det-order-seed 2384257 --print-stats --no-revisit-dets --det-order-index num_shots = 100 num_low_confidence = 0 num_errors = 0 total_time_seconds = 142.994753 ``` This is achieved via a new enum class `DetOrder` in utils. It is also now exposed via python API: ``` tesseract_decoder.utils.build_det_orders( _DETECTOR_ERROR_MODEL, num_det_orders=1, method=tesseract_decoder.utils.DetOrder.DetIndex, seed=0, ``` Fixes #103 --------- Co-authored-by: Noureldin <noureldinyosri@gmail.com>
diff --git a/src/py/utils_test.py b/src/py/utils_test.py
@@ -50,12 +50,25 @@ def test_build_det_orders():
     ) == [[0, 1]]
 
 
-def test_build_det_orders_no_bfs():
+def test_build_det_orders_coordinate():
     assert tesseract_decoder.utils.build_det_orders(
-        _DETECTOR_ERROR_MODEL, num_det_orders=1, det_order_bfs=False, seed=0
+        _DETECTOR_ERROR_MODEL,
+        num_det_orders=1,
+        method=tesseract_decoder.utils.DetOrder.DetCoordinate,
+        seed=0,
     ) == [[0, 1]]
 
 
+def test_build_det_orders_index():
+    res = tesseract_decoder.utils.build_det_orders(
+        _DETECTOR_ERROR_MODEL,
+        num_det_orders=1,
+        method=tesseract_decoder.utils.DetOrder.DetIndex,
+        seed=0,
+    )
+    assert res == [[0, 1]] or res == [[1, 0]]
+
+
 def test_get_errors_from_dem():
     expected = "Error{cost=1.945910, symptom=Symptom{detectors=[0], observables=[]}}, Error{cost=0.510826, symptom=Symptom{detectors=[0 1], observables=[]}}, Error{cost=1.098612, symptom=Symptom{detectors=[1], observables=[]}}"
     assert (
diff --git a/src/tesseract.pybind.h b/src/tesseract.pybind.h
@@ -41,7 +41,7 @@ TesseractConfig tesseract_config_maker_no_dem(
     double det_penalty = 0.0, bool create_visualization = false) {
   stim::DetectorErrorModel empty_dem;
   if (det_orders.empty()) {
-    det_orders = build_det_orders(empty_dem, 20, /*det_order_bfs=*/true, 2384753);
+    det_orders = build_det_orders(empty_dem, 20, DetOrder::DetBFS, 2384753);
   }
   return TesseractConfig({empty_dem, det_beam, beam_climbing, no_revisit_dets,
                           at_most_two_errors_per_detector, verbose, merge_errors, pqlimit,
@@ -57,7 +57,7 @@ TesseractConfig tesseract_config_maker(
     double det_penalty = 0.0, bool create_visualization = false) {
   stim::DetectorErrorModel input_dem = parse_py_object<stim::DetectorErrorModel>(dem);
   if (det_orders.empty()) {
-    det_orders = build_det_orders(input_dem, 20, true, 2384753);
+    det_orders = build_det_orders(input_dem, 20, DetOrder::DetBFS, 2384753);
   }
   return TesseractConfig({input_dem, det_beam, beam_climbing, no_revisit_dets,
                           at_most_two_errors_per_detector, verbose, merge_errors, pqlimit,
diff --git a/src/tesseract_main.cc b/src/tesseract_main.cc
@@ -34,7 +34,9 @@ struct Args {
   // Manifold orientation options
   uint64_t det_order_seed;
   size_t num_det_orders = 10;
-  bool det_order_bfs = true;
+  bool det_order_bfs = false;
+  bool det_order_index = false;
+  bool det_order_coordinate = false;
 
   // Sampling options
   size_t sample_num_shots = 0;
@@ -88,6 +90,12 @@ struct Args {
       throw std::invalid_argument("Must provide at least one of --circuit or --dem");
     }
 
+    int det_order_flags = int(det_order_bfs) + int(det_order_index) + int(det_order_coordinate);
+    if (det_order_flags > 1) {
+      throw std::invalid_argument(
+          "Only one of --det-order-bfs, --det-order-index, or --det-order-coordinate may be set.");
+    }
+
     int num_data_sources = int(sample_num_shots > 0) + int(!in_fname.empty());
     if (num_data_sources != 1) {
       throw std::invalid_argument("Requires exactly 1 source of shots.");
@@ -180,8 +188,13 @@ struct Args {
           std::cout << ")" << std::endl;
         }
       }
-      config.det_orders =
-          build_det_orders(config.dem, num_det_orders, det_order_bfs, det_order_seed);
+      DetOrder order = DetOrder::DetBFS;
+      if (det_order_index) {
+        order = DetOrder::DetIndex;
+      } else if (det_order_coordinate) {
+        order = DetOrder::DetCoordinate;
+      }
+      config.det_orders = build_det_orders(config.dem, num_det_orders, order, det_order_seed);
     }
 
     if (sample_num_shots > 0) {
@@ -296,21 +309,18 @@ int main(int argc, char* argv[]) {
       .metavar("N")
       .default_value(size_t(1))
       .store_into(args.num_det_orders);
-  program.add_argument("--no-det-order-bfs")
-      .help("Disable BFS-based detector ordering and use geometric orientation")
-      .default_value(true)
-      .implicit_value(false)
-      .store_into(args.det_order_bfs);
   program.add_argument("--det-order-bfs")
-      .action([&](auto const&) {
-        std::cout << "BFS-based detector ordering is the default now; "
-                     "--det-order-bfs is ignored."
-                  << std::endl;
-      })
-      .default_value(true)
-      .implicit_value(true)
-      .store_into(args.det_order_bfs)
-      .hidden();
+      .help("Use BFS-based detector ordering (default if no method specified)")
+      .flag()
+      .store_into(args.det_order_bfs);
+  program.add_argument("--det-order-index")
+      .help("Randomly choose increasing or decreasing detector index order")
+      .flag()
+      .store_into(args.det_order_index);
+  program.add_argument("--det-order-coordinate")
+      .help("Random geometric detector orientation ordering")
+      .flag()
+      .store_into(args.det_order_coordinate);
   program.add_argument("--det-order-seed")
       .help(
           "Seed used when initializing the random detector traversal "
diff --git a/src/utils.cc b/src/utils.cc
@@ -83,15 +83,15 @@ std::vector<std::vector<size_t>> build_detector_graph(const stim::DetectorErrorM
 }
 
 std::vector<std::vector<size_t>> build_det_orders(const stim::DetectorErrorModel& dem,
-                                                  size_t num_det_orders, bool det_order_bfs,
+                                                  size_t num_det_orders, DetOrder method,
                                                   uint64_t seed) {
   std::vector<std::vector<size_t>> det_orders(num_det_orders);
   std::mt19937_64 rng(seed);
   std::normal_distribution<double> dist(0, 1);
 
   auto detector_coords = get_detector_coords(dem);
 
-  if (det_order_bfs) {
+  if (method == DetOrder::DetBFS) {
     auto graph = build_detector_graph(dem);
     std::uniform_int_distribution<size_t> dist_det(0, graph.size() - 1);
     for (size_t det_order = 0; det_order < num_det_orders; ++det_order) {
@@ -131,7 +131,7 @@ std::vector<std::vector<size_t>> build_det_orders(const stim::DetectorErrorModel
       }
       det_orders[det_order] = inv_perm;
     }
-  } else {
+  } else if (method == DetOrder::DetCoordinate) {
     std::vector<double> inner_products(dem.count_detectors());
     if (!detector_coords.size() || !detector_coords.at(0).size()) {
       for (size_t det_order = 0; det_order < num_det_orders; ++det_order) {
@@ -163,6 +163,19 @@ std::vector<std::vector<size_t>> build_det_orders(const stim::DetectorErrorModel
         det_orders[det_order] = inv_perm;
       }
     }
+  } else if (method == DetOrder::DetIndex) {
+    std::uniform_int_distribution<int> dist_bool(0, 1);
+    size_t n = dem.count_detectors();
+    for (size_t det_order = 0; det_order < num_det_orders; ++det_order) {
+      det_orders[det_order].resize(n);
+      if (dist_bool(rng)) {
+        for (size_t i = 0; i < n; ++i) {
+          det_orders[det_order][i] = n - 1 - i;
+        }
+      } else {
+        std::iota(det_orders[det_order].begin(), det_orders[det_order].end(), 0);
+      }
+    }
   }
   return det_orders;
 }
diff --git a/src/utils.h b/src/utils.h
@@ -34,8 +34,11 @@ std::vector<std::vector<double>> get_detector_coords(const stim::DetectorErrorMo
 // in the model activates them both.
 std::vector<std::vector<size_t>> build_detector_graph(const stim::DetectorErrorModel& dem);
 
+enum class DetOrder { DetBFS, DetIndex, DetCoordinate };
+
 std::vector<std::vector<size_t>> build_det_orders(const stim::DetectorErrorModel& dem,
-                                                  size_t num_det_orders, bool det_order_bfs = true,
+                                                  size_t num_det_orders,
+                                                  DetOrder method = DetOrder::DetBFS,
                                                   uint64_t seed = 0);
 
 const double INF = std::numeric_limits<double>::infinity();
diff --git a/src/utils.pybind.h b/src/utils.pybind.h
@@ -32,6 +32,12 @@ void add_utils_module(py::module& root) {
   m.attr("INF") = INF;
   m.doc() = "A representation of infinity for floating point numbers.";
 
+  py::enum_<DetOrder>(m, "DetOrder", "Detector ordering methods")
+      .value("DetBFS", DetOrder::DetBFS)
+      .value("DetIndex", DetOrder::DetIndex)
+      .value("DetCoordinate", DetOrder::DetCoordinate)
+      .export_values();
+
   m.def(
       "get_detector_coords",
       [](py::object dem) {
@@ -79,11 +85,11 @@ void add_utils_module(py::module& root) {
     )pbdoc");
   m.def(
       "build_det_orders",
-      [](py::object dem, size_t num_det_orders, bool det_order_bfs, uint64_t seed) {
+      [](py::object dem, size_t num_det_orders, DetOrder method, uint64_t seed) {
         auto input_dem = parse_py_object<stim::DetectorErrorModel>(dem);
-        return build_det_orders(input_dem, num_det_orders, det_order_bfs, seed);
+        return build_det_orders(input_dem, num_det_orders, method, seed);
       },
-      py::arg("dem"), py::arg("num_det_orders"), py::arg("det_order_bfs") = true,
+      py::arg("dem"), py::arg("num_det_orders"), py::arg("method") = DetOrder::DetBFS,
       py::arg("seed") = 0, R"pbdoc(
         Generates various detector orderings for decoding.
 
@@ -93,17 +99,19 @@ void add_utils_module(py::module& root) {
             The detector error model to generate orders for.
         num_det_orders : int
             The number of detector orderings to generate.
-        det_order_bfs : bool, default=True
-            If True, uses a Breadth-First Search (BFS) to generate
-            the orders. If False, uses a randomized ordering.
+        method : tesseract_decoder.utils.DetOrder, default=tesseract_decoder.utils.DetOrder.DetBFS
+            Strategy for ordering detectors. ``DetBFS`` performs a breadth-first
+            traversal, ``DetCoordinate`` uses randomized geometric orientations,
+            and ``DetIndex`` chooses either increasing or decreasing detector
+            index order at random.
         seed : int, default=0
             A seed for the random number generator.
 
         Returns
         -------
         list[list[int]]
-            A list of detector orderings. Each inner list is a
-            permutation of the detector indices.
+            A list of detector orderings. Each inner list maps a detector index
+            to its position in the ordering.
     )pbdoc");
   m.def(
       "get_errors_from_dem",
