Make Delphy runs deterministic given same seed and thread count

Patch vendored Abseil at CMake configure time to neutralize three sources of
hash container iteration nondeterminism (Hash::Seed, PerTableSalt, RandomSeed).
Remove the sort-before-RNG workaround in build_usher_like_tree that was a
partial fix for the same issue.

Store the PRNG seed in Run and output both seed and thread count in BEAST log
file headers via stamp_version_into_log_file.  Route through Run rather than
globals so multiple WASM Delphy_context instances can coexist.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: patvarilly

.gitmodules

@@ -5,6 +5,7 @@
 [submodule "third-party/abseil-cpp"]
 	path = third-party/abseil-cpp
 	url = https://github.com/abseil/abseil-cpp.git
+	ignore = dirty
 [submodule "third-party/ctpl"]
 	path = third-party/ctpl
 	url = https://github.com/vit-vit/ctpl.git

CMakeLists.txt

@@ -76,6 +76,32 @@ find_package(Threads REQUIRED)
 find_package(Eigen3 REQUIRED)
 find_package(Boost REQUIRED)
 set(ABSL_PROPAGATE_CXX_STD ON)
+
+# Apply Delphy patches to vendored Abseil (deterministic hash iteration).
+# The patch neutralizes PerTableSalt, RandomSeed, and absl::Hash::Seed so that
+# flat_hash_map/set iteration order depends only on hash values, not on table
+# memory addresses or ASLR.  This is required for reproducible MCMC runs.
+# If the patch has already been applied (e.g., on a reconfigure), git apply
+# --check --reverse will detect that and we skip it.  If the patch fails for
+# any other reason (e.g., Abseil was upgraded), the build fails loudly.
+set(_abseil_patch "${CMAKE_SOURCE_DIR}/patches/abseil-deterministic-hash-iteration.patch")
+execute_process(
+  COMMAND git apply --check --reverse ${_abseil_patch}
+  WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/third-party/abseil-cpp
+  RESULT_VARIABLE _patch_already_applied
+  OUTPUT_QUIET ERROR_QUIET)
+if(_patch_already_applied)
+  execute_process(
+    COMMAND git apply ${_abseil_patch}
+    WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/third-party/abseil-cpp
+    RESULT_VARIABLE _patch_result)
+  if(_patch_result)
+    message(FATAL_ERROR
+      "Failed to apply Abseil patch ${_abseil_patch}. "
+      "If Abseil was upgraded, the patch may need updating.")
+  endif()
+endif()
+
 add_subdirectory(third-party/abseil-cpp EXCLUDE_FROM_ALL)
 
 # Optional UI libraries

core/beasty_input.cpp

