perf(mpi): 🧭 GF(2)-linear rank routing — messages per rank flat in R

cpp/include/monoprop/MonomialPropagator.h

@@ -365,6 +365,8 @@ class MonomialPropagator {
     // it captures this and rejects a later call once it moves, as it does for a rebuilt graph.
     size_t initial_operator_epoch_{0};
 
+    bool routing_coverage_reported_{false}; // report_routing_coverage_ speaks once per propagator
+
     size_t logical_num_modes_{NumModes};
 
     CutoffType cutoff_type_;
@@ -449,6 +451,10 @@ class MonomialPropagator {
                                            const VecD &parameters,
                                            std::optional<size_t> only_rotate_len_k) -> void;
 
+    // Do this call's generator shifts span log2(R)? If not, ranks receive nothing (routing::gf2_rank).
+    // Not beside check_routing_agreement: at construction the gate list does not exist yet.
+    auto report_routing_coverage_(const std::vector<VecZ> &majoranas) -> void;
+
     template <typename EvolutionFunc>
     auto run_gate_loop_(const std::vector<VecZ> &majoranas,
                         std::optional<size_t> only_rotate_len_k,

cpp/monoprop/Evolution.cpp

@@ -26,6 +26,7 @@
 #include "monoprop/detail/evolution/CosineRecomputeCallbacks.h"
 #include "monoprop/detail/mpi/Exchange.h"
 #include "monoprop/detail/mpi/MPICompat.h"
+#include "monoprop/detail/mpi/Routing.h"
 
 namespace monoprop {
 namespace {
@@ -73,10 +74,23 @@ auto &acquire_flat_exchange_buffers() {
 }
 
 // A property of the communicator, not the layer: all ranks participate even at local total_count 0.
+// Still true with the pairwise arm: `wire_bits` decides the transport for the whole communicator, so a
+// rank that skipped the round strands the others whichever transport they are on.
 auto layer_exchange_participates(const mpi::Comm &comm) -> bool {
     return mpi::size(comm) != 1;
 }
 
+// The transport gate for post_flat_alltoallv, and the ONLY thing allowed to choose it: rank-uniform by
+// construction, because linear_bits_for reads the environment alone and check_routing_agreement
+// allreduces exactly this number at construction and throws rather than proceed on a mismatch. Fanout 1
+// -- every generator's queries land on one destination rank -- is both why a layer's other legs are
+// empty and why no rank can be on the other side of the branch. Any other geometry keeps the collective.
+auto layer_exchange_wire_bits(const mpi::Comm &comm) -> int {
+    const auto ranks = static_cast<size_t>(mpi::geometry(comm).ranks);
+    const size_t bits = routing::linear_bits_for(ranks);
+    return (ranks >> bits) == 1 ? static_cast<int>(bits) : 0;
+}
+
 // Derives both sides at once: the count matrix is symmetric, so the recv layout is the send layout.
 auto derive_layer_exchange(const LayerTraversal &layer, const mpi::Comm &comm, int scale, LayerExchangeLayout &layout)
     -> void {
@@ -115,7 +129,8 @@ inline auto begin_flat_exchange(FlatExchangeBuffers &buffers, const mpi::Comm &c
                                                       .recv_counts = layout.counts.data(),
                                                       .recv_displs = layout.displs.data()},
                                                      mpi::size(comm),
-                                                     comm);
+                                                     comm,
+                                                     layer_exchange_wire_bits(comm));
     return handle;
 }
 

cpp/monoprop/detail/EnvConfig.h

@@ -14,18 +14,35 @@
 
 #pragma once
 
+#include <cerrno>
 #include <cstddef>
+#include <cstdint>
 #include <cstdlib>
 #include <optional>
+#include <stdexcept>
+#include <string>
+#include <string_view>
 
 // Single home for runtime environment configuration. Kept dependency-free by design, because it is
 // pulled into hot-path headers.
 //
 //   monoprop_NUM_THREADS        positive int (1..1e6), else ignored → num_threads
 //   monoprop_PARTITIONS         int N | "auto" | "off"; parsed where it is used (resolve_partition_count_)
+//   monoprop_ROUTING            "splitmix" | "linear" → routing_mode
+//   monoprop_ROUTE_SEED         decimal uint64 basis seed → route_seed
+//
+// Both routing knobs THROW on a malformed value instead of falling back: each silently changes the
+// transport, so a typo that defaulted would stay invisible until a performance postmortem.
 
 namespace monoprop::config {
 
+class EnvConfigError : public std::runtime_error {
+public:
+    using std::runtime_error::runtime_error;
+};
+
+enum class RoutingMode : std::uint8_t { Splitmix, Linear };
+
 namespace detail {
 
 inline auto parse_positive_int(const char *text) -> std::optional<int> {
@@ -43,17 +60,58 @@ inline auto parse_positive_int(const char *text) -> std::optional<int> {
     return static_cast<int>(value);
 }
 
+[[noreturn]] inline auto reject_env(std::string_view name, const char *text, std::string_view expected) -> void {
+    throw EnvConfigError(std::string{name} + "=\"" + text + "\" is not " + std::string{expected}
+                         + "; correct it or leave the variable unset.");
+}
+
+// Unset and empty are both nullopt; a value that is present but unparseable throws.
+inline auto parse_uint64(std::string_view name, const char *text) -> std::optional<std::uint64_t> {
+    if (text == nullptr || *text == '\0') {
+        return std::nullopt;
+    }
+    // strtoull WRAPS a negative literal to a huge unsigned rather than failing, so '-' is rejected here.
+    if (std::string_view{text}.find('-') != std::string_view::npos) {
+        reject_env(name, text, "a decimal uint64");
+    }
+    errno = 0;
+    char *end = nullptr;
+    const unsigned long long value = std::strtoull(text, &end, 10);
+    if (end == text || *end != '\0' || errno == ERANGE) {
+        reject_env(name, text, "a decimal uint64");
+    }
+    return static_cast<std::uint64_t>(value);
+}
+
+inline auto parse_routing_mode(std::string_view name, const char *text) -> std::optional<RoutingMode> {
+    if (text == nullptr || *text == '\0') {
+        return std::nullopt;
+    }
+    const std::string_view value{text};
+    if (value == "splitmix") {
+        return RoutingMode::Splitmix;
+    }
+    if (value == "linear") {
+        return RoutingMode::Linear;
+    }
+    reject_env(name, text, "one of \"splitmix\" or \"linear\"");
+}
+
 } // namespace detail
 
 struct Settings {
     std::optional<int> num_threads;
+    std::optional<RoutingMode> routing_mode;
+    std::optional<std::uint64_t> route_seed;
 };
 
 // Parse the environment once; the Settings are cached and shared across TUs.
 inline auto get() -> const Settings & {
     static const Settings settings = [] {
         Settings s;
         s.num_threads = detail::parse_positive_int(std::getenv("monoprop_NUM_THREADS"));
+        s.routing_mode = detail::parse_routing_mode("monoprop_ROUTING", std::getenv("monoprop_ROUTING"));
+        s.route_seed = detail::parse_uint64("monoprop_ROUTE_SEED", std::getenv("monoprop_ROUTE_SEED"));
         return s;
     }();
     return settings;