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

{peclet_coupling-0.2.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.2.0 → peclet_coupling-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: peclet-coupling
-Version: 0.2.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
@@ -32,9 +32,15 @@ architecture (Python is the composition layer).
 Per fluid step (`CfdDem.step()`):
 1. **Void fraction** — scatter each particle's volume onto the grid (trilinear, **wall-aware**: near
    an immersed solid the weights re-normalise over the fluid corners so no hold-up leaks into walls),
-   periodic-fold the ghost deposits, and `ε = clamp(1 − Vsolid/Vcell, eps_min, 1)`. The floor
-   `eps_min` defaults to 0.4 ≈ the random-close-packing voidage (the drag correlations are invalid,
-   and Ergun's `1/ε` powers explosive, below a physical packing).
+   fold the ghost deposits (periodic wrap on periodic axes; **same-side fold onto the boundary cell
+   at a non-periodic domain face** — a grain resting on the distributor scatters part of its volume
+   below z=0, and that hold-up belongs to the bottom cell, not to a ghost the fluid never owns), and
+   `ε = clamp(1 − Vsolid/Vcell, eps_min, 1)`. The floor `eps_min` defaults to 0.4 ≈ the
+   random-close-packing voidage (the drag correlations are invalid, and Ergun's `1/ε` powers
+   explosive, below a physical packing). A particle whose trilinear stencil falls **outside the
+   domain by more than one ghost layer** (e.g. pushed through a DEM wall by a violent contact solve)
+   is dropped from the exchange entirely — no deposit, zero drag — so a runaway escapee can never
+   feed a diverging `β·u_p` source into the boundary row.
 2. **Drag + feedback** — gather the fluid velocity and ε at each particle, evaluate the drag law
    (Stokes / Schiller–Naumann / Ergun / Di Felice / Wen & Yu / Gidaspow), write the drag force to the
    particles and deposit the reaction onto the fluid momentum source.

{peclet_coupling-0.2.0 → peclet_coupling-0.4.0}/README.md

@@ -16,9 +16,15 @@ architecture (Python is the composition layer).
 Per fluid step (`CfdDem.step()`):
 1. **Void fraction** — scatter each particle's volume onto the grid (trilinear, **wall-aware**: near
    an immersed solid the weights re-normalise over the fluid corners so no hold-up leaks into walls),
-   periodic-fold the ghost deposits, and `ε = clamp(1 − Vsolid/Vcell, eps_min, 1)`. The floor
-   `eps_min` defaults to 0.4 ≈ the random-close-packing voidage (the drag correlations are invalid,
-   and Ergun's `1/ε` powers explosive, below a physical packing).
+   fold the ghost deposits (periodic wrap on periodic axes; **same-side fold onto the boundary cell
+   at a non-periodic domain face** — a grain resting on the distributor scatters part of its volume
+   below z=0, and that hold-up belongs to the bottom cell, not to a ghost the fluid never owns), and
+   `ε = clamp(1 − Vsolid/Vcell, eps_min, 1)`. The floor `eps_min` defaults to 0.4 ≈ the
+   random-close-packing voidage (the drag correlations are invalid, and Ergun's `1/ε` powers
+   explosive, below a physical packing). A particle whose trilinear stencil falls **outside the
+   domain by more than one ghost layer** (e.g. pushed through a DEM wall by a violent contact solve)
+   is dropped from the exchange entirely — no deposit, zero drag — so a runaway escapee can never
+   feed a diverging `β·u_p` source into the boundary row.
 2. **Drag + feedback** — gather the fluid velocity and ε at each particle, evaluate the drag law
    (Stokes / Schiller–Naumann / Ergun / Di Felice / Wen & Yu / Gidaspow), write the drag force to the
    particles and deposit the reaction onto the fluid momentum source.

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

@@ -16,8 +16,8 @@ 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.4.0"  CACHE STRING "Vendored core git tag (headers)")
-set(PECLET_MORTON_TAG "v0.2.0"  CACHE STRING "Vendored morton 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)
 
 # nanobind — found via the active interpreter (scikit-build-core supplies it as a build requirement),

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

@@ -16,7 +16,7 @@ build-backend = "scikit_build_core.build"
 
 [project]
 name = "peclet-coupling"
-version = "0.2.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.2.0 → peclet_coupling-0.4.0}/python/peclet_coupling/driver.py

@@ -25,10 +25,11 @@ def _sl(axis, idx):
 
 class CfdDem:
     def __init__(self, flow, dem, *, fluid_dt, mu, rho, radius, drag="schiller_naumann",
-                 dem_substeps=20, eps_min=0.4, periodic=(True, True, True), h=1.0,
-                 move_particles=True, implicit_drag=True, porous=False, advection=True):
+                 dem_substeps=20, eps_min=0.25, smooth_width=0.0, periodic=(True, True, True), h=1.0,
+                 move_particles=True, implicit_drag=True, porous=True, advection=True,
+                 gravity=(0.0, 0.0, 0.0)):
         from . import (_coupling, DRAG_STOKES, DRAG_SCHILLER_NAUMANN, DRAG_ERGUN, DRAG_DI_FELICE,
-                       DRAG_WEN_YU, DRAG_GIDASPOW)
+                       DRAG_WEN_YU, DRAG_GIDASPOW, DRAG_BEETSTRA, DRAG_TANG)
         self._c = _coupling
         self.flow = flow
         self.dem = dem
