ci: add cross-platform determinism check (Part 1) (#1594)

AnshulPatil2005 · web-flow · commit 076c704c4f66 · 2026-04-19T09:14:47.000+12:00
* init determinism.yml file

* integrated with existing ci

* init determinism.yml file

* switched test filter to generate coplanar.obj +trimmed output + -euo pipefail

* minor fix

* replaced nasty gear

* small set of simple single-op determinism cases

* Normalize line endings

* hex-float OBJ dump mode

* intermediate dumps for Perturb3 / boolean_result

* format

* canonicalize hex-float text in determinism compare

* add Perturb3 decomposition lane + print stable hex from C++ dumps + dump full intermediate boolean_result array contents + keep simple-case chec

* clang-format

* boolean debug dump

* Perturb3 decomposition

* script to compare boolean dumps

* binary-tree decomposition probes

* minor fix

* 4-&gt;1

* boolean3_000004 fix

* clang format

* boolean3_000015_post_winding_add_inQ.obj

* trig canonicalization at 45 degree

* added multicoplanar in blocking ci

* added Boolean.NonIntersecting

* add Boolean.AlmostCoplanar

* reuse existing verbosity level and dedup dump helpers via boolean_dump.h

* format

* move determinism compare logic into scripts and keep dumps discovery-only

* remove discovery

* clean dead code

* clean
diff --git a/.github/workflows/manifold.yml b/.github/workflows/manifold.yml
@@ -83,7 +83,20 @@ jobs:
       run: |
         cp ./build/lib/Release/* ./build/bin/Release
         ./build/bin/Release/manifold_test.exe
-
+    - name: Export determinism meshes
+      if: matrix.parallelization == 'OFF' && matrix.shared == 'OFF'
+      shell: bash
+      env:
+        MANIFOLD_OBJ_HEX_FLOAT: 1
+      run: |
+        cp ./build/lib/Release/* ./build/bin/Release
+        bash ./scripts/export_determinism_meshes.sh build/bin/Release ./manifold_test.exe meshes-windows
+    - name: Upload determinism meshes (Windows)
+      if: matrix.parallelization == 'OFF' && matrix.shared == 'OFF'
+      uses: actions/upload-artifact@v4
+      with:
+        name: meshes-windows
+        path: meshes-windows/
   build:
     name: GCC ${{matrix.gcc}} (CrossSection:${{matrix.cross_section}}, TBB:${{matrix.parallelization}})
     timeout-minutes: 45
@@ -145,6 +158,18 @@ jobs:
         export PYTHONPATH=$PYTHONPATH:$(pwd)/build/bindings/python
         python3 bindings/python/examples/run_all.py -e
         python3 -m pytest
+    - name: Export determinism meshes
+      if: matrix.parallelization == 'OFF' && matrix.gcc == 14 && matrix.os == 'ubuntu-24.04'
+      env:
+        MANIFOLD_OBJ_HEX_FLOAT: 1
+      run: |
+        bash ./scripts/export_determinism_meshes.sh build/test ./manifold_test meshes-linux
+    - name: Upload determinism meshes (Linux)
+      if: matrix.parallelization == 'OFF' && matrix.gcc == 14 && matrix.os == 'ubuntu-24.04'
+      uses: actions/upload-artifact@v4
+      with:
+        name: meshes-linux
+        path: meshes-linux/
     - name: test cmake consumer
       run: |
         sudo cmake --install build
@@ -425,6 +450,18 @@ jobs:
     - name: Test
       run: |
         build/test/manifold_test
+    - name: Export determinism meshes
+      if: matrix.parallelization == 'OFF' && matrix.shared == 'OFF' && matrix.os == 'macos-latest'
+      env:
+        MANIFOLD_OBJ_HEX_FLOAT: 1
+      run: |
+        bash ./scripts/export_determinism_meshes.sh build/test ./manifold_test meshes-mac
+    - name: Upload determinism meshes (macOS)
+      if: matrix.parallelization == 'OFF' && matrix.shared == 'OFF' && matrix.os == 'macos-latest'
+      uses: actions/upload-artifact@v4
+      with:
+        name: meshes-mac
+        path: meshes-mac/
     - name: test cmake consumer
       run: |
         sudo cmake --install build
@@ -491,3 +528,27 @@ jobs:
     - uses: DeterminateSystems/magic-nix-cache-action@main
     - run: nix build -L '.?submodules=1#${{matrix.variant}}'
 
+  determinism_check:
+    name: Cross-platform determinism check
+    needs: [build, build_windows, build_mac]
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v6
+    - name: Download Linux meshes
+      uses: actions/download-artifact@v4
+      with:
+        name: meshes-linux
+        path: meshes/linux
+    - name: Download macOS meshes
+      uses: actions/download-artifact@v4
+      with:
+        name: meshes-mac
+        path: meshes/mac
+    - name: Download Windows meshes
+      uses: actions/download-artifact@v4
+      with:
+        name: meshes-windows
+        path: meshes/windows
+    - name: Compare meshes across platforms
+      run: |
+        bash ./scripts/compare_artifact.sh meshes
diff --git a/scripts/compare_artifact.sh b/scripts/compare_artifact.sh
@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="${1:-meshes}"
+FILES="${DETERMINISM_COMPARE_FILES:-}"
+DIFF_LINES="${DETERMINISM_COMPARE_DIFF_LINES:-200}"
+NORMALIZE_SCRIPT="${DETERMINISM_NORMALIZE_SCRIPT:-./scripts/normalize_objs.sh}"
+
+source "$(dirname "$0")/determinism_cases.sh"
+
+if [ -z "$FILES" ]; then
+  FILES="${DETERMINISM_OBJ_FILES[*]}"
+fi
+
+for os in linux mac windows; do
+  if [ ! -d "$ROOT_DIR/$os" ]; then
+    echo "Missing directory: $ROOT_DIR/$os"
+    exit 1
+  fi
+done
+
+tmpdir="$(mktemp -d)"
+trap 'rm -rf "$tmpdir"' EXIT
+
+failed=0
+
+for f in $FILES; do
+  echo "--- $f ---"
+  file_missing=0
+  for os in linux mac windows; do
+    if [ ! -f "$ROOT_DIR/$os/$f" ]; then
+      echo "Missing file: $ROOT_DIR/$os/$f"
+      failed=1
+      file_missing=1
+    fi
+  done
+  if [ "$file_missing" -ne 0 ]; then
+    continue
+  fi
+
+  for os in linux mac windows; do
+    bash "$NORMALIZE_SCRIPT" "$ROOT_DIR/$os/$f" "$tmpdir/$os-$f"
+  done
+
+  linux_hash="$(sha256sum "$tmpdir/linux-$f" | awk '{print $1}')"
+  mac_hash="$(sha256sum "$tmpdir/mac-$f" | awk '{print $1}')"
+  win_hash="$(sha256sum "$tmpdir/windows-$f" | awk '{print $1}')"
+  echo "linux:   $linux_hash"
+  echo "mac:     $mac_hash"
+  echo "windows: $win_hash"
+
+  if [ "$linux_hash" != "$mac_hash" ] || [ "$linux_hash" != "$win_hash" ]; then
+    echo "MISMATCH in $f"
+    echo "linux vs mac diff:"
+    diff "$tmpdir/linux-$f" "$tmpdir/mac-$f" | sed -n "1,${DIFF_LINES}p" || true
+    echo "linux vs windows diff:"
+    diff "$tmpdir/linux-$f" "$tmpdir/windows-$f" | sed -n "1,${DIFF_LINES}p" || true
+    failed=1
+  fi
+done
+
+if [ "$failed" -ne 0 ]; then
+  echo "::error::Cross-platform determinism check failed."
+  exit 1
+fi
+
+if [ -n "${GITHUB_STEP_SUMMARY:-}" ]; then
+  {
+    echo "### Cross-platform determinism check"
+    echo ""
+    echo "No cross-platform mismatches detected."
+  } >> "$GITHUB_STEP_SUMMARY"
+fi
diff --git a/scripts/determinism_cases.sh b/scripts/determinism_cases.sh
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+
+# Shared determinism test/filter definitions for CI export+compare.
+
+DETERMINISM_GTEST_FILTER="Boolean.DeterminismSimpleSubtract:Boolean.DeterminismSimpleUnion:Boolean.DeterminismSimpleIntersect:Boolean.MultiCoplanar:Boolean.NonIntersecting:Boolean.AlmostCoplanar"
+
+DETERMINISM_OBJ_FILES=(
+  det_simple_subtract.obj
+  det_simple_union.obj
+  det_simple_intersect.obj
+  det_multi_coplanar.obj
+  det_non_overlap.obj
+  det_nearly_coplanar.obj
+)
+
diff --git a/scripts/export_determinism_meshes.sh b/scripts/export_determinism_meshes.sh
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ "$#" -ne 3 ]; then
+  echo "Usage: $0 <run-dir> <test-binary> <output-dir>"
+  exit 2
+fi
+
+RUN_DIR="$1"
+TEST_BIN="$2"
+OUT_DIR="$3"
+
+source "$(dirname "$0")/determinism_cases.sh"
+
+repo_root="$(pwd)"
+if [[ "$OUT_DIR" = /* ]]; then
+  out_abs="$OUT_DIR"
+else
+  out_abs="$repo_root/$OUT_DIR"
+fi
+
+cd "$RUN_DIR"
+"$TEST_BIN" -e --gtest_filter="$DETERMINISM_GTEST_FILTER"
+
+mkdir -p "$out_abs"
+cp "${DETERMINISM_OBJ_FILES[@]}" "$out_abs/"
diff --git a/scripts/normalize_objs.sh b/scripts/normalize_objs.sh
@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ "$#" -ne 2 ]; then
+  echo "Usage: $0 <input-obj> <output-obj>"
+  exit 2
+fi
+
+input="$1"
+output="$2"
+
+tr -d '\r' < "$input" > "$output"
diff --git a/src/boolean_result.cpp b/src/boolean_result.cpp
@@ -739,7 +739,9 @@ Manifold::Impl Boolean3::Result(OpType op) const {
   // Create the output Manifold
   Manifold::Impl outR;
 
-  if (numVertR == 0) return outR;
+  if (numVertR == 0) {
+    return outR;
+  }
 
   outR.epsilon_ = std::max(inP_.epsilon_, inQ_.epsilon_);
   outR.tolerance_ = std::max(inP_.tolerance_, inQ_.tolerance_);
diff --git a/src/csg_tree.cpp b/src/csg_tree.cpp
@@ -17,6 +17,7 @@
 #endif
 
 #include <algorithm>
+#include <cstdint>
 
 #include "boolean3.h"
 #include "csg_tree.h"
@@ -28,10 +29,14 @@ namespace {
 using namespace manifold;
 
 struct MeshCompare {
-  bool operator()(const std::shared_ptr<CsgLeafNode>& a,
-                  const std::shared_ptr<CsgLeafNode>& b) {
+  bool operator()(const std::pair<std::shared_ptr<CsgLeafNode>, uint64_t>& a,
+                  const std::pair<std::shared_ptr<CsgLeafNode>, uint64_t>& b) {
     // Use NumVert() which doesn't trigger transform application.
-    return a->NumVert() < b->NumVert();
+    const size_t aVert = a.first->NumVert();
+    const size_t bVert = b.first->NumVert();
+    if (aVert != bVert) return aVert < bVert;
+    // Tie-break by insertion order so heap behavior is deterministic across
+    return a.second < b.second;
   }
 };
 
@@ -384,47 +389,59 @@ std::shared_ptr<CsgLeafNode> BatchBoolean(
   if (results.size() == 2)
     return SimpleBoolean(*results[0]->GetImpl(), *results[1]->GetImpl(),
                          operation);
+  std::vector<std::pair<std::shared_ptr<CsgLeafNode>, uint64_t>> heapNodes;
+  heapNodes.reserve(results.size());
+  for (size_t i = 0; i < results.size(); ++i) {
+    heapNodes.emplace_back(std::move(results[i]), i);
+  }
+  results.clear();
+  uint64_t nextSerial = heapNodes.size();
+
   // apply boolean operations starting from smaller meshes
   // the assumption is that boolean operations on smaller meshes is faster,
   // due to less data being copied and processed
   auto cmpFn = MeshCompare();
-  std::make_heap(results.begin(), results.end(), cmpFn);
-  std::vector<std::shared_ptr<CsgLeafNode>> tmp;
+  std::make_heap(heapNodes.begin(), heapNodes.end(), cmpFn);
+  std::vector<std::pair<std::shared_ptr<CsgLeafNode>, uint64_t>> tmp;
 #if MANIFOLD_PAR == 1
   tbb::task_group group;
   // make sure the order of result is deterministic
   std::vector<std::shared_ptr<CsgLeafNode>> parallelTmp;
+  std::vector<uint64_t> parallelSerial;
   for (int i = 0; i < 4; i++) parallelTmp.push_back(nullptr);
+  for (int i = 0; i < 4; i++) parallelSerial.push_back(0);
 #endif
-  while (results.size() > 1) {
-    for (size_t i = 0; i < 4 && results.size() > 1; i++) {
-      std::pop_heap(results.begin(), results.end(), cmpFn);
-      auto a = std::move(results.back());
-      results.pop_back();
-      std::pop_heap(results.begin(), results.end(), cmpFn);
-      auto b = std::move(results.back());
-      results.pop_back();
+  while (heapNodes.size() > 1) {
+    for (size_t i = 0; i < 4 && heapNodes.size() > 1; i++) {
+      std::pop_heap(heapNodes.begin(), heapNodes.end(), cmpFn);
+      auto a = std::move(heapNodes.back());
+      heapNodes.pop_back();
+      std::pop_heap(heapNodes.begin(), heapNodes.end(), cmpFn);
+      auto b = std::move(heapNodes.back());
+      heapNodes.pop_back();
 #if MANIFOLD_PAR == 1
-      group.run([&, i, a, b]() {
+      parallelSerial[i] = nextSerial++;
+      group.run([&, i, a = std::move(a.first), b = std::move(b.first)]() {
         parallelTmp[i] = SimpleBoolean(*a->GetImpl(), *b->GetImpl(), operation);
       });
 #else
-      auto result = SimpleBoolean(*a->GetImpl(), *b->GetImpl(), operation);
-      tmp.push_back(result);
+      auto result =
+          SimpleBoolean(*a.first->GetImpl(), *b.first->GetImpl(), operation);
+      tmp.emplace_back(std::move(result), nextSerial++);
 #endif
     }
 #if MANIFOLD_PAR == 1
     group.wait();
     for (int i = 0; i < 4 && parallelTmp[i]; i++)
-      tmp.emplace_back(std::move(parallelTmp[i]));
+      tmp.emplace_back(std::move(parallelTmp[i]), parallelSerial[i]);
 #endif
-    for (auto result : tmp) {
-      results.push_back(result);
-      std::push_heap(results.begin(), results.end(), cmpFn);
+    for (auto& result : tmp) {
+      heapNodes.push_back(std::move(result));
+      std::push_heap(heapNodes.begin(), heapNodes.end(), cmpFn);
     }
     tmp.clear();
   }
-  return results.front();
+  return heapNodes.front().first;
 }
 
 /**
diff --git a/src/impl.cpp b/src/impl.cpp
@@ -16,6 +16,8 @@
 
 #include <algorithm>
 #include <atomic>
+#include <cstdio>
+#include <cstdlib>
 #include <cstring>
 #include <iomanip>
 #include <map>
@@ -700,16 +702,48 @@ void Manifold::Impl::IncrementMeshIDs() {
 static std::ostream& WriteOBJWithEpsilon(std::ostream& stream,
                                          const MeshGL64& mesh,
                                          std::optional<double> epsilon) {
+  auto useHexFloat = []() {
+    const char* v = std::getenv("MANIFOLD_OBJ_HEX_FLOAT");
+    if (v == nullptr) return false;
+    return std::strcmp(v, "1") == 0 || std::strcmp(v, "true") == 0 ||
+           std::strcmp(v, "TRUE") == 0 || std::strcmp(v, "on") == 0 ||
+           std::strcmp(v, "ON") == 0;
+  };
+  const bool hexFloat = useHexFloat();
+  auto writeValue = [&](double value) {
+    if (hexFloat) {
+      // Use explicit C-format hex to keep text stable across standard library
+      // implementations.
+      char buf[128];
+      std::snprintf(buf, sizeof(buf), "%.13a", value);
+      stream << buf;
+    } else {
+      stream << value;
+    }
+  };
+
   stream << std::setprecision(19);  // for double precision
-  stream << std::fixed;             // for uniformity in output numbers
+  if (!hexFloat) {
+    stream << std::fixed;  // for uniformity in output numbers
+  }
   stream << "# ======= begin mesh ======" << std::endl;
-  stream << "# tolerance = " << mesh.tolerance << std::endl;
-  if (epsilon.has_value())
-    stream << "# epsilon = " << epsilon.value() << std::endl;
+  stream << "# float_format = " << (hexFloat ? "hexfloat" : "fixed")
+         << std::endl;
+  stream << "# tolerance = ";
+  writeValue(mesh.tolerance);
+  stream << std::endl;
+  if (epsilon.has_value()) {
+    stream << "# epsilon = ";
+    writeValue(epsilon.value());
+    stream << std::endl;
+  }
   for (size_t i = 0; i < mesh.NumVert(); i++) {
     stream << "v";
     size_t offset = i * mesh.numProp;
-    for (size_t j : {0, 1, 2}) stream << " " << mesh.vertProperties[offset + j];
+    for (size_t j : {0, 1, 2}) {
+      stream << " ";
+      writeValue(mesh.vertProperties[offset + j]);
+    }
     stream << std::endl;
   }
   std::vector<ivec3> triangles;
diff --git a/test/boolean_test.cpp b/test/boolean_test.cpp
