refactor(parallel)!: ♻️ replace the partition runtime with sharded OpenMP

.devcontainer/Dockerfile

@@ -9,6 +9,7 @@ RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
     | grep -v '^$' \
     | xargs apt-get -y install \
     clang \
+    libomp-dev \
     clang-tidy \
     clang-format \
     cmake \

.github/actions/setup/action.yml

@@ -69,8 +69,16 @@ runs:
           esac
         fi
 
+        # OpenMP is required. g++ ships libgomp; a Linux Clang needs the libomp of its own
+        # version, even when the runner already provides the compiler.
+        if [[ "$RUNNER_OS" != "macOS" && "${CXX:-}" == clang++* ]]; then
+          packages+=("libomp${CXX#clang++}-dev")
+        fi
+
         if [[ "$RUNNER_OS" == "macOS" ]]; then
           brew install "${packages[@]}"
+          # Homebrew's libomp is keg-only; CMake's FindOpenMP searches OpenMP_ROOT.
+          echo "OpenMP_ROOT=$(brew --prefix libomp)" >> "$GITHUB_ENV"
         else
           sudo apt-get update
           sudo apt-get install -y "${packages[@]}"

.github/tsan-libomp.supp

@@ -0,0 +1,4 @@
+# ThreadSanitizer suppressions for LLVM's OpenMP runtime: its internal locking is not instrumented, so races
+# reported from inside libomp itself are not evidence (docs/content/docs/building.mdx). Archer
+# (OMP_TOOL_LIBRARIES=.../libarcher.so) supplies the OpenMP synchronization TSan needs for monoprop's own frames.
+called_from_lib:libomp.so.5

.github/workflows/bench.yml

@@ -15,8 +15,9 @@ on:
         type: string
       rungs:
         description: >-
-          One rung per line, `<name> <ranks> <partitions> <rounds> | <pytest args>`.
-          `partitions` is an integer or `per-rank` for (physical cores / ranks).
+          One rung per line, `<name> <ranks> <threads> <rounds> | <pytest args>`.
+          `threads` (OpenMP threads, and so shards, per rank) is an integer or `per-rank` for
+          (physical cores / ranks).
           Blank lines and `#` comments are ignored. A name may carry a `.suffix`: the
           Bencher testbed is the part before the first `.`, so rungs sharing a prefix
           share a plot, which is how one shape measured by two processes keeps its rows
@@ -47,7 +48,7 @@ jobs:
         with:
           # A cache filled by a non-MPI build would restore a monoprop without MPI, which every
           # rung below then shares.
-          cache-suffix: benchmark-mpi
+          cache-suffix: benchmark-mpi-sharded
           # The build below requires MPI::MPI_CXX, and the multi-rank rungs need mpiexec.
           mpi: "on"
 
@@ -79,7 +80,7 @@ jobs:
           mkdir -p benches/results
           # fd 3, because mpiexec forwards its own stdin to rank 0 and would eat the rung list.
           while IFS='|' read -r head args <&3; do
-            IFS=$' \t' read -r rung ranks partitions rounds <<<"$head"
+            IFS=$' \t' read -r rung ranks threads rounds <<<"$head"
             case "${rung:-}" in '' | '#'*) continue ;; esac
             # The name reaches a result filename, a Bencher testbed and the prefix split
             # below, so hold it to what all three accept. A leading `.` would split to an
@@ -94,23 +95,23 @@ jobs:
             # `0` divides by zero at per-rank and reaches `mpiexec -n 0` otherwise; and `08` is
             # an invalid octal literal there. Rejecting leading zeros keeps that arithmetic
             # base 10.
-            for field in ranks partitions rounds; do
+            for field in ranks threads rounds; do
               value="${!field:-}"
-              [[ "$field" == partitions && "$value" == per-rank ]] && continue
+              [[ "$field" == threads && "$value" == per-rank ]] && continue
               case "$value" in
                 '') echo "::error::rung $rung has no $field"; exit 1 ;;
                 *[!0-9]* | 0*)
                   echo "::error::rung $rung needs a positive decimal $field, not '$value'"
                   exit 1 ;;
               esac
             done