@@ -48,22 +49,53 @@ class CfdDem:
         self.fluid_dt = float(fluid_dt)
         self.dem_substeps = int(dem_substeps)
         self.dt_dem = self.fluid_dt / self.dem_substeps
-        # Void-fraction floor. Default 0.4 ~ the random-close-packing voidage: a physical packing
-        # cannot go below ~0.36, so deposits under the floor are local over-concentration of the
-        # trilinear/wall-aware scatter, and the Ergun-branch drag (beta ~ (1-eps)^2/eps...) explodes
-        # outside its validity range (a porous Model-B bed at eps_min=0.3 diverges; 0.4 is stable).
+        # Void-fraction floor (default 0.25): a PHYSICAL regularisation, not just a guard. Real
+        # voidage bottoms out near random close packing (~0.36 monodisperse, ~0.25 for wide bidisperse
+        # mixes); anything lower can only come from numerically interpenetrated particles or deposit
+        # artifacts, and must not reach the volume-averaged fluid — the eps-conservative projection
+        # legitimately amplifies the interstitial velocity by 1/eps, so junk eps -> junk gas. 0.25
+        # keeps the Ergun/drag fidelity over the physical range (the old 0.4 clamp under-predicted
+        # dense-bed drag ~3x; the interim 0.05 guard let interpenetration artifacts detonate a bed).
         self.eps_min = float(eps_min)
+        # Porosity smoothing length (grid cells), decoupled from the CFD cell size — MFIX's
+        # DES_DIFFUSE_WIDTH. 0 = off (plain trilinear deposit). For a coarse cell/dp bed set it ~1 cell
+        # (a few particle diameters) so the void fraction the drag sees is smooth and grid-independent;
+        # converted to `nsweeps` explicit diffusion sweeps (sigma = sqrt(2*alpha*nsweeps), alpha=1/6).
+        self.smooth_width = float(smooth_width)
+        # Volume-averaging validity: eps must be smooth over >~ the particle scale. With cells not
+        # much larger than d_p the raw trilinear deposit is not a proper volume filter — smooth it.
+        if np.isscalar(radius) and float(h) < 3.0 * (2.0 * float(radius)) \
+                and self.smooth_width * float(h) < 1.5 * (2.0 * float(radius)):
+            import warnings
+            warnings.warn(
+                f"CfdDem: cell size h={float(h):g} is < 3 particle diameters and smooth_width is "
+                f"below ~1.5 d_p — the deposited void fraction is not a proper volume average at "
+                f"this resolution. Set smooth_width so the smoothing length exceeds the particle "
+                f"diameter (e.g. smooth_width={1.5 * 2.0 * float(radius) / float(h):.1f}).")
+        self._smooth_alpha = 1.0 / 6.0
+        self._smooth_sweeps = (max(1, int(round(self.smooth_width ** 2 / (2.0 * self._smooth_alpha))))
+                               if self.smooth_width > 0.0 else 0)
         self.move_particles = bool(move_particles)  # False: fixed bed — skip DEM dynamics entirely
         self.implicit_drag = bool(implicit_drag)    # beta on the fluid diagonal (stable for stiff beds)
