peclet-coupling 0.3.0__tar.gz → 0.4.0__tar.gz

{peclet_coupling-0.3.0 → peclet_coupling-0.4.0}/CMakeLists.txt

@@ -32,10 +32,18 @@ configure_file(${CMAKE_CURRENT_SOURCE_DIR}/python/peclet_coupling/__init__.py
                ${CMAKE_CURRENT_BINARY_DIR}/peclet/coupling/__init__.py COPYONLY)
 configure_file(${CMAKE_CURRENT_SOURCE_DIR}/python/peclet_coupling/driver.py
                ${CMAKE_CURRENT_BINARY_DIR}/peclet/coupling/driver.py COPYONLY)
+# resolved.py is imported by __init__.py, so omitting it makes a dev build unimportable.
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/python/peclet_coupling/resolved.py
+               ${CMAKE_CURRENT_BINARY_DIR}/peclet/coupling/resolved.py COPYONLY)
 target_include_directories(coupling PRIVATE src "${CORE_INC}")
 target_link_libraries(coupling PRIVATE Kokkos::kokkos)
 if(Kokkos_ENABLE_HIP)
   target_link_options(coupling PRIVATE -Wl,--no-gc-sections)
+  # HIP/lld experiment 1 (docs/RELEASE.md §8): nanobind sets CXX_VISIBILITY_PRESET hidden, and under hipcc
+  # the host objects then reference the Kokkos SharedAllocationRecord / shared_ptr control-block vtables
+  # as hidden symbols that nothing defines ("undefined hidden symbol: vtable for ..."). Default visibility
+  # on the HIP path only; CUDA/OpenMP builds are untouched.
+  set_target_properties(coupling PROPERTIES CXX_VISIBILITY_PRESET default)
 endif()
 
 option(PECLET_COUPLING_TESTS "Register the Python CFD-DEM integration tests as ctests" OFF)
@@ -45,12 +53,13 @@ if(PECLET_COUPLING_TESTS)
 endif()
 
 # --- pip / scikit-build-core install rule --------------------------------------------------------
-# Places the extension + the peclet/coupling package (__init__.py + driver.py) into the PEP-420
+# Places the extension + the peclet/coupling package (__init__.py + driver.py + resolved.py) into the PEP-420
 # peclet namespace. In an sdist build the core headers + nanobind come from PecletDeps (fetched at
 # the pinned tag), so the source distribution is self-contained.
 if(DEFINED SKBUILD)
   install(TARGETS coupling LIBRARY DESTINATION peclet/coupling COMPONENT python)
   install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/python/peclet_coupling/__init__.py
                 ${CMAKE_CURRENT_SOURCE_DIR}/python/peclet_coupling/driver.py
+                ${CMAKE_CURRENT_SOURCE_DIR}/python/peclet_coupling/resolved.py
           DESTINATION peclet/coupling COMPONENT python)
 endif()