@@ -191,7 +191,7 @@ static auto export_beast_2_6_2_input(
   os << absl::StreamFormat("<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?>\n")
      << absl::StreamFormat("\n")
      << absl::StreamFormat("<!-- \n")
-     << stamp_version_into_log_file{}
+     << stamp_version_into_log_file{run}
      << absl::StreamFormat("-->\n")
      << absl::StreamFormat("\n")
      << absl::StreamFormat("<!-- BEAST2 v2.6.2 input file, modelled on run analyzed in \n")
@@ -579,7 +579,7 @@ static auto export_beast_2_7_7_input(
   os << absl::StreamFormat("<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?>\n")
      << absl::StreamFormat("\n")
      << absl::StreamFormat("<!-- \n")
-     << stamp_version_into_log_file{}
+     << stamp_version_into_log_file{run}
      << absl::StreamFormat("-->\n")
      << absl::StreamFormat("\n")
      << absl::StreamFormat("<!-- BEAST2 v2.7.7 input file, modelled on run analyzed in \n")
@@ -1111,7 +1111,7 @@ static auto export_beast_X_10_5_0_input(
   os << absl::StreamFormat("<?xml version=\"1.0\" standalone=\"yes\"?>\n")
      << absl::StreamFormat("\n")
      << absl::StreamFormat("<!-- \n")
-     << stamp_version_into_log_file{}
+     << stamp_version_into_log_file{run}
      << absl::StreamFormat("-->\n")
      << absl::StreamFormat("\n")
      << absl::StreamFormat("<!-- BEAST X 10.5.0 input file, modelled on run analyzed in \n")

core/beasty_output.cpp

@@ -66,7 +66,7 @@ class Beasty_log_output_2_x_x : public Beasty_log_output_version_impl {
 
     if (not run.mpox_hack_enabled()) {
       // WARNING: Ensure this matches the logger output from export_beast_2_x_x_input (beasty_input.cpp)
-      os << stamp_version_into_log_file{};
+      os << stamp_version_into_log_file{run};
       os << "Sample\t"
          << "numMuts\t"    // Not output by BEAST, but useful for downstream analysis of Delphy results
          << "posterior_for_Delphy\t"        // Not really BEAST's posterior
@@ -275,7 +275,7 @@ class Beasty_log_output_X_10_5_0 : public Beasty_log_output_version_impl {
     const auto& pop_model = run.pop_model();
 
     // WARNING: Ensure this matches the logger output from export_beast_X_10_5_0_input (beasty_input.cpp)
-    os << stamp_version_into_log_file{};
+    os << stamp_version_into_log_file{run};
     os << "state\t"
        << "numMuts\t"    // Not output by BEAST, but useful for downstream analysis of Delphy results
        << "posterior_for_Delphy\t"        // Not really BEAST's "joint"
@@ -513,7 +513,7 @@ auto Beasty_trees_output::output_headers(const Run& run) -> void {
   }
 
   *os_ << "#NEXUS\n"
-       << stamp_version_into_log_file{}
+       << stamp_version_into_log_file{run}
        << "\n"
        << "Begin taxa;\n"
        << "    Dimensions ntax=" << num_tips << ";\n"

core/cmdline.cpp

@@ -625,7 +625,7 @@ auto process_args(int argc, char** argv) -> Processed_cmd_line {
 
     // Create and configure initial run
     auto t0 = calc_max_tip_time(tree);
-    auto run = std::make_shared<Run>(*thread_pool, prng, std::move(tree));
+    auto run = std::make_shared<Run>(*thread_pool, prng, seed, std::move(tree));
     run->set_paranoid(opts["v0-paranoid"].as<bool>());
     run->set_mpox_hack_enabled(mpox_hack_enabled);
     run->set_alpha_move_enabled(alpha_move_enabled);

core/io.cpp

@@ -255,7 +255,7 @@ auto read_maple(
   return result;
 }
 
-auto operator<<(std::ostream& os, stamp_version_into_log_file) -> std::ostream& {
+auto operator<<(std::ostream& os, stamp_version_into_log_file s) -> std::ostream& {
   os << absl::StreamFormat("# Produced by delphy version %s (build %d, commit %s)\n",
                            k_delphy_version_string, k_delphy_build_number, k_delphy_commit_string);
   if (delphy_invoked_via_cli) {
@@ -266,6 +266,8 @@ auto operator<<(std::ostream& os, stamp_version_into_log_file) -> std::ostream&
     }
     os << "\n";
   }
+  os << "# Seed: " << s.run.prng_seed() << "\n";
+  os << "# Parallelism: " << s.run.num_parts() << "\n";
   return os;
 }
 

core/io.h

@@ -33,8 +33,11 @@ auto read_maple(
     = default_sequence_warning_hook)
     -> Maple_file;
 
-struct stamp_version_into_log_file{};  // dummy type for stream command
-auto operator<<(std::ostream& os, stamp_version_into_log_file) -> std::ostream&;
+class Run;  // forward declaration
+struct stamp_version_into_log_file {
+  const Run& run;
+};
+auto operator<<(std::ostream& os, stamp_version_into_log_file s) -> std::ostream&;
 
 auto output_resolved_fasta(const Phylo_tree& tree, std::ostream& os) -> void;
 

core/phylo_tree.cpp

@@ -955,18 +955,7 @@ auto build_usher_like_tree(
     tree.at(S).parent = P;
 
     // Distribute needed mutations randomly
-    //  - ordered_mutations is here to avoid the non-determinism introduced by abseil's flat_hash_map
-    //    (so delphy invocations with the same seed produce identical starting trees)
-    auto ordered_mutations = Scratch_vector<std::pair<Site_index, Site_delta>>{};
     for (const auto& [l, delta] : deltas_P_to_X) {
-      ordered_mutations.push_back({l, delta});
-    }
-    std::ranges::sort(ordered_mutations, [](const auto& pair_a, const auto& pair_b) {
-      const auto& [la, _1] = pair_a;
-      const auto& [lb, _2] = pair_b;
-      return la < lb;
-    });
-    for (const auto& [l, delta] : ordered_mutations) {
       tree.at(X).mutations.push_back(Mutation{
           delta.from, l, delta.to,
           absl::Uniform(absl::IntervalOpenClosed, bitgen, t_P, t_X)});

core/run.cpp

@@ -11,9 +11,10 @@
 
 namespace delphy {
 
-Run::Run(ctpl::thread_pool& thread_pool, std::mt19937 bitgen, Phylo_tree tree)
+Run::Run(ctpl::thread_pool& thread_pool, std::mt19937 bitgen, uint32_t prng_seed, Phylo_tree tree)
     : thread_pool_{&thread_pool},
       bitgen_{bitgen},
+      prng_seed_{prng_seed},
       tree_{std::move(tree)},
       num_parts_{1},
       target_coal_prior_cells_{400},

core/run.h

@@ -17,7 +17,7 @@ namespace delphy {
 
 class Run {
  public:
-  Run(ctpl::thread_pool& thread_pool, std::mt19937 bitgen, Phylo_tree tree);
+  Run(ctpl::thread_pool& thread_pool, std::mt19937 bitgen, uint32_t prng_seed, Phylo_tree tree);
 
   auto bitgen() -> absl::BitGenRef { return bitgen_; }
   auto tree() -> Phylo_tree& { return tree_; }
@@ -28,6 +28,7 @@ class Run {
   auto set_step(int64_t num_steps) -> void;
   auto local_moves_per_global_move() const -> int { return local_moves_per_global_move_; }
   auto set_local_moves_per_global_move(int local_moves_per_global_move) -> void;
+  auto prng_seed() const -> uint32_t { return prng_seed_; }
   auto num_parts() const -> int { return num_parts_; }
   auto set_num_parts(int num_parts) -> void { num_parts_ = num_parts; partition_stencils_valid_ = false; }
   auto target_coal_prior_cells() const -> int { return target_coal_prior_cells_; }
@@ -225,6 +226,7 @@ class Run {
  private:
   ctpl::thread_pool* thread_pool_;
   std::mt19937 bitgen_;
+  uint32_t prng_seed_;
   Phylo_tree tree_;
 
   int64_t step_;