-        # Volume-averaged continuity d(eps)/dt+div(eps u)=0 (proper unresolved CFD-DEM). When off the
-        # fluid is solved incompressible (eps only in the drag) — cheaper, fine for dilute/steady beds.
+        # Volume-averaged continuity d(eps)/dt+div(eps u)=0 (proper unresolved CFD-DEM) — the DEFAULT:
+        # porosity must enter the volume-averaged Navier-Stokes equations, not just the drag closure.
+        # (MFIX-Exa likewise advects with the superficial velocity and projects div(eps u)=0; its
+        # d(eps)/dt constraint term is optional/"under development" — ours keeps it.) porous=False
+        # solves plain incompressible NS (eps only in the drag): a cheaper approximation for
+        # dilute/steady beds, not a faithful CFD-DEM.
         self.porous = bool(porous)
         self.h = float(h)
         self.inv_vcell = 1.0 / (self.h ** 3)
+        # Constant external acceleration dem applies per substep (its set_gravity vector; dem has
+        # no getter, so pass it here too). Feeds the stiff-safe drag cap's gravity-exact correction
+        # F -= m g (1 - beta_eff/beta), which restores the physical steady-state slip m g / beta.
+        self.gravity = tuple(float(c) for c in gravity)
         self.periodic = tuple(bool(p) for p in periodic)
         self.drag_kind = {"stokes": DRAG_STOKES, "schiller_naumann": DRAG_SCHILLER_NAUMANN,
                           "ergun": DRAG_ERGUN, "di_felice": DRAG_DI_FELICE,
-                          "wen_yu": DRAG_WEN_YU, "gidaspow": DRAG_GIDASPOW}[drag]
+                          "wen_yu": DRAG_WEN_YU, "gidaspow": DRAG_GIDASPOW,
+                          "beetstra": DRAG_BEETSTRA, "bvk": DRAG_BEETSTRA,
+                          "tang": DRAG_TANG, "bvk2": DRAG_TANG}[drag]
 
         nx, ny, nz = flow.get_resolution()  # LOCAL block dims under MPI
         self.g = flow.ghost_width()
@@ -87,6 +119,22 @@ class CfdDem:
         self._ox, self._oy, self._oz = bo[0] * self.h, bo[1] * self.h, bo[2] * self.h
         gnx, gny, gnz = flow.global_resolution() if self.mpi else (nx, ny, nz)
         self.gnx, self.gny, self.gnz = gnx, gny, gnz
+        # Smoothing under MPI: a local block face that is an INTERIOR rank boundary is not a wall —
+        # the diffusion sweep must read the halo ghost there (bit set), while faces on the GLOBAL
+        # domain boundary keep the validated single-rank zero-flux closed-box behaviour (bit clear,
+        # also on periodic axes, matching the single-rank path byte-for-byte). The sweep loop in
+        # update_void_fraction halo-refreshes solidvol before every sweep, so multi-rank smoothing
+        # reproduces the single-rank arithmetic exactly.
+        self._smooth_open = 0
+        if self.mpi:
+            lo = (bo[0], bo[1], bo[2])
+            dims = (nx, ny, nz)
+            gdims = (gnx, gny, gnz)
+            for a in range(3):
+                if lo[a] > 0:
+                    self._smooth_open |= 1 << (2 * a)
+                if lo[a] + dims[a] < gdims[a]:
+                    self._smooth_open |= 1 << (2 * a + 1)
         # The CURRENT shared decomposition, as an x-fastest per-cell weight field. Uniform => the
         # default equal-cell ORB flow's init_mpi built; rebalance() overwrites it. dem is migrated onto
         # this each moving step so its ownership tracks flow's grid partition (the deposit stays