{peclet_coupling-0.3.0 → peclet_coupling-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: peclet-coupling
-Version: 0.3.0
+Version: 0.4.0
 Summary: peclet.coupling — unresolved point-particle CFD-DEM coupling of peclet.flow + peclet.dem
 Author-Email: Frank Peters <e.a.j.f.peters@gmail.com>
 License-Expression: MIT

{peclet_coupling-0.3.0 → peclet_coupling-0.4.0}/cmake/PecletDeps.cmake

@@ -16,7 +16,7 @@ include(FetchContent)
 
 set(PECLET_KOKKOS_TAG "5.1.1" CACHE STRING "Vendored Kokkos git tag")
 set(PECLET_ARBORX_TAG "v2.1"  CACHE STRING "Vendored ArborX git tag")
-set(PECLET_TPX_TAG    "v0.5.0"  CACHE STRING "Vendored core git tag (headers)")
+set(PECLET_TPX_TAG    "v0.6.0"  CACHE STRING "Vendored core git tag (headers)")
 set(PECLET_MORTON_TAG "v0.2.1"  CACHE STRING "Vendored morton git tag (headers)")
 option(PECLET_VENDOR_DEPS "Force FetchContent-build of Kokkos/ArborX/siblings (self-contained wheel)" OFF)
 

{peclet_coupling-0.3.0 → peclet_coupling-0.4.0}/pyproject.toml

@@ -16,7 +16,7 @@ build-backend = "scikit_build_core.build"
 
 [project]
 name = "peclet-coupling"
-version = "0.3.0"
+version = "0.4.0"
 description = "peclet.coupling — unresolved point-particle CFD-DEM coupling of peclet.flow + peclet.dem"
 readme = "README.md"
 requires-python = ">=3.10"

peclet_coupling-0.4.0/python/peclet_coupling/__init__.py

@@ -0,0 +1,45 @@
+"""peclet.coupling — CFD-DEM coupling, unresolved and resolved.
+
+Composes peclet.flow (Eulerian fluid) + peclet.dem (Lagrangian particles).
+
+CfdDem is the UNRESOLVED point-particle driver: a grain is a point with a drag closure, and the
+compute kernels (particle<->grid deposition, drag laws, momentum feedback) live in the _coupling
+extension, running in place on the arrays the two solvers expose (zero-copy grid fields; particle
+forces round-tripped through the dem host API).
+
+ResolvedCfdDem is the RESOLVED driver (Layer 4 of suite/docs/ANALYTIC_SDF_GEOMETRY.md): each grain
+IS an analytic SDF instance in the flow solver's scene, the fluid resolves its surface, and the
+coupling is a surface-traction exchange with no drag correlation in it. Pure Python -- it needs no
+compiled kernels of its own.
+"""
+# The compiled kernels are needed by the UNRESOLVED driver only. ResolvedCfdDem is pure Python
+# composing peclet.flow + peclet.dem -- it has no C++ dependency at all -- so a missing extension
+# must not make it unimportable. CfdDem re-imports _coupling in its own constructor, where the
+# failure is still immediate and its message still points at the right thing.
+try:
+    from . import _coupling  # noqa: F401  (deposit_solid_volume, compute_void_fraction, ...)
+except ImportError:  # pragma: no cover
+    _coupling = None
+from .driver import CfdDem  # noqa: F401
+from .resolved import ResolvedCfdDem  # noqa: F401
+
+DRAG_STOKES = 0
+DRAG_SCHILLER_NAUMANN = 1
+DRAG_ERGUN = 2
+DRAG_DI_FELICE = 3
+DRAG_WEN_YU = 4
+DRAG_GIDASPOW = 5  # Ergun (dense) + Wen & Yu (dilute), switched at eps = 0.8
+DRAG_BEETSTRA = 6  # Beetstra-van der Hoef-Kuipers (2007) DNS drag — the published "BVK2"
+DRAG_TANG = 7      # Tang et al. (2015) DNS drag — what MFIX-Exa's "BVK2" option actually executes
+
+# The installed distribution's metadata (pyproject.toml) is the single source of truth for the version;
+# a build-tree import (PYTHONPATH=<build>) has no metadata and reports "0+unknown". This replaces a
+# hand-maintained literal that had drifted behind pyproject.toml in every package at 0.6.0.
+try:
+    from importlib.metadata import version as _dist_version
+    __version__ = _dist_version("peclet-coupling")
+except Exception:  # PackageNotFoundError (dev build), or a broken metadata install
+    __version__ = "0+unknown"
+
+__all__ = ["CfdDem", "ResolvedCfdDem", "_coupling", "DRAG_STOKES", "DRAG_SCHILLER_NAUMANN", "DRAG_ERGUN",
+           "DRAG_DI_FELICE", "DRAG_WEN_YU", "DRAG_GIDASPOW", "DRAG_BEETSTRA", "DRAG_TANG"]

peclet_coupling-0.4.0/python/peclet_coupling/resolved.py

@@ -0,0 +1,176 @@
+"""ResolvedCfdDem -- resolved (geometry-resolving) CFD-DEM.
+
+Layer 4 of suite/docs/ANALYTIC_SDF_GEOMETRY.md. Where `CfdDem` treats a grain as a point with a
+drag closure, this driver makes each grain an ANALYTIC SDF INSTANCE in the flow solver's scene: the
+fluid resolves the actual surface, no-slip is enforced on the moving wall by the cut-cell IBM
+(Layer 3 rung 2), the projection carries the wall's own volume flux (rung 3), and the coupling is a hydrodynamic-load exchange (rung L4-R2) with no drag correlation anywhere in it:
+by default the DISCRETE REACTION (route (b) of the design note's OPEN FOR REVIEW 1) -- the momentum
+the fluid actually lost to each grain, exactly conservative -- with the reconstructed traction
+integral available as force_method="traction" for diagnostics.
+
+Python-composed, like `CfdDem` and for the same reason: dem and flow stay separate method codes and
+nothing links them in C++. Per coupling step:
+
+  1. pull dem state (positions / quaternions / velocities / angular velocities) and push it into
+     flow's scene -- instance transforms plus rung-2 rigid-body motion;
+  2. flow.rebuild_geometry() -- re-derive SDF, cut-cell overlay, apertures and pressure operator;
+     the velocity and pressure fields survive it;
+  3. flow.step();
+  4. flow.hydro_force_torque() -> per-grain force; add gravity/buoyancy; hand to dem;
+  5. dem sub-steps at the DEM timestep, holding the fluid force constant.
+
+WEAK, EXPLICIT COUPLING (spec: L4-R3). The fluid force is lagged by one fluid step. That is the
+documented v1; a strongly-coupled variant would iterate 3-5 inside the step.
+
+FLOAT/DOUBLE BOUNDARY. dem carries float32 state, flow's scene is float64. The per-step instance
+rebuild converts; "zero-copy" is not literal across that divide, and does not need to be -- the
+instance array is a few hundred bytes per grain against a geometry rebuild measured in tens of ms.
+
+UNITS. Everything is in flow's grid units: cell spacing 1, cell (i,j,k) centred at (i,j,k), so dem
+positions and radii must be expressed in cells.
+
+HYDRODYNAMIC TORQUE (validated 2026-08-31). flow's reaction torque now carries the
+transposed-stress wall term (flow `16e91ec`) and is GATED: a spinning sphere reproduces the exact
+Stokes torque 8*pi*mu*a^3*Omega to +3.5/+2.4/+2.2% (converging with the aperture first moment),
+and THIS loop with apply_torque=True decays a freely spinning sphere at 1.039x the same box's
+calibrated rotational drag (rotation_gate.py part B). Before that term the torque was a structural
+-31% -- the missing traction mu*(n x Omega) integrates to zero in the FORCE, which is why no
+force-based gate ever saw it.
+
+apply_torque stays **off by default** for one remaining reason: dem assigns a DEFAULT inverse
+inertia unrelated to the grain's size, so handing a torque to a grain whose inertia was never set
+spins it up at an arbitrary rate (the settling gate diverged to 1e+09 that way). Set the physical
+principal inertia FIRST -- (2/5) m R^2 for a sphere, or `scene_particle`'s `inv_inertia_unit` --
+then enable. The torque is computed and reported through `torques()` either way.
+
+"""
+import numpy as np
+
+
+class ResolvedCfdDem:
+    def __init__(self, flow, dem, *, radius, mu, rho_f, fluid_dt, dem_substeps=20,
+                 periodic=True, gravity=(0.0, 0.0, 0.0), rho_p=None, move=True,
+                 buoyancy=True, apply_torque=False,
+                 force_method="reaction"):
+        self.flow = flow
+        self.dem = dem
+        self.mu = float(mu)
+        self.rho_f = float(rho_f)
+        self.fluid_dt = float(fluid_dt)
+        self.dem_substeps = int(dem_substeps)
+        self.dt_dem = self.fluid_dt / self.dem_substeps
+        self.gravity = np.asarray(gravity, dtype=np.float64)
+        self.move = bool(move)
+        self.buoyancy = bool(buoyancy)
+        self.radius = float(radius)
+        self.rho_p = float(rho_p) if rho_p is not None else None
+        self.periodic = bool(periodic)
+        # Hand the reaction TORQUE to dem as well as the force (dem R2, set_external_torques).
+        # The torque is VALIDATED (rotating-sphere + spin-decay gates, see the class docstring);
+        # off by default only because dem's default inverse inertia is not the grain's -- set a
+        # physical principal inertia first, then enable.
+        self.apply_torque = bool(apply_torque)
+        # "reaction" (default): the discrete-reaction force -- exactly conservative (the momentum
+        # the fluid lost IS the momentum the grain gains) and as accurate as the flow solution it
+        # sustains. "traction": the reconstructed surface integral, kept as a diagnostic; it
+        # under-reads the drag by a resolution-independent ~29% (measured), which in this loop
+        # shows up as a total-momentum leak. See suite/docs/ANALYTIC_SDF_GEOMETRY.md OPEN FOR
+        # REVIEW 1.
+        if force_method not in ("reaction", "traction"):
+            raise ValueError("force_method must be 'reaction' or 'traction'")
+        self.force_method = force_method
+        self.n = int(dem.num_particles())
+        self.last_force = np.zeros((self.n, 3))
+        self.last_torque = np.zeros((self.n, 3))
+        flow.set_dt(self.fluid_dt)
+        dem.set_dt(self.dt_dem)   # kept in sync, though step(dt) below passes it explicitly
+        self._install_scene()
+
+    # --- L4-R1: the dem -> scene bridge --------------------------------------------------------
+    _KN_R, _KI_I, _KI_R = 16, 2, 17
+
+    def _install_scene(self):
+        """One kSphere node, one instance per grain. Spheres first, per the spec; a shaped grain is
+        the same bridge with the grain's own node tree in place of the sphere leaf."""
+        node_ints = np.array([1, -1, -1], dtype=np.int32)          # kSphere
+        node_reals = np.zeros(self._KN_R)
+        node_reals[0] = self.radius
+        node_reals[14] = 1.0                                       # quaternion w
+        node_reals[15] = 1.0                                       # scale
+        ii, ir = self._instance_arrays()
+        self.flow.set_scene(node_ints, node_reals, ii.ravel(), ir.ravel(), periodic=self.periodic)
+        self._push_motion()
+        self.flow.set_solid_from_scene(True)
+
+    def _instance_arrays(self):
+        pos = np.asarray(self.dem.get_positions(), dtype=np.float64)
+        quat = np.asarray(self.dem.get_quaternions(), dtype=np.float64)
+        ii = np.zeros((self.n, self._KI_I), dtype=np.int32)
+        ir = np.zeros((self.n, self._KI_R))
+        ii[:, 0] = 0        # shapeRoot
+        ii[:, 1] = -1       # materialId
+        ir[:, 0:3] = pos[:, 0:3]
+        ir[:, 3:7] = quat[:, 0:4]   # (x,y,z,w)
+        ir[:, 7] = 1.0              # scale
+        return ii, ir
+
+    def _push_motion(self):
+        """Instance transforms + rigid-body velocities, straight from dem state."""
+        pos = np.asarray(self.dem.get_positions(), dtype=np.float64)
+        quat = np.asarray(self.dem.get_quaternions(), dtype=np.float64)
+        vel = np.asarray(self.dem.get_velocities(), dtype=np.float64)
+        omg = np.asarray(self.dem.get_angular_velocities(), dtype=np.float64)
+        for i in range(self.n):
+            self.flow.set_instance_transform(i, pos[i, 0:3].tolist(), quat[i, 0:4].tolist())
+            self.flow.set_instance_motion(i, lin_vel=vel[i, 0:3].tolist(),
+                                          ang_vel=omg[i, 0:3].tolist())
+
+    # --- L4-R3: the motion loop ----------------------------------------------------------------
+    def step(self):
+        if self.move:
+            self._push_motion()
+            self.flow.rebuild_geometry()
+        self.flow.step()
+        if self.force_method == "reaction":
+            ft = np.asarray(self.flow.hydro_force_torque_reaction())   # (2, n, 3): F, tau
+            self.last_force = np.array(ft[0][: self.n], dtype=np.float64)
+            self.last_torque = np.array(ft[1][: self.n], dtype=np.float64)
+            self.last_force_pressure = None   # the reaction has no pressure/viscous split
+            self.last_force_viscous = None
+        else:
+            ft = np.asarray(self.flow.hydro_force_torque())   # (4, n, 3): F, tau, F_p, F_visc
+            self.last_force = np.array(ft[0][: self.n], dtype=np.float64)
+            self.last_torque = np.array(ft[1][: self.n], dtype=np.float64)
+            self.last_force_pressure = np.array(ft[2][: self.n], dtype=np.float64)
+            self.last_force_viscous = np.array(ft[3][: self.n], dtype=np.float64)
+        if not self.move:
+            return
+        F = self.last_force.copy()
+        if self.buoyancy and self.rho_p is not None:
+            # The resolved traction already contains the hydrostatic part of the pressure field, so
+            # what is added here is only the BODY force on the grain itself. Net gravity on a grain
+            # of density rho_p displacing rho_f is (rho_p - rho_f) V g when the fluid carries the
+            # hydrostatic gradient; when it does not (the usual periodic set-up, no gravity in the
+            # fluid), the full rho_p V g applies. buoyancy=False selects the latter.
+            V = 4.0 / 3.0 * np.pi * self.radius**3
+            F += (self.rho_p - self.rho_f) * V * self.gravity
+        elif self.rho_p is not None:
+            V = 4.0 / 3.0 * np.pi * self.radius**3
+            F += self.rho_p * V * self.gravity
+        self.dem.set_external_forces(np.ascontiguousarray(F, dtype=np.float32))
+        if self.apply_torque:
+            # World-frame torque; dem rotates it into the body frame in the predictor. Held
+            # constant over the sub-steps, exactly like the force.
+            self.dem.set_external_torques(
+                np.ascontiguousarray(self.last_torque, dtype=np.float32))
+        for _ in range(self.dem_substeps):
+            # dt MUST be passed explicitly. dem's step(dt=0) is a dynamics-free relaxation step
+            # (overlap removal only), so step() with no argument advances nothing and the driver
+            # would run happily with a frozen particle.
+            self.dem.step(self.dt_dem)
+
+    def forces(self):
+        return self.last_force
+
+    def torques(self):
+        return self.last_torque

{peclet_coupling-0.3.0 → peclet_coupling-0.4.0}/src/coupling_bindings.cpp

@@ -6,8 +6,12 @@
 /// so a coupled run never links the two solvers in C++ — the Python CfdDem driver composes them.
 /// Particle arrays are float32 (dem SoA precision), grid fields float64 (flow field precision); each
 /// array is wrapped as an unmanaged Kokkos View over the SAME memory (zero-copy on host and, for
-/// DLPack device arrays on a GPU build, on device). Kokkos is initialised at import; the arrays are
-/// borrowed (owned by the caller), so there is nothing to release at exit.
+/// DLPack device arrays on a GPU build, on device). The arrays are borrowed (owned by the caller),
+/// so this module owns no Kokkos Views and its teardown registry stays empty; it still follows the
+/// suite-wide pattern of peclet/core/python/kokkos_teardown.hpp (Kokkos initialised at import, one
+/// atexit hook that releases and THEN finalizes -- required on CUDA, where a Kokkos left to its
+/// static destructors aborts with cudaErrorCudartUnloading after the runtime unloads -- plus
+/// `finalize()` and `execution_space`).
 #include <nanobind/nanobind.h>
 #include <nanobind/ndarray.h>
 
@@ -15,6 +19,7 @@
 #include <stdexcept>
 
 #include "coupling_kernels.hpp"
+#include "peclet/core/python/kokkos_teardown.hpp"
 #include "peclet/core/python/ndarray_interop.hpp"
 
 namespace nb = nanobind;
@@ -64,8 +69,9 @@ GridMap gmap(double ox, double oy, double oz, double h, int ex, int ey, int ez,
 
 NB_MODULE(_coupling, m) {
   m.doc() = "CFD-DEM coupling kernels (deposition, drag, momentum feedback) on shared arrays.";
-  if (!Kokkos::is_initialized())
-    Kokkos::initialize();
+  // Kokkos init + the release-then-finalize atexit hook + finalize() + execution_space (the
+  // suite-wide teardown pattern; see the file comment).
+  peclet::core::python::install(m);
 
   m.def(
       "deposit_solid_volume",

peclet_coupling-0.3.0/python/peclet_coupling/__init__.py

@@ -1,23 +0,0 @@
-"""peclet.coupling — unresolved point-particle CFD-DEM coupling.
-
-Composes peclet.flow (Eulerian fluid) + peclet.dem (Lagrangian particles) via the CfdDem driver.
-The compute kernels (particle<->grid deposition, drag laws, momentum feedback) live in the _coupling
-extension and run in place on the arrays the two solvers expose (zero-copy grid fields; particle
-forces round-tripped through the dem host API).
-"""
-from . import _coupling  # noqa: F401  (deposit_solid_volume, compute_void_fraction, compute_drag_feedback)
-from .driver import CfdDem  # noqa: F401
-
-DRAG_STOKES = 0
-DRAG_SCHILLER_NAUMANN = 1
-DRAG_ERGUN = 2
-DRAG_DI_FELICE = 3
-DRAG_WEN_YU = 4
-DRAG_GIDASPOW = 5  # Ergun (dense) + Wen & Yu (dilute), switched at eps = 0.8
-DRAG_BEETSTRA = 6  # Beetstra-van der Hoef-Kuipers (2007) DNS drag — the published "BVK2"
-DRAG_TANG = 7      # Tang et al. (2015) DNS drag — what MFIX-Exa's "BVK2" option actually executes
-
-__version__ = "0.2.0"
-
-__all__ = ["CfdDem", "_coupling", "DRAG_STOKES", "DRAG_SCHILLER_NAUMANN", "DRAG_ERGUN",
-           "DRAG_DI_FELICE", "DRAG_WEN_YU", "DRAG_GIDASPOW", "DRAG_BEETSTRA", "DRAG_TANG"]