peclet-core 1.3.1__tar.gz → 1.3.2__tar.gz

{peclet_core-1.3.1 → peclet_core-1.3.2}/CITATION.cff

@@ -16,8 +16,8 @@ authors:
     orcid: "https://orcid.org/0000-0001-6099-3583"
     email: e.a.j.f.peters@tue.nl
     affiliation: "Eindhoven University of Technology"
-version: 1.3.1
-date-released: 2026-09-27
+version: 1.3.2
+date-released: 2026-10-03
 license: MIT
 doi: 10.5281/zenodo.21132435
 identifiers:

{peclet_core-1.3.1 → peclet_core-1.3.2}/CLAUDE.md

@@ -37,7 +37,7 @@ ctest --test-dir build --output-on-failure -LE bench   # 76 ctests (77 with `ben
 export PATH=/usr/local/cuda-13.2/bin:$PATH    # if the Kokkos install targets the CUDA backend
 cmake -S . -B build_kokkos -DPECLET_CORE_ENABLE_KOKKOS=ON \
   -DCMAKE_PREFIX_PATH=../extern/install/nvidia-cuda
-cmake --build build_kokkos -j && ctest --test-dir build_kokkos --output-on-failure -LE bench  # 91 ctests (92 with `bench`): + device halo / geometry / solver, np=1,2,4,8
+cmake --build build_kokkos -j && ctest --test-dir build_kokkos --output-on-failure -LE bench  # 92 ctests (93 with `bench`): + device halo / geometry / solver / VoF PV fit, np=1,2,4,8
 mpirun -np 4 ./build/benchmarks/bench_halo 48 1 300
 
 # Python modules + their ctests (test_mpi.py np=1,2,4,8; state_hash; ndarray interop). Release is