@@ -106,6 +154,15 @@ class CfdDem:
             self._solidvol = xp.zeros((self.ex, self.ey, self.ez), dtype=xp.float64, order="F")
             self._eps = xp.ones((self.ex, self.ey, self.ez), dtype=xp.float64, order="F")
         if self.porous:
+            # The porous projection lives on the cut-cell pressure operator (eps-weighted
+            # coefficients ride the openness rails). A domain-BC-only box (no set_solid /
+            # set_pressure_geometry) has no such operator, and flow would silently solve plain
+            # div(u)=0 — the gas never accelerates to the interstitial velocity in the bed and the
+            # drag is far too weak to fluidize. Auto-install an all-fluid geometry in that case
+            # (flow's project() now also throws rather than silently degrade).
+            if hasattr(flow, "has_cutcell_pressure") and not flow.has_cutcell_pressure():
+                allfluid = np.full((self.nx, self.ny, self.nz), 1e6, dtype=np.float64)
+                flow.set_pressure_geometry(allfluid.flatten(order="F"))
             flow.set_porous_continuity(True)  # projection enforces d(eps)/dt + div(eps u) = 0
         # Gas convection ON by default: fully-implicit FOU operator + explicit deferred-correction
         # TVD (unconditionally stable at the large coupled dt on both the periodic and domain-BC
@@ -163,24 +220,68 @@ class CfdDem:
             vel = np.ascontiguousarray(self.dem.get_velocities(), dtype=np.float32)
         return pos, vel
 
-    # --- periodic ghost handling on a padded (ex,ey,ez) buffer -------------------------------
-    def _fold(self, f):  # deposits that landed one cell into the ghost wrap back to the inner edge
+    # --- ghost handling on a padded (ex,ey,ez) buffer ----------------------------------------
+    def _fold(self, f):
+        """Fold ghost-layer deposits back onto owned cells. Periodic axis: wrap to the opposite
+        inner edge. Non-periodic axis: fold into the SAME-side boundary cell — a grain resting on
+        the distributor scatters part of its volume (and drag beta / feedback) one layer below
+        z=0; dropping it would lose hold-up exactly where the bed is densest and leave the
+        deposit's leakage in ghosts the fluid reads."""
         g = self.g
         for a, (n, per) in enumerate(zip((self.nx, self.ny, self.nz), self.periodic)):
-            if not per:
-                continue
-            f[_sl(a, n + g - 1)] += f[_sl(a, g - 1)]
-            f[_sl(a, g)] += f[_sl(a, n + g)]
+            if per:
+                f[_sl(a, n + g - 1)] += f[_sl(a, g - 1)]
+                f[_sl(a, g)] += f[_sl(a, n + g)]
+            else:
+                f[_sl(a, g)] += f[_sl(a, g - 1)]
+                f[_sl(a, n + g - 1)] += f[_sl(a, n + g)]
             f[_sl(a, g - 1)] = 0.0
             f[_sl(a, n + g)] = 0.0
 