-            if [[ "$partitions" == per-rank ]]; then
-              partitions=$((BENCH_CORES / ranks))
+            if [[ "$threads" == per-rank ]]; then
+              threads=$((BENCH_CORES / ranks))
             fi
             # Oversubscription reports a plausible wall time and would silently corrupt the
             # testbed.
-            if ((partitions < 1 || ranks * partitions > BENCH_CORES)); then
-              echo "::error::rung $rung wants ${ranks}x${partitions} on $BENCH_CORES physical cores"
+            if ((threads < 1 || ranks * threads > BENCH_CORES)); then
+              echo "::error::rung $rung wants ${ranks}x${threads} on $BENCH_CORES physical cores"
               exit 1
             fi
             # xargs honours quotes in `-k "a and b"` without evaluating the input.
@@ -123,23 +124,25 @@ jobs:
               readarray -t argv <<< "$parsed"
             fi
             label="$BENCH_LABEL-$rung"
-            echo "::group::$rung: ${ranks}x${partitions}, $rounds rounds -> $label"
-            # `monoprop_PARTITIONS` also sizes the pinning below -- unpinned ranks vary by more
+            echo "::group::$rung: ${ranks}x${threads}, $rounds rounds -> $label"
+            # An exact team of T per rank, one thread per core of the rank's slot: placement is
+            # the launcher's and OpenMP's, never the library's. Unpinned threads vary by more
             # than the effects being tracked.
-            export monoprop_PARTITIONS="$partitions" monoprop_NUM_THREADS="$partitions"
+            export monoprop_NUM_THREADS="$threads" OMP_NUM_THREADS="$threads" OMP_DYNAMIC=FALSE
+            export OMP_PROC_BIND=close OMP_PLACES=cores
             export monoprop_BENCH_LABEL="$label" monoprop_BENCH_RESULTS=benches/results
             if ((ranks == 1)); then
               uv run --no-sync python -m pytest benches -o filterwarnings=default \
-                --benchmark-json="benches/results/time-$label.json" \
+                --runtime-shape=openmp --benchmark-json="benches/results/time-$label.json" \
                 -m "${monoprop_BENCH_MARKERS-not slow}" \
                 --bench-rounds "$rounds" "${argv[@]}"
             else
               uv run --no-sync mpiexec -n "$ranks" \
-                --map-by "slot:PE=$monoprop_PARTITIONS" --bind-to core \
+                --map-by "slot:PE=$threads" --bind-to core \
                 -x monoprop_BENCH_LABEL -x monoprop_BENCH_RESULTS \
-                -x monoprop_PARTITIONS -x monoprop_NUM_THREADS \
+                -x monoprop_NUM_THREADS -x OMP_NUM_THREADS -x OMP_DYNAMIC -x OMP_PROC_BIND -x OMP_PLACES \
                 python -m pytest benches -o filterwarnings=default \
-                --benchmark-json="benches/results/time-$label.json" \
+                --runtime-shape=openmp --benchmark-json="benches/results/time-$label.json" \
                 -m "${monoprop_BENCH_MARKERS-not slow}" \
                 --bench-rounds "$rounds" "${argv[@]}"
             fi
@@ -148,7 +151,7 @@ jobs:
             # To the log too: a rung that OOMs the instance takes the artifact with it.
             cat "bmf-$rung.json"
             uv run --no-sync python .github/workflows/scripts/check_shape.py \
-              "benches/results/$label.json" "$ranks" "$partitions"
+              "benches/results/$label.json" "$ranks" "$threads"
             echo "::endgroup::"
           done 3<<< "$RUNGS"
 

.github/workflows/nix.yml

@@ -16,6 +16,10 @@ on:
       - VERSION
       - pyproject.toml
       - CMakeLists.txt