{peclet_core-1.3.1 → peclet_core-1.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: peclet-core
-Version: 1.3.1
+Version: 1.3.2
 Summary: peclet.core — compatibility shell: peclet.core.geom is now peclet.geom, peclet.core.mpi is now peclet.halo
 Project-URL: Homepage, https://github.com/computational-chemical-engineering/peclet
 Project-URL: Documentation, https://computational-chemical-engineering.github.io/peclet/

{peclet_core-1.3.1 → peclet_core-1.3.2}/docs/Doxyfile

@@ -5,7 +5,7 @@
 
 DOXYFILE_ENCODING      = UTF-8
 PROJECT_NAME           = "core"
-PROJECT_NUMBER         = 1.3.1
+PROJECT_NUMBER         = 1.3.2
 PROJECT_BRIEF          = "Shared MPI block decomposition, asynchronous ghost-layer exchange, SDF geometry, load balancing (header-only C++20)"
 OUTPUT_DIRECTORY       = docs
 HTML_OUTPUT            = html

{peclet_core-1.3.1 → peclet_core-1.3.2}/include/peclet/core/vof/curvature.hpp

@@ -729,7 +729,7 @@ KOKKOS_INLINE_FUNCTION void pvFitInit(PvFit& f) {
   f.npoly = 0;
 }
 
-/// Fold one stencil cell's PLIC polygon into the fit.
+/// One stencil cell's PLIC polygon in the PV fit: the parameters of `pvFitTerm` and `pvFitAdd`.
 ///
 /// @param mx,my,mz,alpha  the cell's PLIC plane in ITS OWN unit-cell coordinates (`plic.hpp`).
 /// @param off             the cell's integer index offset from the target cell.
@@ -744,11 +744,25 @@ KOKKOS_INLINE_FUNCTION void pvFitInit(PvFit& f) {
 ///                        integrated with the wrong sign of `z'`. Jibben's area projection
 ///                        `A (n.n_p)` decays to zero over the same range; this is the explicit
 ///                        version of the same guard.
-/// @return true if the polygon contributed.
-KOKKOS_INLINE_FUNCTION bool pvFitAdd(PvFit& f, double mx, double my, double mz, double alpha,
-                                     const double off[3], const double org[3], const double t1[3],
-                                     const double t2[3], const double nn[3], double dW,
-                                     double cosMin, const VofMetric& g) {
+///
+/// `pvFitAdd` is the composition of `pvFitTerm` (the per-polygon map) and `pvFitAccum` (the `+=`
+/// into the normal equations), bitwise (`tests/test_vof_pvfit.cpp`). The split lets a device
+/// fallback evaluate the stencil's terms in parallel and still accumulate them in the canonical
+/// order (flow `doc/vof_step_performance_design.md` §4.7, §5.11).
+struct PvTerm {
+  double w, B, s[6];
+  bool ok;
+};
+
+/// One stencil polygon's contribution to the PV fit: everything `pvFitAdd` computes before the
+/// accumulation — the polygon, the frame transform, the moments `s`, the Wendland weight `w` and
+/// `B`. Same parameters as `pvFitAdd`. Sets `t.ok` and returns it: false exactly where `pvFitAdd`
+/// returns false (a rejected polygon), and then `w`, `B`, `s` are unspecified.
+KOKKOS_INLINE_FUNCTION bool pvFitTerm(PvTerm& t, double mx, double my, double mz, double alpha,
+                                      const double off[3], const double org[3], const double t1[3],
+                                      const double t2[3], const double nn[3], double dW,
+                                      double cosMin, const VofMetric& g) {
+  t.ok = false;
   const double n2 = mx * mx + my * my + mz * mz;
   if (!(n2 > 0.0))
     return false;
@@ -804,12 +818,38 @@ KOKKOS_INLINE_FUNCTION bool pvFitAdd(PvFit& f, double mx, double my, double mz,
     return false;
 
   const double B = b0 * s[0] + b1 * s[1] + b2 * s[2];
+  t.w = w;
+  t.B = B;
+  for (int i = 0; i < 6; ++i)
+    t.s[i] = s[i];
+  t.ok = true;
+  return true;
+}
+
+/// Fold one accepted term (`t.ok`) into the fit — the accumulation half of `pvFitAdd`, with its
+/// expressions verbatim. Calling it in the stencil's canonical order reproduces `pvFitAdd`'s sums.
+KOKKOS_INLINE_FUNCTION void pvFitAccum(PvFit& f, const PvTerm& t) {
+  const double w = t.w, B = t.B;
+  const double* s = t.s;
   for (int i = 0; i < 6; ++i) {
     f.b[i] += w * s[i] * B;
     for (int j = 0; j < 6; ++j)
       f.A[i][j] += w * s[i] * s[j];
   }
   ++f.npoly;
+}
+
+/// Fold one stencil cell's PLIC polygon into the fit: `pvFitTerm`, then `pvFitAccum` if the
+/// polygon is accepted. Parameters as documented above `PvTerm`.
+/// @return true if the polygon contributed.
+KOKKOS_INLINE_FUNCTION bool pvFitAdd(PvFit& f, double mx, double my, double mz, double alpha,
+                                     const double off[3], const double org[3], const double t1[3],
+                                     const double t2[3], const double nn[3], double dW,
+                                     double cosMin, const VofMetric& g) {
+  PvTerm t;
+  if (!pvFitTerm(t, mx, my, mz, alpha, off, org, t1, t2, nn, dW, cosMin, g))
+    return false;
+  pvFitAccum(f, t);
   return true;
 }
 

{peclet_core-1.3.1 → peclet_core-1.3.2}/packaging/pyproject-core.toml

@@ -19,7 +19,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "peclet-core"
-version = "1.3.1"
+version = "1.3.2"
 description = "peclet.core — compatibility shell: peclet.core.geom is now peclet.geom, peclet.core.mpi is now peclet.halo"
 readme = "README.md"
 requires-python = ">=3.10"

{peclet_core-1.3.1 → peclet_core-1.3.2}/pyproject.toml

@@ -19,7 +19,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "peclet-core"
-version = "1.3.1"
+version = "1.3.2"
 description = "peclet.core — compatibility shell: peclet.core.geom is now peclet.geom, peclet.core.mpi is now peclet.halo"
 readme = "README.md"
 requires-python = ">=3.10"

{peclet_core-1.3.1 → peclet_core-1.3.2}/tests/CMakeLists.txt

@@ -282,6 +282,14 @@ if(MPI_FOUND)
     target_link_libraries(test_csr_solver PRIVATE Kokkos::kokkos)
     peclet_core_add_test(csr_solver test_csr_solver)
 
+    # VoF PV fit: pvFitAdd == pvFitTerm + pvFitAccum bitwise, device and host spaces (10^5
+    # random cases incl. rejected polygons; flow vof_step_performance_design.md §5.11, WO-7a).
+    add_executable(test_vof_pvfit test_vof_pvfit.cpp)
+    target_include_directories(test_vof_pvfit PRIVATE
+      ${PROJECT_SOURCE_DIR}/include ${CMAKE_CURRENT_SOURCE_DIR})
+    target_link_libraries(test_vof_pvfit PRIVATE Kokkos::kokkos)
+    peclet_core_add_test(vof_pvfit test_vof_pvfit)
+
     # Device GraphAMG apply vs the host oracle (no MPI; serial + device).
     add_executable(test_graph_amg_device test_graph_amg_device.cpp)
     target_include_directories(test_graph_amg_device PRIVATE

peclet_core-1.3.2/tests/test_vof_pvfit.cpp

@@ -0,0 +1,305 @@
+// pvFitAdd == pvFitTerm + pvFitAccum, BITWISE, on the default execution space (CUDA / HIP /
+// OpenMP) and on the host space (flow doc/vof_step_performance_design.md §4.7, §5.11, WO-7a).
+//
+// Three accumulations of the same stencils, each on the same backend:
+//   ref   a frozen copy of pvFitAdd as it was before the split (below, verbatim body);
+//   add   today's pvFitAdd (the composition);
+//   team  the device fallback's shape: one kernel writes every stencil cell's PvTerm to memory,
+//         a second kernel folds the accepted terms with pvFitAccum in the canonical order.
+// 10^5 random cases (800 stencils x 5^3 cells), random planes, frames, origins, metrics and guards,
+// with a planted share of rejected polygons (zero normal, plane missing the cell, normal below
+// cosMin, outside the Wendland support). Every accumulator byte and every accept flag must match.
+#include <cstdint>
+#include <cstdio>
+#include <cstring>
+#include <Kokkos_Core.hpp>
+#include <vector>
+
+#include "peclet/core/vof/curvature.hpp"
+
+using namespace peclet::core::vof;
+
+namespace {
+
+// --- the pre-split pvFitAdd (core 6859d4e), verbatim apart from its name -------------------------
+KOKKOS_INLINE_FUNCTION bool pvFitAddReference(PvFit& f, double mx, double my, double mz,
+                                              double alpha, const double off[3],
+                                              const double org[3], const double t1[3],
+                                              const double t2[3], const double nn[3], double dW,
+                                              double cosMin, const VofMetric& g) {
+  const double n2 = mx * mx + my * my + mz * mz;
+  if (!(n2 > 0.0))
+    return false;
+  // Phase 3 (V2.4): the polygon's own normal enters the fit as a PHYSICAL direction (the frame is
+  // physical), so it is pulled back through H^-1 and renormalized. At g.h = {1,1,1} the pullback
+  // is `m/1.0` and `invn` is the same reciprocal square root as before — bitwise.
+  const double mi[3] = {mx / g.h[0], my / g.h[1], mz / g.h[2]};
+  const double invn = 1.0 / Kokkos::sqrt(mi[0] * mi[0] + mi[1] * mi[1] + mi[2] * mi[2]);
+  const double np[3] = {(mi[0] * t1[0] + mi[1] * t1[1] + mi[2] * t1[2]) * invn,
+                        (mi[0] * t2[0] + mi[1] * t2[1] + mi[2] * t2[2]) * invn,
+                        (mi[0] * nn[0] + mi[1] * nn[1] + mi[2] * nn[2]) * invn};
+  if (!(np[2] > cosMin))
+    return false;
+
+  double v[8][3];
+  const int nv = plicPolygon(mx, my, mz, alpha, v);
+  if (nv < 3)
+    return false;
+
+  // cell-local [0,1]^3 -> target-centred cell units -> the fit frame
+  double xy[8][2];
+  double zc = 0.0;
+  double px = 0.0, py = 0.0;
+  for (int k = 0; k < nv; ++k) {
+    const double Xi[3] = {off[0] + v[k][0] - 0.5 - org[0], off[1] + v[k][1] - 0.5 - org[1],
+                          off[2] + v[k][2] - 0.5 - org[2]};
+    double X[3];
+    g.toPhys(Xi, X);  // index displacement -> physical (identity at g.h = {1,1,1})
+    xy[k][0] = X[0] * t1[0] + X[1] * t1[1] + X[2] * t1[2];
+    xy[k][1] = X[0] * t2[0] + X[1] * t2[1] + X[2] * t2[2];
+    const double z = X[0] * nn[0] + X[1] * nn[1] + X[2] * nn[2];
+    px += xy[k][0];
+    py += xy[k][1];
+    zc += z;
+  }
+  const double invv = 1.0 / static_cast<double>(nv);
+  px *= invv;
+  py *= invv;
+  zc *= invv;
+
+  double s[6];
+  polygonMoments2d(xy, nv, s);
+  if (!(Kokkos::fabs(s[0]) > 1e-14))
+    return false;
+
+  // the polygon's own plane in the fit frame: z' = b0 + b1 x' + b2 y'
+  const double b1 = -np[0] / np[2], b2 = -np[1] / np[2];
+  const double b0 = zc - b1 * px - b2 * py;
+
+  const double r = Kokkos::sqrt(px * px + py * py + zc * zc);
+  const double w = wendlandWeight(r, dW);
+  if (!(w > 0.0))
+    return false;
+
+  const double B = b0 * s[0] + b1 * s[1] + b2 * s[2];
+  for (int i = 0; i < 6; ++i) {
+    f.b[i] += w * s[i] * B;
+    for (int j = 0; j < 6; ++j)
+      f.A[i][j] += w * s[i] * s[j];
+  }
+  ++f.npoly;
+  return true;
+}
+
+constexpr int kSide = 5, kCells = kSide * kSide * kSide, kStencils = 800;
+constexpr int kCases = kStencils * kCells;  // 100000
+
+struct Stencil {
+  double org[3], t1[3], t2[3], nn[3], dW, cosMin;
+  VofMetric g;
+};
+struct Cell {
+  double mx, my, mz, alpha, off[3];
+};
+
+struct Rng {  // splitmix64: fixed seed, identical sequence on every host
+  std::uint64_t s;
+  std::uint64_t next() {
+    std::uint64_t z = (s += 0x9e3779b97f4a7c15ULL);
+    z = (z ^ (z >> 30)) * 0xbf58476d1ce4e5b9ULL;
+    z = (z ^ (z >> 27)) * 0x94d049bb133111ebULL;
+    return z ^ (z >> 31);
+  }
+  double uni() { return (next() >> 11) * 0x1.0p-53; }  // [0,1)
+  double sym() { return 2.0 * uni() - 1.0; }           // [-1,1)
+};
+
+void unit(double v[3]) {
+  const double n = std::sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]);
+  for (int a = 0; a < 3; ++a)
+    v[a] /= n;
+}
+
+void makeCases(std::vector<Stencil>& st, std::vector<Cell>& ce) {
+  Rng r{20261002ULL};
+  st.resize(kStencils);
+  ce.resize(kCases);
+  for (int s = 0; s < kStencils; ++s) {
+    Stencil& S = st[s];
+    double nn[3] = {r.sym(), r.sym(), r.sym()};
+    unit(nn);
+    // t1 = any unit vector orthogonal to nn, t2 = nn x t1
+    double a[3] = {1, 0, 0};
+    if (std::fabs(nn[0]) > 0.6)
+      a[0] = 0, a[1] = 1;
+    const double d = a[0] * nn[0] + a[1] * nn[1] + a[2] * nn[2];
+    double t1[3] = {a[0] - d * nn[0], a[1] - d * nn[1], a[2] - d * nn[2]};
+    unit(t1);
+    const double t2[3] = {nn[1] * t1[2] - nn[2] * t1[1], nn[2] * t1[0] - nn[0] * t1[2],
+                          nn[0] * t1[1] - nn[1] * t1[0]};
+    for (int k = 0; k < 3; ++k) {
+      S.nn[k] = nn[k];
+      S.t1[k] = t1[k];
+      S.t2[k] = t2[k];
+      S.org[k] = 0.5 * r.sym();
+    }
+    S.dW = (s % 50 == 7) ? 0.0 : 1.5 + 2.0 * r.uni();  // a few unweighted stencils (d <= 0)
+    const double cm[4] = {0.0, 0.2, 0.5, -1.0};
+    S.cosMin = cm[s % 4];
+    if (s % 3 != 0)  // two thirds anisotropic
+      for (int k = 0; k < 3; ++k)
+        S.g.h[k] = 0.5 + 1.5 * r.uni();
+    for (int k = 0; k < kCells; ++k) {
+      Cell& C = ce[s * kCells + k];
+      C.off[0] = k % kSide - 2;
+      C.off[1] = (k / kSide) % kSide - 2;
+      C.off[2] = k / (kSide * kSide) - 2;
+      const int kind = static_cast<int>(r.next() % 20);
+      if (kind == 0) {  // degenerate normal
+        C.mx = C.my = C.mz = 0.0;
+      } else if (kind <= 3) {  // random direction (many fall below cosMin)
+        C.mx = r.sym(), C.my = r.sym(), C.mz = r.sym();
+      } else {  // near the target normal, in index space
+        C.mx = nn[0] * S.g.h[0] + 0.3 * r.sym();
+        C.my = nn[1] * S.g.h[1] + 0.3 * r.sym();
+        C.mz = nn[2] * S.g.h[2] + 0.3 * r.sym();
+      }
+      if (kind == 1) {  // plane well outside the cube: no polygon
+        C.alpha = 3.0 + r.uni();
+      } else {  // plane through a random point of the cell
+        const double p[3] = {r.uni(), r.uni(), r.uni()};
+        C.alpha = C.mx * p[0] + C.my * p[1] + C.mz * p[2];
+      }
+    }
+  }
+}
+
+struct Result {
+  std::vector<PvFit> ref, add, team;
+  std::vector<int> fref, fadd, fterm;
+};
+
+template <class Exec>
+Result run(const std::vector<Stencil>& st, const std::vector<Cell>& ce) {
+  using Mem = typename Exec::memory_space;
+  Kokkos::View<Stencil*, Mem> S("st", kStencils);
+  Kokkos::View<Cell*, Mem> C("ce", kCases);
+  {
+    auto hs = Kokkos::create_mirror_view(S);
+    auto hc = Kokkos::create_mirror_view(C);
+    for (int i = 0; i < kStencils; ++i)
+      hs(i) = st[i];
+    for (int i = 0; i < kCases; ++i)
+      hc(i) = ce[i];
+    Kokkos::deep_copy(S, hs);
+    Kokkos::deep_copy(C, hc);
+  }
+  Kokkos::View<PvFit*, Mem> ref("ref", kStencils), add("add", kStencils), team("team", kStencils);
+  Kokkos::View<int*, Mem> fref("fref", kCases), fadd("fadd", kCases), fterm("fterm", kCases);
+  Kokkos::View<PvTerm*, Mem> terms("terms", kCases);
+
+  // ref and add: one thread per stencil, cells in canonical order (as curvFallbackCell does).
+  // Separate kernels, so the compiler cannot merge the two identical computations into one.
+  Kokkos::parallel_for(
+      "pvfit_ref", Kokkos::RangePolicy<Exec>(0, kStencils), KOKKOS_LAMBDA(const int s) {
+        const Stencil& T = S(s);
+        PvFit f;
+        pvFitInit(f);
+        for (int k = 0; k < kCells; ++k) {
+          const Cell& c = C(s * kCells + k);
+          fref(s * kCells + k) = pvFitAddReference(f, c.mx, c.my, c.mz, c.alpha, c.off, T.org, T.t1,
+                                                   T.t2, T.nn, T.dW, T.cosMin, T.g);
+        }
+        ref(s) = f;
+      });
+  Kokkos::parallel_for(
+      "pvfit_add", Kokkos::RangePolicy<Exec>(0, kStencils), KOKKOS_LAMBDA(const int s) {
+        const Stencil& T = S(s);
+        PvFit f;
+        pvFitInit(f);
+        for (int k = 0; k < kCells; ++k) {
+          const Cell& c = C(s * kCells + k);
+          fadd(s * kCells + k) = pvFitAdd(f, c.mx, c.my, c.mz, c.alpha, c.off, T.org, T.t1, T.t2,
+                                          T.nn, T.dW, T.cosMin, T.g);
+        }
+        add(s) = f;
+      });
+  // team shape: the map over every case, then the ordered fold
+  Kokkos::parallel_for(
+      "pvfit_term", Kokkos::RangePolicy<Exec>(0, kCases), KOKKOS_LAMBDA(const int i) {
+        const Stencil& T = S(i / kCells);
+        const Cell& c = C(i);
+        PvTerm t;
+        fterm(i) = pvFitTerm(t, c.mx, c.my, c.mz, c.alpha, c.off, T.org, T.t1, T.t2, T.nn, T.dW,
+                             T.cosMin, T.g);
+        terms(i) = t;
+      });
+  Kokkos::parallel_for(
+      "pvfit_accum", Kokkos::RangePolicy<Exec>(0, kStencils), KOKKOS_LAMBDA(const int s) {
+        PvFit f;
+        pvFitInit(f);
+        for (int k = 0; k < kCells; ++k)
+          if (terms(s * kCells + k).ok)
+            pvFitAccum(f, terms(s * kCells + k));
+        team(s) = f;
+      });
+  Kokkos::fence();
+
+  Result R;
+  auto pull = [](auto v, auto& out) {
+    auto h = Kokkos::create_mirror_view_and_copy(Kokkos::HostSpace(), v);
+    out.assign(h.data(), h.data() + h.extent(0));
+  };
+  pull(ref, R.ref);
+  pull(add, R.add);
+  pull(team, R.team);
+  pull(fref, R.fref);
+  pull(fadd, R.fadd);
+  pull(fterm, R.fterm);
+  return R;
+}
+
+bool sameFit(const PvFit& a, const PvFit& b) {
+  return std::memcmp(a.A, b.A, sizeof a.A) == 0 && std::memcmp(a.b, b.b, sizeof a.b) == 0 &&
+         a.npoly == b.npoly;
+}
+
+int check(const char* name, const Result& R) {
+  int badFit = 0, badFlag = 0, accepted = 0, fitted = 0;
+  for (int s = 0; s < kStencils; ++s) {
+    badFit += !sameFit(R.ref[s], R.add[s]) || !sameFit(R.ref[s], R.team[s]);
+    fitted += R.ref[s].npoly >= 6;
+  }
+  for (int i = 0; i < kCases; ++i) {
+    badFlag += (R.fref[i] != R.fadd[i]) || (R.fref[i] != R.fterm[i]);
+    accepted += R.fref[i];
+  }
+  const int rejected = kCases - accepted;
+  std::printf(
+      "[%s] %d cases: %d accepted, %d rejected; %d/%d stencils with npoly >= 6; "
+      "accumulator mismatches %d, flag mismatches %d\n",
+      name, kCases, accepted, rejected, fitted, kStencils, badFit, badFlag);
+  // non-vacuous: both branches exercised in volume, and most stencils carry a real fit
+  const bool coverage = accepted > kCases / 5 && rejected > kCases / 20 && fitted > kStencils / 2;
+  if (!coverage)
+    std::printf("[%s] FAIL: coverage too thin to mean anything\n", name);
+  return badFit + badFlag + (coverage ? 0 : 1);
+}
+
+}  // namespace
+
+int main(int argc, char** argv) {
+  Kokkos::initialize(argc, argv);
+  int bad = 0;
+  {
+    std::vector<Stencil> st;
+    std::vector<Cell> ce;
+    makeCases(st, ce);
+    bad += check(Kokkos::DefaultExecutionSpace::name(), run<Kokkos::DefaultExecutionSpace>(st, ce));
+    bad += check(Kokkos::DefaultHostExecutionSpace::name(),
+                 run<Kokkos::DefaultHostExecutionSpace>(st, ce));
+  }
+  Kokkos::finalize();
+  std::printf(bad ? "FAIL\n" : "PASS\n");
+  return bad ? 1 : 0;
+}