-    def _fill(self, f):  # fill the one ghost layer the gather stencil reads (periodic wrap)
+    def _fold_domain(self, f):
+        """MPI: same-side fold of the non-periodic GLOBAL-domain-boundary ghosts of the local
+        block (the reverse halo never touches them). Call BEFORE exchange_field_add."""
+        g = self.g
+        lo = (int(self._ox / self.h), int(self._oy / self.h), int(self._oz / self.h))
+        dims = (self.nx, self.ny, self.nz)
+        gdims = (self.gnx, self.gny, self.gnz)
+        for a in range(3):
+            if self.periodic[a]:
+                continue
+            if lo[a] == 0:
+                f[_sl(a, g)] += f[_sl(a, g - 1)]
+                f[_sl(a, g - 1)] = 0.0
+            if lo[a] + dims[a] == gdims[a]:
+                f[_sl(a, dims[a] + g - 1)] += f[_sl(a, dims[a] + g)]
+                f[_sl(a, dims[a] + g)] = 0.0
+
+    def _fill(self, f):
+        """Fill the one ghost layer the gather stencil reads: periodic wrap, or zero-gradient at a
+        non-periodic domain face (a grain near the floor must see the LOCAL bed eps/velocity, not
+        the deposit's stale ghost values)."""
         g = self.g
         for a, (n, per) in enumerate(zip((self.nx, self.ny, self.nz), self.periodic)):
-            if not per:
+            if per:
+                f[_sl(a, g - 1)] = f[_sl(a, n + g - 1)]
+                f[_sl(a, n + g)] = f[_sl(a, g)]
+            else:
+                f[_sl(a, g - 1)] = f[_sl(a, g)]
+                f[_sl(a, n + g)] = f[_sl(a, n + g - 1)]
+
+    def _fill_domain(self, f):
+        """MPI: zero-gradient fill of the non-periodic global-domain-boundary ghosts (the halo
+        fill never touches them). Call AFTER exchange_field."""
+        g = self.g
+        lo = (int(self._ox / self.h), int(self._oy / self.h), int(self._oz / self.h))
+        dims = (self.nx, self.ny, self.nz)
+        gdims = (self.gnx, self.gny, self.gnz)
+        for a in range(3):
+            if self.periodic[a]:
                 continue
-            f[_sl(a, g - 1)] = f[_sl(a, n + g - 1)]
-            f[_sl(a, n + g)] = f[_sl(a, g)]
+            if lo[a] == 0:
+                f[_sl(a, g - 1)] = f[_sl(a, g)]
+            if lo[a] + dims[a] == gdims[a]:
+                f[_sl(a, dims[a] + g)] = f[_sl(a, dims[a] + g - 1)]
 
     def update_void_fraction(self, pos):
         # deposit target: a registered flow field under MPI (so the halo folds ghost deposits + fills
@@ -194,14 +295,35 @@ class CfdDem:
             # With no geometry set sdf is all-zero -> every corner fluid -> plain trilinear deposit.
             self._c.deposit_solid_volume(pos, self._rad, sv, self._fv("sdf"), *self._gm())
         if self.mpi:
+            self._fold_domain(sv)  # non-periodic domain-boundary ghosts (halo never folds them)
             self.flow.exchange_field_add("solidvol")  # fold cross-rank + periodic ghost deposits
         else:
             self._fold(sv)
+        if self._smooth_sweeps:
+            # Diffusive smoothing of the deposited solid volume (MFIX DES_DIFFUSE_WIDTH): decouple the
+            # porosity smoothing length from the CFD cell so a coarse cell/dp bed sees a smooth,
+            # grid-independent void fraction. Volume-conserving (zero-flux at the global walls).
+            if self.mpi:
+                # Interior rank faces diffuse across the block boundary: refresh the halo before
+                # every Jacobi sweep so open faces read the neighbour's pre-sweep values — this
+                # reproduces the single-rank closed-box arithmetic exactly (global faces stay
+                # zero-flux, flux across rank faces is antisymmetric => volume conserved).
+                for _ in range(self._smooth_sweeps):
+                    self.flow.exchange_field("solidvol")
+                    self._c.smooth_solid_volume(sv, *self._gm(), 1, self._smooth_alpha,
+                                                self._smooth_open)
+            else:
+                self._c.smooth_solid_volume(sv, *self._gm(), self._smooth_sweeps, self._smooth_alpha)
         self._c.compute_void_fraction(sv, ep, self.inv_vcell, self.eps_min)
         if self.mpi:
             self.flow.exchange_field("eps")  # fill the ghosts the gather stencil reads