+      - cmake/**
+      - cpp/**/CMakeLists.txt
+      - cpp/tests/find_package_smoke/**
+      - cpp/tests/link_export_probe/**
       - src/monoprop/bindings/CMakeLists.txt
 
 concurrency:
@@ -67,10 +71,18 @@ jobs:
             ninja --version
             uv --version
             just --version
-            pkg-config --modversion hwloc
             mpicc --version
           '
 
+      # Configures, links and runs the installed-package consumer, which instantiates the
+      # OpenMP worksharing template, with the shell's compiler and OpenMP runtime.
+      - name: Check the OpenMP consumer from the dev shell
+        run: |
+          nix develop --command bash -euo pipefail -c '
+            monoprop_ENABLE_MPI=OFF just build --group workspace-test
+            just test-find-package
+          '
+
   flake-result:
     name: All flake checks
     if: always()

.github/workflows/qa-analysis.yml

@@ -57,7 +57,7 @@ jobs:
       - name: Set up the build environment
         uses: ./.github/actions/setup
         with:
-          cache-suffix: coverage-mpi-${{ matrix.mpi }}
+          cache-suffix: coverage-mpi-${{ matrix.mpi }}-sharded
           mpi: ${{ matrix.mpi }}
 
       - name: Collect coverage
@@ -142,7 +142,7 @@ jobs:
       - name: Set up the build environment
         uses: ./.github/actions/setup
         with:
-          cache-suffix: gcc-asan-ubsan
+          cache-suffix: gcc-asan-ubsan-sharded
 
       - name: Install package
         run: just build --group workspace-test
@@ -157,16 +157,23 @@ jobs:
         if: failure()
         run: just sanitizer-reports
 
-  gcc-tsan:
+  clang-tsan:
     # TSan cannot load instrumented _core into stock CPython; Python coverage needs an
-    # instrumented interpreter. C++ tests cover the relevant partition and ShmComm paths.
-    name: GCC ThreadSanitizer (C++)
+    # instrumented interpreter. The C++ tests cover the sharded runtime's concurrency surface,
+    # whose OpenMP teams need LLVM's libomp with its Archer tool: GCC's libgomp is not
+    # TSan-aware, so its reports are not evidence either way (docs/content/docs/building.mdx).
+    name: Clang ThreadSanitizer with Archer (C++)
     runs-on: ubuntu-26.04
     permissions:
       contents: read
     env:
+      CXX: clang++-18
+      CC: clang-18
       SKBUILD_CMAKE_BUILD_TYPE: "Tsan"
       SKBUILD_CMAKE_DEFINE: "monoprop_SANITIZER=tsan"
+      OMP_TOOL_LIBRARIES: /usr/lib/llvm-18/lib/libarcher.so
+      # libomp's own internal locking is not instrumented.
+      TSAN_OPTIONS: "suppressions=${{ github.workspace }}/.github/tsan-libomp.supp"
 
     steps:
       - uses: actions/checkout@v7.0.1
@@ -176,12 +183,12 @@ jobs:
       - name: Set up the build environment
         uses: ./.github/actions/setup
         with:
-          cache-suffix: gcc-tsan
+          cache-suffix: clang-tsan-sharded
 
       - name: Install package
         run: just build --group workspace-test
 
-      - name: Run C++ partition and ShmComm tests
+      - name: Run the sharded runtime's concurrency tests
         run: just test-cpp-tsan
 
   sonarqube-analysis:
@@ -197,7 +204,7 @@ jobs:
       - name: Set up the build environment
         uses: ./.github/actions/setup
         with:
-          cache-suffix: sonarqube-mpi
+          cache-suffix: sonarqube-mpi-sharded
           mpi: "on"
 
       - name: Install package
@@ -239,8 +246,11 @@ jobs:
 
       - name: Set up the build environment
         uses: ./.github/actions/setup
+        # The build below uses clang++, so the setup installs its matching libomp.
+        env:
+          CXX: clang++
         with:
-          cache-suffix: clang-tidy-mpi
+          cache-suffix: clang-tidy-mpi-sharded
           mpi: "on"
 
       - name: Build (generates compile_commands.json)

.github/workflows/scripts/check_shape.py

@@ -14,12 +14,12 @@
 
 """Fail a rung that did not run at the shape it was asked for.
 
-A knob that fails to reach the ranks does not fail the run: it measures one partition per
-rank at a plausible wall time. Neither does `partitions` above a rank's visible cores --
-that disables placement entirely, at 13.8x to 24.6x, warning only on C++ stderr, which
-pytest's capture eats.
+A knob that fails to reach the ranks does not fail the run: it measures a different team at a
+plausible wall time. So the recorded rank count and per-rank thread count must be the rung's,
+and the removed partition runtime's variable must not be set at all. Placement is the launcher's
+and OpenMP's (`--bind-to core`, `OMP_PROC_BIND`/`OMP_PLACES`); its summary is printed for the log.
 
-Usage: check_shape.py <results/<label>.json> <ranks> <partitions>
+Usage: check_shape.py <results/<label>.json> <ranks> <threads>
 """
 
 from __future__ import annotations
@@ -30,28 +30,26 @@
 
 
 def main(argv: list[str]) -> str | None:
-    path, ranks, partitions = Path(argv[1]), int(argv[2]), argv[3]
+    path, ranks, threads = Path(argv[1]), int(argv[2]), argv[3]
     meta = json.loads(path.read_text())["meta"]
     pin = meta.get("pinning", {})
-    threads = pin.get("threads", 0)
-    placed = pin.get("single_cpu_threads_min", 0)
 
     print(
-        f"  ranks={meta['ranks']} partitions_env={meta['partitions_env']} "
-        f"threads={meta['monoprop_threads']} pinned>={placed} of {threads} "
+        f"  ranks={meta['ranks']} threads={meta['monoprop_threads']} "
+        f"partitions_env={meta['partitions_env']} "
+        f"single-cpu threads>={pin.get('single_cpu_threads_min', 0)} of {pin.get('threads', 0)} "
         f"mask={pin.get('affinity_cpus_min')}..{pin.get('affinity_cpus_max')}"
     )
 
-    if meta["ranks"] != ranks or meta["partitions_env"] != partitions:
+    if meta["ranks"] != ranks or meta["monoprop_threads"] != threads:
         return (
             f"::error::{path.stem} ran at ranks={meta['ranks']} "
-            f"partitions_env={meta['partitions_env']}, asked for {ranks}x{partitions}"
+            f"threads={meta['monoprop_threads']}, asked for {ranks}x{threads}"
         )
-    # An all-zero summary means /proc was unreadable, not that nothing was pinned.
-    if int(partitions) > 1 and threads and not placed:
+    if meta["partitions_env"] != "unset":
         return (
-            f"::error::{path.stem} placed no thread on a CPU of its own. "
-            "partitions above the rank's visible cores return an empty placement order."
+            f"::error::{path.stem} ran with monoprop_PARTITIONS={meta['partitions_env']}; "
+            "the sharded runtime ignores it, so a rung must not set it"
         )
     return None
 

.github/workflows/scripts/resolve_cores.py

@@ -48,9 +48,9 @@ def main() -> str | None:
     if not monoprop.has_mpi:
         return "monoprop was built without MPI; every rung shares this binary"
 
-    # PHYSICAL cores, and only the ones this process may run on. Physical, because that is what
-    # the engine enumerates and the logical count would cross the `partitions > visible cores`
-    # threshold on any SMT machine. Visible, because psutil counts the whole machine: under a
+    # PHYSICAL cores, and only the ones this process may run on. Physical, because the rungs size
+    # their thread counts in cores and an SMT sibling is not a second core; monoprop itself takes
+    # whatever OpenMP reports. Visible, because psutil counts the whole machine: under a
     # mask -- a cpuset, taskset, or a shared runner -- that number oversubscribes every rung and
     # names the testbed after cores the run never had.
     visible = os.sched_getaffinity(0)

.github/workflows/test.yml

@@ -74,7 +74,9 @@ jobs:
         uses: ./.github/actions/setup
         with:
           python-version: ${{ matrix.python-version }}
-          cache-suffix: ${{ matrix.compiler }}-mpi-${{ matrix.mpi }}
+          # The MPI-off and MPI builds are ABI-incompatible, and so is every build from before the partition runtime was
+          # removed: the `sharded` part retires the caches of the dual-runtime matrix.
+          cache-suffix: ${{ matrix.compiler }}-mpi-${{ matrix.mpi }}-sharded
           mpi: ${{ matrix.mpi }}
 
       - name: Install package
@@ -87,6 +89,9 @@ jobs:
       - name: Get monoprop information
         run: just info
 
+      - name: Verify the runtime and MPI identity of the build
+        run: just check-runtime
+
       - name: Verify that find_package(monoprop) works
         run: just test-find-package
 

AGENTS.md

@@ -56,8 +56,38 @@ just build-docs
 - Python reference data lives in `tests/reference_data.py` (`load_problem()` reads `tests/data/*.msgpack`); C++ uses
   `test_utils::load_case()` from `cpp/tests/TestData.h`.
 - Pytest's fd capture hides C++ stderr such as `COMMPROF`; rerun with `-s`.
+- Benchmark evidence: `pytest benches --runtime-shape=... --build-mode=...` refuses contradictory
+  runs. `tools/benchmark-rank-local-openmp.py` has exactly three modes, `observe`, `validate` and
+  `compare` (see `docs/content/docs/benchmarks.mdx`). Launch MPI-off runs directly: `mpi4py` is
+  never imported when `monoprop.has_mpi` is false.
 - `uv sync` does not relink `bin/monoprop_unit_tests.x` -- compare mtimes and use the standalone
   recipe in `docs/content/docs/building.mdx`.
+- OpenMP is a required build dependency in every configuration (`OpenMP::OpenMP_CXX`, linked PUBLIC on
+  both `monoprop-objs` and `monoprop`, `find_dependency` in the package config). The worksharing
+  primitive is `detail/parallel/Workshare.h::for_blocks`. Never call `omp_set_*` from the library.
+  The library calls the runtime (`ThreadBudget.cpp`), so `import monoprop` loads it: with `OMP_PLACES`
+  set and binding on, the importing thread is bound to the first place.
+- One runtime: each rank's `MonomialPropagator` owns T shards (`detail/sharded/`), T captured once at
+  construction from `monoprop_NUM_THREADS` (strict parser; unset falls back to `omp_get_max_threads()`).
+  There is no partition runtime, selector or `monoprop_PARTITIONS` reader. Every MPI-using operation
+  enforces MPI's initializing thread; only that thread (the team's primary) calls MPI, so FUNNELED is
+  required. Every state operation separates validation from mutation (`run_operation_`): a failure after
+  mutation starts invalidates the object and aborts a multi-rank communicator (`mpi::operation_failed`).
+  Catch failures inside posted `Ticket`/`PendingAlltoallv`/physical-round lifetimes, never only at the
+  outermost level. `detail::build_layer` (with `run_exchange` and `mpi::begin_alltoallv`) is the low-level
+  one-owner-per-rank engine kept only as the tests' reference; production builds layers through
+  `detail/sharded/Construction.h`.
+- Threaded kernels (`scale_cos_*`, `apply_fused_contract`, the `fused_find_and_collect` scan, the resolve
+  phases: incoming decode, `probe_frozen_positions`, certified-sink scatter) take a defaulted test-only
+  range observer; participation tests read it (`cpp/tests/KernelTestSupport.h`, `ScanTestSupport.h`).
+  Serial and threaded runs must agree bitwise. Scan workers only traverse frozen storage and merge in range
+  order; only typed cutoffs (`CutoffEvaluator::parallel_safe`) run on them. Probes read a frozen store;
+  received query streams are validated on the caller (`QueryWire::checked_extent`) before any decode;
+  miss IDs, insertion (`bulk_insert_hashed`) and inverted-index maintenance stay single-writer. A sink's
+  `on_resolved` runs on workers only with `static constexpr bool parallel_resolve = true`. TSan evidence
+  needs Clang + libomp + Archer; GCC's libgomp gives false reports (`building.mdx`).
+- `cpp/tests/mpi_failure_driver.cpp` has its own `main()`, excluded from the unit-runner glob;
+  `ctest -L mpi_failure` runs its two-rank abort scenarios (30 s timeout; a timeout is a hang).
 - Slow CTest startup in MPI builds is `MPI_Init` fabric probing; see
   `monoprop_TEST_EXCLUDE_MPI_FABRIC` in `cpp/tests/CMakeLists.txt`.
 - Sanitizer rebuild and test:

CMakeLists.txt

@@ -65,6 +65,10 @@ find_package(
 
 find_package(Threads REQUIRED)
 
+# Required in every configuration, including MPI-off and single-thread builds: there is no
+# OpenMP-disabled variant of the library.
+find_package(OpenMP REQUIRED COMPONENTS CXX)
+
 if(monoprop_ENABLE_MPI)
   find_package(MPI REQUIRED COMPONENTS CXX)
 endif()