Add multi-pass infrastructure libraries

Add foundational libraries for multi-pass decoding:
- bern_utils: Bernoulli probability utilities (log-likelihood
  conversion, probability clamping)
- tanner_graph: Union-Find-based connected component analysis of
  the detector-error Tanner graph
- error_correlations: Correlation extraction pipeline computing
  marginal, joint, and conditional error probabilities from
  first-pass decoding results
- dem_decomposition: DEM decomposition by detector class, error
  splitting across components, observable assignment, and DEM
  merging for multi-component decoding

Author: oscarhiggott

CMakeLists.txt

@@ -3,6 +3,7 @@ project(tesseract_decoder LANGUAGES CXX)
 
 set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -include cstdint")
 
 include(FetchContent)
 find_package(Threads REQUIRED)
@@ -73,7 +74,7 @@ FetchContent_Declare(
 FetchContent_MakeAvailable(googletest)
 
 
-set(OPT_COPTS -Ofast -fno-fast-math -march=native)
+set(OPT_COPTS -Ofast -fno-fast-math -march=native -include cstdint)
 
 set(TESSERACT_SRC_DIR ${CMAKE_CURRENT_SOURCE_DIR}/src)
 
@@ -93,6 +94,25 @@ target_include_directories(visualization PUBLIC ${TESSERACT_SRC_DIR})
 target_compile_options(visualization PRIVATE ${OPT_COPTS})
 target_link_libraries(visualization PUBLIC common boost_headers)
 
+add_library(bern_utils ${TESSERACT_SRC_DIR}/bern_utils.cc ${TESSERACT_SRC_DIR}/bern_utils.h)
+target_include_directories(bern_utils PUBLIC ${TESSERACT_SRC_DIR})
+target_compile_options(bern_utils PRIVATE ${OPT_COPTS})
+
+add_library(error_correlations ${TESSERACT_SRC_DIR}/error_correlations.cc ${TESSERACT_SRC_DIR}/error_correlations.h)
+target_include_directories(error_correlations PUBLIC ${TESSERACT_SRC_DIR})
+target_compile_options(error_correlations PRIVATE ${OPT_COPTS})
+target_link_libraries(error_correlations PUBLIC libstim)
+
+add_library(tanner_graph ${TESSERACT_SRC_DIR}/tanner_graph.cc ${TESSERACT_SRC_DIR}/tanner_graph.h)
+target_include_directories(tanner_graph PUBLIC ${TESSERACT_SRC_DIR})
+target_compile_options(tanner_graph PRIVATE ${OPT_COPTS})
+target_link_libraries(tanner_graph PUBLIC libstim)
+
+add_library(dem_decomposition ${TESSERACT_SRC_DIR}/dem_decomposition.cc ${TESSERACT_SRC_DIR}/dem_decomposition.h)
+target_include_directories(dem_decomposition PUBLIC ${TESSERACT_SRC_DIR})
+target_compile_options(dem_decomposition PRIVATE ${OPT_COPTS})
+target_link_libraries(dem_decomposition PUBLIC bern_utils libstim)
+
 add_library(tesseract_lib ${TESSERACT_SRC_DIR}/tesseract.cc ${TESSERACT_SRC_DIR}/tesseract.h)
 target_include_directories(tesseract_lib PUBLIC ${TESSERACT_SRC_DIR})
 target_compile_options(tesseract_lib PRIVATE ${OPT_COPTS})
@@ -117,13 +137,12 @@ target_link_libraries(simplex_bin PRIVATE common simplex argparse::argparse nloh
 pybind11_add_module(_core MODULE ${TESSERACT_SRC_DIR}/tesseract.pybind.cc)
 target_compile_options(_core PRIVATE ${OPT_COPTS})
 target_include_directories(_core PRIVATE ${TESSERACT_SRC_DIR})
-target_link_libraries(_core PRIVATE common utils simplex tesseract_lib)
 set_target_properties(_core PROPERTIES
-    LIBRARY_OUTPUT_DIRECTORY ${PROJECT_SOURCE_DIR}/src
-    LIBRARY_OUTPUT_DIRECTORY_DEBUG ${PROJECT_SOURCE_DIR}/src
-    LIBRARY_OUTPUT_DIRECTORY_RELEASE ${PROJECT_SOURCE_DIR}/src
-    LIBRARY_OUTPUT_DIRECTORY_MINSIZEREL ${PROJECT_SOURCE_DIR}/src
-    LIBRARY_OUTPUT_DIRECTORY_RELWITHDEBINFO ${PROJECT_SOURCE_DIR}/src
+    LIBRARY_OUTPUT_DIRECTORY ${PROJECT_SOURCE_DIR}/tesseract_decoder
+    LIBRARY_OUTPUT_DIRECTORY_DEBUG ${PROJECT_SOURCE_DIR}/tesseract_decoder
+    LIBRARY_OUTPUT_DIRECTORY_RELEASE ${PROJECT_SOURCE_DIR}/tesseract_decoder
+    LIBRARY_OUTPUT_DIRECTORY_MINSIZEREL ${PROJECT_SOURCE_DIR}/tesseract_decoder
+    LIBRARY_OUTPUT_DIRECTORY_RELWITHDEBINFO ${PROJECT_SOURCE_DIR}/tesseract_decoder
 )
 
 # === Tests ===
@@ -137,3 +156,15 @@ add_executable(tesseract_test ${TESSERACT_SRC_DIR}/tesseract.test.cc)
 target_link_libraries(tesseract_test PRIVATE tesseract_lib simplex GTest::gtest_main)
 add_test(NAME tesseract_test COMMAND tesseract_test)
 
+add_executable(dem_decomposition_test ${TESSERACT_SRC_DIR}/dem_decomposition.test.cc)
+target_link_libraries(dem_decomposition_test PRIVATE dem_decomposition GTest::gtest_main libstim)
+add_test(NAME dem_decomposition_test COMMAND dem_decomposition_test)
+
+add_executable(tanner_graph_test ${TESSERACT_SRC_DIR}/tanner_graph.test.cc)
+target_link_libraries(tanner_graph_test PRIVATE tanner_graph GTest::gtest_main libstim)
+add_test(NAME tanner_graph_test COMMAND tanner_graph_test)
+
+add_executable(error_correlations_test ${TESSERACT_SRC_DIR}/error_correlations.test.cc)
+target_link_libraries(error_correlations_test PRIVATE error_correlations GTest::gtest_main libstim)
+add_test(NAME error_correlations_test COMMAND error_correlations_test)
+

src/BUILD

@@ -93,7 +93,6 @@ pybind_extension(
 )
 
 
-
 cc_library(
     name = "libutils",
     srcs = ["utils.cc"],
@@ -133,6 +132,87 @@ cc_library(
     ],
 )
 
+cc_library(
+    name = "liberror_correlations",
+    srcs = ["error_correlations.cc"],
+    hdrs = ["error_correlations.h"],
+    copts = OPT_COPTS,
+    linkopts = OPT_LINKOPTS,
+    deps = [
+        "@stim//:stim_lib",
+    ],
+)
+
+cc_test(
+    name = "error_correlations_tests",
+    srcs = ["error_correlations.test.cc"],
+    copts = OPT_COPTS,
+    linkopts = OPT_LINKOPTS,
+    deps = [
+        ":liberror_correlations",
+        "@gtest",
+        "@gtest//:gtest_main",
+        "@stim//:stim_lib",
+    ],
+)
+
+cc_library(
+    name = "libtanner_graph",
+    srcs = ["tanner_graph.cc"],
+    hdrs = ["tanner_graph.h"],
+    copts = OPT_COPTS,
+    linkopts = OPT_LINKOPTS,
+    deps = [
+        "@stim//:stim_lib",
+    ],
+)
+
+cc_test(
+    name = "tanner_graph_tests",
+    srcs = ["tanner_graph.test.cc"],
+    copts = OPT_COPTS,
+    linkopts = OPT_LINKOPTS,
+    deps = [
+        ":libtanner_graph",
+        "@gtest",
+        "@gtest//:gtest_main",
+        "@stim//:stim_lib",
+    ],
+)
+
+cc_library(
+    name = "libbern_utils",
+    srcs = ["bern_utils.cc"],
+    hdrs = ["bern_utils.h"],
+    copts = OPT_COPTS,
+    linkopts = OPT_LINKOPTS,
+)
+
+cc_library(
+    name = "libdem_decomposition",
+    srcs = ["dem_decomposition.cc"],
+    hdrs = ["dem_decomposition.h"],
+    copts = OPT_COPTS,
+    linkopts = OPT_LINKOPTS,
+    deps = [
+        ":libbern_utils",
+        "@stim//:stim_lib",
+    ],
+)
+
+cc_test(
+    name = "dem_decomposition_tests",
+    srcs = ["dem_decomposition.test.cc"],
+    copts = OPT_COPTS,
+    linkopts = OPT_LINKOPTS,
+    deps = [
+        ":libdem_decomposition",
+        "@gtest",
+        "@gtest//:gtest_main",
+        "@stim//:stim_lib",
+    ],
+)
+
 cc_binary(
     name = "tesseract",
     srcs = ["tesseract_main.cc"],

src/bern_utils.cc

@@ -0,0 +1,21 @@
+#include "bern_utils.h"
+#include <cmath>
+#include <limits>
+
+namespace tesseract {
+
+double bernoulli_xor(double p1, double p2) {
+    return p1 * (1 - p2) + p2 * (1 - p1);
+}
+
+double to_weight(double probability) {
+    if (probability >= 1.0) {
+        return -std::numeric_limits<double>::infinity();
+    }
+    if (probability <= 0) {
+        return std::numeric_limits<double>::infinity();
+    }
+    return std::log((1 - probability) / probability);
+}
+
+} // namespace two_pass_decoding

src/bern_utils.h

@@ -0,0 +1,17 @@
+#ifndef BERN_UTILS_H
+#define BERN_UTILS_H
+
+namespace tesseract {
+
+// Calculates the probability of an odd number of independent events with
+// probabilities p1 and p2 occurring: p1*(1-p2) + p2*(1-p1).
+double bernoulli_xor(double p1, double p2);
+
+// Converts a probability to a log-likelihood ratio weight.
+// The weight is calculated as w = ln((1-p)/p).
+double to_weight(double probability);
+
+} // namespace two_pass_decoding
+
+#endif // BERN_UTILS_H
+