+            self._fill_domain(ep)
         else:
             self._fill(ep)
+        # Non-periodic ghost fills extrapolate and can leave eps outside [eps_min, 1] (observed
+        # 1.95 at a freeboard boundary); the porous coefficients and the gather stencil read those
+        # ghosts, so clamp the whole padded block to the physical range.
+        self.xp.clip(ep, self.eps_min, 1.0, out=ep)
         self._eps = ep  # compute_forces reads this at the particles
 
     def compute_forces(self, pos, vel):
@@ -213,19 +335,34 @@ class CfdDem:
         gm = self._gm()
         has_p = pos.shape[0] > 0  # a rank may own no particles under MPI (skip the per-particle
         db = self._fv("drag_beta") if self.implicit_drag else None  # kernels, keep the collectives)
+        # per-particle inverse mass (zero-copy dem view) for the stiff-safe exponential-integrator
+        # drag cap: beta_eff = (m/dt)(1 - exp(-beta dt/m)) — exact for linear drag over the coupling
+        # interval, unconditionally stable for any drag stiffness (the explicit per-substep force
+        # application otherwise blows up once beta*dt/m ~ 1).
+        im = self.xp.from_dlpack(self.dem.get_inv_mass_view()) if self.device \
+            else np.asarray(self.dem.get_inv_mass_view())
+        # The cap models the PARTICLE momentum update over the coupling interval; a fixed bed
+        # (move_particles=False) integrates no particles, so the cap must be off — dt_exch=0 makes
+        # effectiveBeta return the raw beta on both sides of the exchange. (This also guards against
+        # dem's set_positions (N,4) convention, which remaps w==0 to inv_mass=1: "fixed" bed
+        # particles otherwise look like unit-mass movers and the cap floors the dense-bed drag.)
+        dt_exch = self.fluid_dt if self.move_particles else 0.0
         # porous (volume-averaged, Model B: the fluid carries the full -grad p) converts the drag
         # closures beta_B = beta_A/eps inside the kernel (model_b flag); the incompressible mode
         # keeps the literature Model-A forms unchanged.
         if has_p and self.implicit_drag:
-            self._c.compute_drag_implicit(pos, vel, self._rad, uf, vf, wf, self._eps, sd, self._fdrag,
-                                          db, fx, fy, fz, *gm, self.mu, self.rho, self.inv_vcell,
-                                          self.drag_kind, self.porous)
+            self._c.compute_drag_implicit(pos, vel, self._rad, im, uf, vf, wf, self._eps, sd,
+                                          self._fdrag, db, fx, fy, fz, *gm, self.mu, self.rho,
+                                          self.inv_vcell, self.drag_kind, self.porous,
+                                          dt_exch, *self.gravity)
         elif has_p:
-            self._c.compute_drag_feedback(pos, vel, self._rad, uf, vf, wf, self._eps, sd, self._fdrag,
-                                          fx, fy, fz, *gm, self.mu, self.rho, self.inv_vcell,
-                                          self.drag_kind, self.porous)
+            self._c.compute_drag_feedback(pos, vel, self._rad, im, uf, vf, wf, self._eps, sd,
+                                          self._fdrag, fx, fy, fz, *gm, self.mu, self.rho,
+                                          self.inv_vcell, self.drag_kind, self.porous,
+                                          dt_exch, *self.gravity)
         if self.implicit_drag:
             if self.mpi:
+                self._fold_domain(db)
                 self.flow.exchange_field_add("drag_beta")
             else:
                 self._fold(db)
@@ -235,6 +372,7 @@ class CfdDem:
         # fold the reaction feedback (force_*) onto owners: reverse halo under MPI, periodic wrap else.
         for nm, f in (("force_x", fx), ("force_y", fy), ("force_z", fz)):
             if self.mpi:
+                self._fold_domain(f)
                 self.flow.exchange_field_add(nm)
             else:
                 self._fold(f)

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