Remove local tables

.gitignore

@@ -34,3 +34,6 @@ build.ninja
 .ninja_log
 .clwb
 .vscode
+.venv
+benchmarks/fastgap/dems
+benchmarks/fastgap/indices

BUILD

@@ -53,6 +53,7 @@ cc_test(
     srcs = SOURCE_FILES_NO_MAIN + TEST_FILES,
     copts = [
         "-std=c++20",
+        "-DFASTGAP_CHECK",
     ],
     data = glob(["testdata/**"]),
     includes = ["src/"],

CMakeLists.txt

@@ -60,6 +60,25 @@ set(SOURCE_FILES_NO_MAIN
         src/pymatching/rand/rand_gen.cc
         )
 
+# fastgap: certified complementary-gap lower bounds from the decoder's final dual state.
+set(FASTGAP_SOURCE_FILES
+        src/pymatching/fastgap/canonical.cc
+        src/pymatching/fastgap/interior_graph.cc
+        src/pymatching/fastgap/dual_state.cc
+        src/pymatching/fastgap/gap_index.cc
+        src/pymatching/fastgap/gap_decoder.cc
+        src/pymatching/fastgap/exact.cc
+        )
+
+set(FASTGAP_TEST_FILES
+        src/pymatching/fastgap/canonical.test.cc
+        src/pymatching/fastgap/interior_graph.test.cc
+        src/pymatching/fastgap/dual_state.test.cc
+        src/pymatching/fastgap/gap_index.test.cc
+        src/pymatching/fastgap/gap_decoder.test.cc
+        src/pymatching/fastgap/exact.test.cc
+        )
+
 set(TEST_FILES
         src/pymatching/sparse_blossom/driver/namespaced_main.test.cc
         src/pymatching/sparse_blossom/driver/mwpm_decoding.test.cc
@@ -109,7 +128,9 @@ install(TARGETS pymatching RUNTIME DESTINATION bin)
 
 enable_testing()
 
-add_executable(pymatching_tests ${SOURCE_FILES_NO_MAIN} ${TEST_FILES})
+add_executable(pymatching_tests ${SOURCE_FILES_NO_MAIN} ${TEST_FILES} ${FASTGAP_SOURCE_FILES} ${FASTGAP_TEST_FILES})
+# fastgap's debug invariants (CLAUDE.md §5.1) are always on in tests.
+target_compile_definitions(pymatching_tests PRIVATE FASTGAP_CHECK)
 target_compile_options(pymatching_tests PRIVATE -fsanitize=address -g -fsanitize=undefined -fno-omit-frame-pointer -coverage)
 if (NOT (MSVC))
     target_link_options(pymatching_tests PRIVATE -pthread -fsanitize=address -fsanitize=undefined -coverage)
@@ -144,6 +165,17 @@ IF(EXISTS ${CMAKE_CURRENT_LIST_DIR}/pybind11/CMakeLists.txt)
     pybind11_add_module(_cpp_pymatching ${PYTHON_API_FILES} ${SOURCE_FILES_NO_MAIN})
     target_link_libraries(_cpp_pymatching PRIVATE libstim)
     target_compile_options(_cpp_pymatching PRIVATE ${ARCH_OPT})
+
+    pybind11_add_module(_cpp_fastgap src/pymatching/fastgap/fastgap.pybind.cc ${SOURCE_FILES_NO_MAIN} ${FASTGAP_SOURCE_FILES})
+    target_link_libraries(_cpp_fastgap PRIVATE libstim)
+    target_compile_options(_cpp_fastgap PRIVATE ${ARCH_OPT})
+    # setup.py builds both extensions from one CMake tree; each lands in its own package directory.
+    if (DEFINED PYMATCHING_PY_OUTPUT_DIR)
+        set_target_properties(_cpp_pymatching PROPERTIES LIBRARY_OUTPUT_DIRECTORY ${PYMATCHING_PY_OUTPUT_DIR})
+    endif ()
+    if (DEFINED FASTGAP_PY_OUTPUT_DIR)
+        set_target_properties(_cpp_fastgap PROPERTIES LIBRARY_OUTPUT_DIRECTORY ${FASTGAP_PY_OUTPUT_DIR})
+    endif ()
 else()
     message("WARNING: Skipped the pybind11 module _cpp_pymatching because the `pybind11` git submodule isn't present. To fix, run `git submodule update --init --recursive`")
 endif()

benchmarks/fastgap/README.md

@@ -0,0 +1,24 @@
+# fastgap benchmarks
+
+Everything here can be regenerated from the repository root, with the package installed:
+
+```
+PYTHON=python benchmarks/fastgap/run_bench.sh
+```
+
+| File | What |
+|---|---|
+| `index_config.json` | DEM list (rotated surface-code memory, uniform circuit noise `p`, `d` rounds unless `rounds` is set), index parameters (strategy, K, table radius) and bench parameters (shots, warm-up, threads per shot, seed) |
+| `gen_dems.py` | writes `dems/<name>.dem` from the config (git-ignored; deterministic) |
+| `run_bench.sh` | for every DEM: `build-index`, `bench` and `landmark-report` |
+| `results/<name>.csv` | raw per-shot rows: `shot, num_defects, w_star, gap_exact, gap_lb, gap_ub, t_decode_ns, t_gap_ns, t_exact_ns, walk_simple, all_hops_exact, censored, strategy_hash`, then `t_gap_ns_t<T>` for each thread count `T` in `bench.threads` (`t_gap_ns` is T = 1), then the exact baseline's two decodes timed separately: `t_exact_mstar_ns` (the decode in the class of M*) and `t_exact_comp_ns` (the complementary-class decode, i.e. the baseline's cost of the gap) |
+| `results/<name>.summary.json` | per-shot latency percentiles only: compute-only (`latency_ns_by_threads`: decode, gap and total stages, at T = 1 and at each `T` in `bench.threads`) and end-to-end (`end_to_end_ns_by_threads`), the exact baseline's latency (`exact_ns`), its two decodes separately (`exact_mstar_decode_ns`, `exact_comp_decode_ns`), the gap-computation speed-up (`gap_speedup_vs_exact_by_threads`: baseline complementary-decode latency / fastgap gap-stage latency, at the median, p99 and p99.9), plus the soundness count |
+| `results/<name>.index.json` | index build report: landmarks, memory, hash |
+| `results/<name>.landmarks.json` | tightness report (CLAUDE.md §7.5) |
+| `results/soundness_1e5.jsonl` | stats logged by the 10^5-shot §9.3/§9.4 test run (`FASTGAP_TEST_LOG=...`) |
+
+`T` is the number of threads that cooperate on *one* shot's gap search (intra-shot parallelism).
+Shots are always decoded one after another, so there are no throughput numbers.
+
+Gaps and weights in the CSV are in nats. The exact gap comes from the two-decode baseline on the
+same canonical graph.

benchmarks/fastgap/gen_dems.py

@@ -0,0 +1,36 @@
+"""Writes the benchmark DEMs (rotated surface-code memory, uniform circuit noise) to dems/.
+
+Usage: python benchmarks/fastgap/gen_dems.py
+"""
+
+import json
+import pathlib
+
+import stim
+
+HERE = pathlib.Path(__file__).parent
+CONFIG = json.loads((HERE / "index_config.json").read_text())
+
+
+def main():
+    out = HERE / "dems"
+    out.mkdir(exist_ok=True)
+    for cfg in CONFIG["dems"]:
+        p = cfg["p"]
+        circuit = stim.Circuit.generated(
+            cfg["task"],
+            distance=cfg["d"],
+            rounds=cfg.get("rounds", cfg["d"]),
+            after_clifford_depolarization=p,
+            before_round_data_depolarization=p,
+            before_measure_flip_probability=p,
+            after_reset_flip_probability=p,
+        )
+        dem = circuit.detector_error_model(decompose_errors=True)
+        path = out / f"{cfg['name']}.dem"
+        dem.to_file(path)
+        print(path, dem.num_detectors, "detectors")
+
+
+if __name__ == "__main__":
+    main()

benchmarks/fastgap/index_config.json

@@ -0,0 +1,13 @@
+{
+  "index": {"strategy": "auto", "num_landmarks": 16, "observable": 0},
+  "bench": {"shots": 20000, "warmup": 1000, "threads": [4], "seed": 2026, "e2e_shots": 2000},
+  "dems": [
+    {"name": "rmx_d5_p5e-3", "task": "surface_code:rotated_memory_x", "d": 5, "p": 0.005},
+    {"name": "rmx_d7_p5e-3", "task": "surface_code:rotated_memory_x", "d": 7, "p": 0.005},
+    {"name": "rmx_d5_p1e-3", "task": "surface_code:rotated_memory_x", "d": 5, "p": 0.001},
+    {"name": "rmx_d9_p1e-3", "task": "surface_code:rotated_memory_x", "d": 9, "p": 0.001},
+    {"name": "rmx_d13_p1e-3", "task": "surface_code:rotated_memory_x", "d": 13, "p": 0.001},
+    {"name": "rmx_d15_p1e-3", "task": "surface_code:rotated_memory_x", "d": 15, "p": 0.001},
+    {"name": "rmx_d17_p1e-3", "task": "surface_code:rotated_memory_x", "d": 17, "p": 0.001}
+  ]
+}