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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: peclet-coupling
-Version: 0.2.0
+Version: 0.3.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.3.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.3.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.5.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.3.0}/pyproject.toml

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

@@ -14,8 +14,10 @@ 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_DI_FELICE", "DRAG_WEN_YU", "DRAG_GIDASPOW", "DRAG_BEETSTRA", "DRAG_TANG"]

{peclet_coupling-0.2.0 → peclet_coupling-0.3.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.2.0 → peclet_coupling-0.3.0}/src/coupling_bindings.cpp

@@ -84,6 +84,26 @@ NB_MODULE(_coupling, m) {
       "wall-aware: the hold-up is distributed over the fluid corners only (sdf>=0), reweighted to a "
       "partition of unity so no volume leaks into the solid. Fold ghosts before compute_void_fraction.");
 
+  m.def(
+      "smooth_solid_volume",
+      [](nb::ndarray<> solidvol, double ox, double oy, double oz, double h, int ex, int ey, int ez,
+         int g, int nsweeps, double alpha, int open_faces) {
+        auto sv = flatField(solidvol, "smooth_solid_volume(solidvol)");
+        Kokkos::View<double*, MemSpace> owner("peclet::coupling::smooth_tmp", sv.extent(0));
+        FlatV tmp(owner.data(), owner.extent(0));  // unmanaged alias: same View type as `sv`
+        peclet::coupling::smoothField(sv, tmp, gmap(ox, oy, oz, h, ex, ey, ez, g), nsweeps, alpha,
+                                      open_faces);
+      },
+      nb::arg("solidvol"), nb::arg("ox"), nb::arg("oy"), nb::arg("oz"), nb::arg("h"), nb::arg("ex"),
+      nb::arg("ey"), nb::arg("ez"), nb::arg("g"), nb::arg("nsweeps"), nb::arg("alpha") = 1.0 / 6.0,
+      nb::arg("open_faces") = 0,
+      "Volume-conserving diffusive smoothing of the deposited `solidvol` (MFIX DES_DIFFUSE_WIDTH "
+      "analog): nsweeps explicit diffusion sweeps => Gaussian sigma=sqrt(2*alpha*nsweeps) cells, "
+      "zero-flux at the domain boundary (conserves total solid volume). Call after folding ghosts, "
+      "before compute_void_fraction. `open_faces` (bit 2*axis / 2*axis+1 = minus/plus face): local "
+      "faces that are interior MPI rank boundaries read the halo ghost instead of zero-flux — "
+      "halo-fill before every sweep (nsweeps=1 per refresh).");
+
   m.def(
       "compute_void_fraction",
       [](nb::ndarray<> solidvol, nb::ndarray<> eps, double inv_vcell, double eps_min) {
@@ -113,10 +133,11 @@ NB_MODULE(_coupling, m) {
 
   m.def(
       "compute_drag_feedback",
-      [](nb::ndarray<> pos, nb::ndarray<> vel, nb::ndarray<> rad, nb::ndarray<> uf, nb::ndarray<> vf,
-         nb::ndarray<> wf, nb::ndarray<> eps, nb::ndarray<> sdf, nb::ndarray<> fdrag, nb::ndarray<> fx,
-         nb::ndarray<> fy, nb::ndarray<> fz, double ox, double oy, double oz, double h, int ex,
-         int ey, int ez, int g, double mu, double rho, double inv_vcell, int drag_kind, bool model_b) {
+      [](nb::ndarray<> pos, nb::ndarray<> vel, nb::ndarray<> rad, nb::ndarray<> inv_mass,
+         nb::ndarray<> uf, nb::ndarray<> vf, nb::ndarray<> wf, nb::ndarray<> eps, nb::ndarray<> sdf,
+         nb::ndarray<> fdrag, nb::ndarray<> fx, nb::ndarray<> fy, nb::ndarray<> fz, double ox,
+         double oy, double oz, double h, int ex, int ey, int ez, int g, double mu, double rho,
+         double inv_vcell, int drag_kind, bool model_b, double dt_exch, double gx, double gy, double gz) {
         const GridMap mp = gmap(ox, oy, oz, h, ex, ey, ez, g);
         auto Fx = flatField(fx, "fx"), Fy = flatField(fy, "fy"), Fz = flatField(fz, "fz");
         Kokkos::deep_copy(Fx, 0.0);
@@ -124,27 +145,29 @@ NB_MODULE(_coupling, m) {
         Kokkos::deep_copy(Fz, 0.0);
         peclet::coupling::computeDragFeedback(
             (int)pos.shape(0), vec3(pos, "pos"), vec3(vel, "vel"), vecf(rad, "rad"),
-            flatField(uf, "uf"), flatField(vf, "vf"), flatField(wf, "wf"), flatField(eps, "eps"),
-            flatField(sdf, "sdf"), vec3(fdrag, "fdrag"), Fx, Fy, Fz, mp, mu, rho, inv_vcell,
-            drag_kind, model_b);
+            vecf(inv_mass, "inv_mass"), flatField(uf, "uf"), flatField(vf, "vf"),
+            flatField(wf, "wf"), flatField(eps, "eps"), flatField(sdf, "sdf"), vec3(fdrag, "fdrag"),
+            Fx, Fy, Fz, mp, mu, rho, inv_vcell, drag_kind, model_b, dt_exch, gx, gy, gz);
       },
-      nb::arg("pos"), nb::arg("vel"), nb::arg("rad"), nb::arg("uf"), nb::arg("vf"), nb::arg("wf"),
+      nb::arg("pos"), nb::arg("vel"), nb::arg("rad"), nb::arg("inv_mass"), nb::arg("uf"),
+      nb::arg("vf"), nb::arg("wf"),
       nb::arg("eps"), nb::arg("sdf"), nb::arg("fdrag"), nb::arg("fx"), nb::arg("fy"), nb::arg("fz"),
       nb::arg("ox"), nb::arg("oy"), nb::arg("oz"), nb::arg("h"), nb::arg("ex"), nb::arg("ey"),
       nb::arg("ez"), nb::arg("g"), nb::arg("mu"), nb::arg("rho"), nb::arg("inv_vcell"),
-      nb::arg("drag_kind"), nb::arg("model_b") = false,
+      nb::arg("drag_kind"), nb::arg("model_b") = false, nb::arg("dt_exch") = 0.0, nb::arg("gx") = 0.0, nb::arg("gy") = 0.0, nb::arg("gz") = 0.0,
       "Gather (uf,vf,wf,eps) at each particle, evaluate the drag law (0 Stokes, 1 Schiller-Naumann, "
-      "2 Ergun, 3 Di Felice), write the drag force to `fdrag` (N,3) and the reaction force density "
+      "2 Ergun, 3 Di Felice, 4 Wen-Yu, 5 Gidaspow, 6 Beetstra/BVK), write the drag force to `fdrag` "
+      "(N,3) and the reaction force density "
       "-F/Vcell onto (fx,fy,fz) (zeroed here). Momentum-conserving. EXPLICIT feedback — use "
       "compute_drag_implicit for stiff (dense-bed) drag.");
 
   m.def(
       "compute_drag_implicit",
-      [](nb::ndarray<> pos, nb::ndarray<> vel, nb::ndarray<> rad, nb::ndarray<> uf, nb::ndarray<> vf,
-         nb::ndarray<> wf, nb::ndarray<> eps, nb::ndarray<> sdf, nb::ndarray<> fdrag,
-         nb::ndarray<> dragbeta, nb::ndarray<> fx, nb::ndarray<> fy, nb::ndarray<> fz, double ox,
-         double oy, double oz, double h, int ex, int ey, int ez, int g, double mu, double rho,
-         double inv_vcell, int drag_kind, bool model_b) {
+      [](nb::ndarray<> pos, nb::ndarray<> vel, nb::ndarray<> rad, nb::ndarray<> inv_mass,
+         nb::ndarray<> uf, nb::ndarray<> vf, nb::ndarray<> wf, nb::ndarray<> eps, nb::ndarray<> sdf,
+         nb::ndarray<> fdrag, nb::ndarray<> dragbeta, nb::ndarray<> fx, nb::ndarray<> fy,
+         nb::ndarray<> fz, double ox, double oy, double oz, double h, int ex, int ey, int ez, int g,
+         double mu, double rho, double inv_vcell, int drag_kind, bool model_b, double dt_exch, double gx, double gy, double gz) {
         const GridMap mp = gmap(ox, oy, oz, h, ex, ey, ez, g);
         auto Db = flatField(dragbeta, "drag_beta"), Fx = flatField(fx, "fx"),
              Fy = flatField(fy, "fy"), Fz = flatField(fz, "fz");
@@ -154,15 +177,18 @@ NB_MODULE(_coupling, m) {
         Kokkos::deep_copy(Fz, 0.0);
         peclet::coupling::computeDragImplicit(
             (int)pos.shape(0), vec3(pos, "pos"), vec3(vel, "vel"), vecf(rad, "rad"),
-            flatField(uf, "uf"), flatField(vf, "vf"), flatField(wf, "wf"), flatField(eps, "eps"),
+            vecf(inv_mass, "inv_mass"), flatField(uf, "uf"), flatField(vf, "vf"),
+            flatField(wf, "wf"), flatField(eps, "eps"),
             flatField(sdf, "sdf"), vec3(fdrag, "fdrag"), Db, Fx, Fy, Fz, mp, mu, rho, inv_vcell,
-            drag_kind, model_b);
+            drag_kind, model_b, dt_exch, gx, gy, gz);
       },
-      nb::arg("pos"), nb::arg("vel"), nb::arg("rad"), nb::arg("uf"), nb::arg("vf"), nb::arg("wf"),
+      nb::arg("pos"), nb::arg("vel"), nb::arg("rad"), nb::arg("inv_mass"), nb::arg("uf"),
+      nb::arg("vf"), nb::arg("wf"),
       nb::arg("eps"), nb::arg("sdf"), nb::arg("fdrag"), nb::arg("drag_beta"), nb::arg("fx"),
       nb::arg("fy"), nb::arg("fz"), nb::arg("ox"), nb::arg("oy"), nb::arg("oz"), nb::arg("h"),
       nb::arg("ex"), nb::arg("ey"), nb::arg("ez"), nb::arg("g"), nb::arg("mu"), nb::arg("rho"),
       nb::arg("inv_vcell"), nb::arg("drag_kind"), nb::arg("model_b") = false,
+      nb::arg("dt_exch") = 0.0, nb::arg("gx") = 0.0, nb::arg("gy") = 0.0, nb::arg("gz") = 0.0,
       "Implicit (semi-implicit) drag: writes `fdrag` (particle force) and deposits the linear-drag "
       "coefficient density onto `drag_beta` and the target beta*u_p onto (fx,fy,fz) (all zeroed "
       "here) for flow.enable_drag() to treat -beta*(u-u_p) implicitly. Stable for stiff beds.");

{peclet_coupling-0.2.0 → peclet_coupling-0.3.0}/src/coupling_kernels.hpp

@@ -21,6 +21,24 @@ namespace peclet::coupling {
 
 using peclet::core::interp::GridMap;
 
+// Is the particle's trilinear stencil within coupling range of the local block? axisStencil CLAMPS
+// out-of-range particles into the boundary cell, so a grain that has escaped the domain (e.g. pushed
+// through a DEM wall by a violent contact solve and now in free fall below the distributor) would
+// keep depositing its full volume and drag target (with a runaway u_p) into the boundary row forever
+// — a guaranteed gas blow-up. A particle is coupled iff its stencil overlaps [-1, n] (one ghost
+// layer, whose deposits the driver folds back onto the boundary cell); anything further out is
+// dropped from the exchange (no deposit, zero drag — ballistic until the DEM recovers it).
+KOKKOS_INLINE_FUNCTION bool axisInRange(double p, double origin, double inv, int nInner) {
+  const double si = (p - origin) * inv - 0.5;  // continuous cell-centre coordinate
+  return si > -2.0 && si < (double)nInner + 1.0;
+}
+template <class GM>
+KOKKOS_INLINE_FUNCTION bool stencilInRange(double px, double py, double pz, const GM& m, int nx,
+                                           int ny, int nz) {
+  return axisInRange(px, m.ox, m.idx, nx) && axisInRange(py, m.oy, m.idy, ny) &&
+         axisInRange(pz, m.oz, m.idz, nz);
+}
+
 // A stencil corner is a FLUID cell iff the (cell-centred) SDF there is >= 0 (SDF < 0 inside the
 // solid, per docs/CONVENTIONS.md). With no geometry set, flow's sdf field is all-zero -> every corner
 // reads as fluid -> the wall-aware paths below reduce EXACTLY to plain trilinear (the periodic no-wall
@@ -30,6 +48,25 @@ KOKKOS_INLINE_FUNCTION bool cornerIsFluid(const MaskV& sdf, long o) {
   return (double)sdf(o) >= 0.0;
 }
 
+// Stiff-safe (exponential-integrator) effective drag coefficient. The particle-side exchange applies
+// a CONSTANT force over the coupling interval dt (dem substeps accumulate it linearly), so the raw
+// linear coefficient beta is explicit there and blows up for beta*dt/m >~ 1 (measured: a coupled
+// fluidized bed doubling |v| per step once the eps-conservative projection raised the interstitial
+// velocities). The exact solution of m dv/dt = beta (u - v) over dt is reproduced by the constant
+// force F = beta_eff (u - v0) with
+//   beta_eff = (m/dt) (1 - exp(-beta dt / m))
+// — equal to beta for beta*dt/m << 1 and saturating at m/dt (v lands exactly ON u, never beyond):
+// unconditionally stable for any drag stiffness. Used for the particle force AND the fluid-side
+// deposits (beta / feedback), so the exchange stays momentum-conserving. invM <= 0 (static) => raw.
+KOKKOS_INLINE_FUNCTION double effectiveBeta(double beta, double invM, double dt) {
+  if (invM <= 0.0 || beta <= 0.0 || dt <= 0.0)
+    return beta;
+  const double x = beta * invM * dt;          // beta*dt/m
+  if (x < 1e-4)
+    return beta;                              // expm1 not needed; avoids 0/0 noise
+  return (1.0 - Kokkos::exp(-x)) / (invM * dt);
+}
+
 // Wall-aware trilinear gather: interpolate a cell-centred field at the particle using ONLY the fluid
 // corners, reweighted to a partition of unity (a solid corner carries no data — its velocity is the
 // no-slip 0 and its eps is meaningless — so including it biases the interpolant). Reduces to plain
@@ -96,6 +133,8 @@ void depositSolidVolume(int np, PosV pos, RadV rad, FieldV solidvol, FieldV sdf,
   const int nx = m.ex - 2 * m.g, ny = m.ey - 2 * m.g, nz = m.ez - 2 * m.g;
   Kokkos::parallel_for(
       "peclet::coupling::deposit_vol", Kokkos::RangePolicy<Exec>(0, np), KOKKOS_LAMBDA(int p) {
+        if (!stencilInRange((double)pos(p, 0), (double)pos(p, 1), (double)pos(p, 2), m, nx, ny, nz))
+          return;  // escaped the domain: no deposit (axisStencil would clamp it into the boundary)
         int i0, j0, k0;
         double wx, wy, wz;
         peclet::core::interp::detail::axisStencil((double)pos(p, 0), m.ox, m.idx, nx, i0, wx);
@@ -110,7 +149,62 @@ void depositSolidVolume(int np, PosV pos, RadV rad, FieldV solidvol, FieldV sdf,
       });
 }
 
-// eps = clamp(1 - solidvol/Vcell, epsMin, 1) over the whole (padded) field.
+// Volume-conserving diffusive smoothing of a deposited field (the MFIX DES_DIFFUSE_WIDTH analog).
+// `nsweeps` explicit Jacobi diffusion sweeps with per-neighbour coefficient `alpha` (<= 1/6 for 3D
+// stability) spread each particle's deposited volume over a Gaussian of length sigma = sqrt(2*alpha*
+// nsweeps) cells, DECOUPLING the porosity smoothing length from the CFD cell size — the fix a coarse
+// cell/dp bed needs for a smooth, grid-independent void fraction (MFIX-Exa: "smoothing of the fields
+// is crucial to achieve grid-independent results"). Zero-flux (Neumann) at the inner-domain boundary
+// so nothing diffuses out through the distributor/walls and the total solid volume is conserved
+// exactly (the discrete zero-flux Laplacian sums to zero over the inner cells). Ping-pongs between
+// `f` and scratch `tmp` (same padded size); the result is left in `f`. With `openFaces == 0` ghost
+// cells are never read (neighbours outside the inner domain contribute the cell's own value => zero
+// flux), so the caller's ghost fill after this is unaffected. Under MPI a local block face that is an
+// INTERIOR rank boundary is not a wall: setting its bit in `openFaces` (bit 2*axis = minus face,
+// bit 2*axis+1 = plus face) makes the sweep read the first ghost layer there instead — the caller
+// must halo-fill `f` before EVERY sweep (call with nsweeps=1 per refresh; the sweep is Jacobi, so a
+// per-sweep refresh reproduces the single-rank closed-box arithmetic bit-for-bit; flux out of one
+// block equals flux into its neighbour, so global volume conservation is preserved). Faces on the
+// GLOBAL domain boundary stay closed (bit clear) to match the validated single-rank behaviour.
+// NOTE: smooths across immersed-solid cells too — fine for the walled beds here (no inner SDF); an
+// SDF-masked variant is a follow-up.
+template <class FieldV>
+void smoothField(FieldV f, FieldV tmp, GridMap m, int nsweeps, double alpha, int openFaces = 0) {
+  using Exec = Kokkos::DefaultExecutionSpace;
+  const int nx = m.ex - 2 * m.g, ny = m.ey - 2 * m.g, nz = m.ez - 2 * m.g, g = m.g;
+  const long sx = 1, sy = m.ex, sz = (long)m.ex * m.ey;
+  const bool oxm = openFaces & 1, oxp = openFaces & 2, oym = openFaces & 4, oyp = openFaces & 8,
+             ozm = openFaces & 16, ozp = openFaces & 32;
+  Kokkos::deep_copy(tmp, f);  // seed ghosts so an odd-count final copy-back preserves f's ghost
+                              // cells (and so open faces read current ghosts from either buffer)
+  for (int s = 0; s < nsweeps; ++s) {
+    FieldV src = (s % 2 == 0) ? f : tmp;
+    FieldV dst = (s % 2 == 0) ? tmp : f;
+    Kokkos::parallel_for(
+        "peclet::coupling::smooth",
+        Kokkos::MDRangePolicy<Exec, Kokkos::Rank<3>>({0, 0, 0}, {nx, ny, nz}),
+        KOKKOS_LAMBDA(int ix, int iy, int iz) {
+          const long c = (long)(ix + g) + (long)(iy + g) * sy + (long)(iz + g) * sz;
+          const double v = (double)src(c);
+          double lap = 0.0;  // zero-flux: an out-of-domain neighbour contributes v (no gradient),
+                             // unless that face is an open (rank-boundary) face — then read the ghost
+          lap += (ix > 0 || oxm ? (double)src(c - sx) : v) - v;
+          lap += (ix < nx - 1 || oxp ? (double)src(c + sx) : v) - v;
+          lap += (iy > 0 || oym ? (double)src(c - sy) : v) - v;
+          lap += (iy < ny - 1 || oyp ? (double)src(c + sy) : v) - v;
+          lap += (iz > 0 || ozm ? (double)src(c - sz) : v) - v;
+          lap += (iz < nz - 1 || ozp ? (double)src(c + sz) : v) - v;
+          dst(c) = (typename FieldV::value_type)(v + alpha * lap);
+        });
+  }
+  if (nsweeps % 2 == 1)
+    Kokkos::deep_copy(f, tmp);  // odd sweep count left the result in tmp
+}
+
+// eps = clamp(1 - solidvol/Vcell, epsMin, 1) over the whole (padded) field. With smoothing on and a
+// small epsMin, epsMin is only a divide-by-zero guard; the physical void fraction (which can fall
+// well below the random-close-packing 0.4 in a dense cell) is preserved instead of being clamped up —
+// clamping ε up to 0.4 under-predicts the Ergun 1/ε^3 drag ~3x in a dense bed and it never fluidizes.
 template <class FieldV>
 void voidFraction(FieldV solidvol, FieldV eps, double invVcell, double epsMin) {
   using Exec = Kokkos::DefaultExecutionSpace;
@@ -129,15 +223,19 @@ void voidFraction(FieldV solidvol, FieldV eps, double invVcell, double epsMin) {
 // Fused drag + feedback. Gathers (uf,vf,wf,eps) at each particle, evaluates the drag law, writes the
 // drag force to fdrag(p,:) (dem external force), and scatters the reaction -F*invVcell onto the
 // (pre-zeroed) grid force-density fields fx,fy,fz. rho/mu physical; dragKind per drag.hpp.
-template <class PosV, class VelV, class RadV, class FieldV, class OutV>
-void computeDragFeedback(int np, PosV pos, VelV vel, RadV rad, FieldV uf, FieldV vf, FieldV wf,
-                         FieldV eps, FieldV sdf, OutV fdrag, FieldV fx, FieldV fy, FieldV fz,
-                         GridMap m, double mu, double rhof, double invVcell, int dragKind,
-                         bool modelB) {
+template <class PosV, class VelV, class RadV, class InvMV, class FieldV, class OutV>
+void computeDragFeedback(int np, PosV pos, VelV vel, RadV rad, InvMV invMass, FieldV uf, FieldV vf,
+                         FieldV wf, FieldV eps, FieldV sdf, OutV fdrag, FieldV fx, FieldV fy,
+                         FieldV fz, GridMap m, double mu, double rhof, double invVcell, int dragKind,
+                         bool modelB, double dtExch, double gx, double gy, double gz) {
   using Exec = Kokkos::DefaultExecutionSpace;
   const int nx = m.ex - 2 * m.g, ny = m.ey - 2 * m.g, nz = m.ez - 2 * m.g;
   Kokkos::parallel_for(
       "peclet::coupling::drag_feedback", Kokkos::RangePolicy<Exec>(0, np), KOKKOS_LAMBDA(int p) {
+        if (!stencilInRange((double)pos(p, 0), (double)pos(p, 1), (double)pos(p, 2), m, nx, ny, nz)) {
+          fdrag(p, 0) = fdrag(p, 1) = fdrag(p, 2) = 0;  // escaped: ballistic, no exchange
+          return;
+        }
         int i0, j0, k0;
         double wx, wy, wz;
         peclet::core::interp::detail::axisStencil((double)pos(p, 0), m.ox, m.idx, nx, i0, wx);
@@ -160,6 +258,35 @@ void computeDragFeedback(int np, PosV pos, VelV vel, RadV rad, FieldV uf, FieldV
           Fy /= eP;
           Fz /= eP;
         }
+        // Stiff-safe cap + gravity-exact correction. The constant force reproducing the exact
+        // endpoint of m dv/dt = beta (u - v) + m g over dtExch is
+        //   F = beta_eff (u - v0) - m g (1 - beta_eff/beta)
+        // — without the g term the discrete steady state balances at slip = m g / beta_eff (biased
+        // by the cap factor, measured 26% on the Stokes terminal-velocity test); with it the fixed
+        // point is the physical slip = m g / beta. F*dt stays the exact drag impulse, so the fluid
+        // reaction (-F) remains exactly momentum-conserving. g is the constant external
+        // acceleration dem applies per substep (gravity); invM<=0 or dtExch<=0 => raw beta, no
+        // correction.
+        {
+          const double vmag2 = vrx * vrx + vry * vry + vrz * vrz;
+          if (vmag2 > 1e-60) {
+            const double vmag = Kokkos::sqrt(vmag2);
+            const double bon = Kokkos::sqrt(Fx * Fx + Fy * Fy + Fz * Fz) / vmag;
+            const double invM = (double)invMass(p);
+            if (bon > 0.0) {
+              const double sc = effectiveBeta(bon, invM, dtExch) / bon;
+              Fx *= sc;
+              Fy *= sc;
+              Fz *= sc;
+              if (invM > 0.0 && sc < 1.0) {
+                const double corr = (1.0 - sc) / invM;  // m (1 - beta_eff/beta)
+                Fx -= corr * gx;
+                Fy -= corr * gy;
+                Fz -= corr * gz;
+              }
+            }
+          }
+        }
         fdrag(p, 0) = (typename OutV::value_type)Fx;
         fdrag(p, 1) = (typename OutV::value_type)Fy;
         fdrag(p, 2) = (typename OutV::value_type)Fz;
@@ -175,15 +302,20 @@ void computeDragFeedback(int np, PosV pos, VelV vel, RadV rad, FieldV uf, FieldV
 // treats -beta*(u - u_p) implicitly (unconditionally stable for a stiff bed). The particle drag
 // force (evaluated at the current slip) still goes to `fdrag` (explicit on the particle side).
 // beta_over_n = |F_p| / |vrel|, recovered from the drag law by a unit-slip evaluation.
-template <class PosV, class VelV, class RadV, class FieldV, class OutV>
-void computeDragImplicit(int np, PosV pos, VelV vel, RadV rad, FieldV uf, FieldV vf, FieldV wf,
-                         FieldV eps, FieldV sdf, OutV fdrag, FieldV dragBeta, FieldV fx, FieldV fy,
-                         FieldV fz, GridMap m, double mu, double rhof, double invVcell, int dragKind,
-                         bool modelB) {
+template <class PosV, class VelV, class RadV, class InvMV, class FieldV, class OutV>
+void computeDragImplicit(int np, PosV pos, VelV vel, RadV rad, InvMV invMass, FieldV uf, FieldV vf,
+                         FieldV wf, FieldV eps, FieldV sdf, OutV fdrag, FieldV dragBeta, FieldV fx,
+                         FieldV fy, FieldV fz, GridMap m, double mu, double rhof, double invVcell,
+                         int dragKind, bool modelB, double dtExch, double gx, double gy,
+                         double gz) {
   using Exec = Kokkos::DefaultExecutionSpace;
   const int nx = m.ex - 2 * m.g, ny = m.ey - 2 * m.g, nz = m.ez - 2 * m.g;
   Kokkos::parallel_for(
       "peclet::coupling::drag_implicit", Kokkos::RangePolicy<Exec>(0, np), KOKKOS_LAMBDA(int p) {
+        if (!stencilInRange((double)pos(p, 0), (double)pos(p, 1), (double)pos(p, 2), m, nx, ny, nz)) {
+          fdrag(p, 0) = fdrag(p, 1) = fdrag(p, 2) = 0;  // escaped: ballistic, no exchange
+          return;
+        }
         int i0, j0, k0;
         double wx, wy, wz;
         peclet::core::interp::detail::axisStencil((double)pos(p, 0), m.ox, m.idx, nx, i0, wx);
@@ -205,17 +337,39 @@ void computeDragImplicit(int np, PosV pos, VelV vel, RadV rad, FieldV uf, FieldV
           Fy /= eP;
           Fz /= eP;
         }
+        // beta_over_n = |F|/|vrel| (isotropic linear coefficient at the frozen slip), then the
+        // stiff-safe exponential-integrator cap (effectiveBeta) — used consistently for the
+        // particle force AND the fluid-side deposits so the exchange conserves momentum. The
+        // gravity-exact correction -m g (1 - beta_eff/beta) (see computeDragFeedback) rides the
+        // particle force, and its reaction is deposited as a constant term with the drag target.
+        const double vmag = Kokkos::sqrt(vrx * vrx + vry * vry + vrz * vrz);
+        const double Fmag = Kokkos::sqrt(Fx * Fx + Fy * Fy + Fz * Fz);
+        const double bonRaw = (vmag > 1e-30) ? Fmag / vmag : 0.0;
+        const double bon = effectiveBeta(bonRaw, (double)invMass(p), dtExch);
+        double cgx = 0.0, cgy = 0.0, cgz = 0.0;  // m (1 - beta_eff/beta) * g
+        if (bonRaw > 0.0) {
+          const double sc = bon / bonRaw;
+          Fx *= sc;
+          Fy *= sc;
+          Fz *= sc;
+          const double invM = (double)invMass(p);
+          if (invM > 0.0 && sc < 1.0) {
+            const double corr = (1.0 - sc) / invM;
+            cgx = corr * gx;
+            cgy = corr * gy;
+            cgz = corr * gz;
+            Fx -= cgx;
+            Fy -= cgy;
+            Fz -= cgz;
+          }
+        }
         fdrag(p, 0) = (typename OutV::value_type)Fx;
         fdrag(p, 1) = (typename OutV::value_type)Fy;
         fdrag(p, 2) = (typename OutV::value_type)Fz;
-        // beta_over_n = |F|/|vrel| (isotropic linear coefficient at the frozen slip)
-        const double vmag = Kokkos::sqrt(vrx * vrx + vry * vry + vrz * vrz);
-        const double Fmag = Kokkos::sqrt(Fx * Fx + Fy * Fy + Fz * Fz);
-        const double bon = (vmag > 1e-30) ? Fmag / vmag : 0.0;
         scatterAtMasked(dragBeta, sdf, b, sx, sy, sz, wx, wy, wz, bon * invVcell);
-        scatterAtMasked(fx, sdf, b, sx, sy, sz, wx, wy, wz, bon * upx * invVcell);
-        scatterAtMasked(fy, sdf, b, sx, sy, sz, wx, wy, wz, bon * upy * invVcell);
-        scatterAtMasked(fz, sdf, b, sx, sy, sz, wx, wy, wz, bon * upz * invVcell);
+        scatterAtMasked(fx, sdf, b, sx, sy, sz, wx, wy, wz, (bon * upx + cgx) * invVcell);
+        scatterAtMasked(fy, sdf, b, sx, sy, sz, wx, wy, wz, (bon * upy + cgy) * invVcell);
+        scatterAtMasked(fz, sdf, b, sx, sy, sz, wx, wy, wz, (bon * upz + cgz) * invVcell);
       });
 }
 

{peclet_coupling-0.2.0 → peclet_coupling-0.3.0}/src/drag.hpp

@@ -25,7 +25,10 @@ enum DragKind {
   ERGUN = 2,
   DI_FELICE = 3,
   WEN_YU = 4,
-  GIDASPOW = 5
+  GIDASPOW = 5,
+  BEETSTRA = 6,  // Beetstra-van der Hoef-Kuipers DNS drag (the published "BVK2")
+  TANG = 7       // Tang-Peters-Kuipers-Kriebitzsch-van der Hoef (2015) — what MFIX-Exa's
+                 // "BVK2" option ACTUALLY executes (the Beetstra branch is #if 0'd out)
 };
 
 // Wen & Yu interphase drag coefficient per particle, F = beta_over_n * vrel. The dilute branch of
@@ -75,6 +78,38 @@ KOKKOS_INLINE_FUNCTION void dragForce(int kind, double vx, double vy, double vz,
     beta_over_n = 6.0 * M_PI * mu * r * corr * Kokkos::pow(eps, -(chi - 1.0));
   } else if (kind == WEN_YU) {
     beta_over_n = wenYuBetaOverN(vmag, d, mu, rhof, eps, Vp);
+  } else if (kind == BEETSTRA) {
+    // Beetstra, van der Hoef & Kuipers (AIChE J 53, 489, 2007) monodisperse DNS drag — the "BVK2"
+    // law of MFIX(-Exa). Dimensionless drag F(phi,Re) normalized by the Stokes force 3 pi mu d u on
+    // an isolated sphere; per-particle F = 3 pi mu d eps F(phi,Re) vrel (the extra eps is the
+    // MFIX/TFM interstitial-slip convention: beta = 18 mu eps phi F / d^2, beta_over_n = beta Vp/phi).
+    // Re is the voidage (superficial) particle Reynolds number. F -> 1 as phi -> 0, Re -> 0.
+    const double phi = 1.0 - eps;
+    const double Re = eps * rhof * d * vmag / mu;
+    const double e2 = eps * eps;
+    double F = 10.0 * phi / e2 + e2 * (1.0 + 1.5 * Kokkos::sqrt(phi));
+    if (Re > 1e-12) {
+      F += 0.413 * Re / (24.0 * e2) *
+           (1.0 / eps + 3.0 * eps * phi + 8.4 * Kokkos::pow(Re, -0.343)) /
+           (1.0 + Kokkos::pow(10.0, 3.0 * phi) * Kokkos::pow(Re, -0.5 * (1.0 + 4.0 * phi)));
+    }
+    beta_over_n = 3.0 * M_PI * mu * d * eps * F;
+  } else if (kind == TANG) {
+    // Tang, Peters, Kuipers, Kriebitzsch & van der Hoef (AIChE J 61, 688, 2015) monodisperse DNS
+    // drag — the correlation MFIX-Exa's "BVK2" drag option actually executes (verified against
+    // mfix_des_drag_K.H: the Beetstra 2007 branch there is compiled out). Same static part as
+    // Beetstra; the inertial part is ~15% stronger for Re ~ 2-20. Same normalization + Re as BVK:
+    // per-particle F = 3 pi mu d eps F(phi,Re) vrel, Re the voidage particle Reynolds number.
+    const double phi = 1.0 - eps;
+    const double Re = eps * rhof * d * vmag / mu;
+    const double e2 = eps * eps;
+    const double inv_e4 = 1.0 / (e2 * e2);
+    double F = 10.0 * phi / e2 + e2 * (1.0 + 1.5 * Kokkos::sqrt(phi));
+    if (Re > 1e-12) {
+      F += Re * (0.11 * phi * (1.0 + phi) - 4.56e-3 * inv_e4 +
+                 Kokkos::pow(Re, -0.343) * (0.169 * eps + 6.44e-2 * inv_e4));
+    }
+    beta_over_n = 3.0 * M_PI * mu * d * eps * F;
   } else if (kind == GIDASPOW) {
     // Gidaspow (1994): Ergun for the dense regime, Wen & Yu for the dilute, switched at eps = 0.8.
     beta_over_n = (eps < 0.8) ? ergunBetaOverN(vmag, d, mu, rhof, eps, Vp)

{peclet_coupling-0.2.0 → peclet_coupling-0.3.0}/tests/test_fixed_bed_ergun.py

@@ -48,7 +48,7 @@ def run_bed(f_drive, eps_target=0.6, N=16, mu=1.0, rho=1.0, dt=0.5, steps=120):
     d.enable_periodicity(True, True, True)
     d.set_positions(posw)
     d.set_velocities(np.zeros((Np, 3), dtype=np.float32))
-    cpl = CfdDem(s, d, fluid_dt=dt, mu=mu, rho=rho, radius=r, drag="ergun", eps_min=0.05,
+    cpl = CfdDem(s, d, fluid_dt=dt, mu=mu, rho=rho, radius=r, drag="ergun", eps_min=0.05, porous=False,
                  move_particles=False)  # fixed bed: no DEM dynamics
     for _ in range(steps):
         cpl.step()

{peclet_coupling-0.2.0 → peclet_coupling-0.3.0}/tests/test_mpi_fixed_bed_ergun.py

@@ -56,7 +56,7 @@ def run_bed(f_drive, comm, eps_target=0.6, N=16, mu=1.0, rho=1.0, dt=0.5, steps=
     d.set_positions(posw)
     d.set_velocities(np.zeros((Np, 3), dtype=np.float32))
 
-    cpl = CfdDem(s, d, fluid_dt=dt, mu=mu, rho=rho, radius=r, drag="ergun", eps_min=0.05,
+    cpl = CfdDem(s, d, fluid_dt=dt, mu=mu, rho=rho, radius=r, drag="ergun", eps_min=0.05, porous=False,
                  move_particles=False)
     for _ in range(steps):
         cpl.step()

peclet_coupling-0.3.0/tests/test_mpi_smoothing.py

@@ -0,0 +1,114 @@
+"""Multi-rank void-fraction SMOOTHING: distributed diffusive smoothing must reproduce the
+single-rank result exactly.
+
+The MFIX-style diffusive smoothing (smooth_width) was single-rank-only: the sweep treated every
+local block face as a zero-flux wall, so a rank boundary acted as a spurious internal wall. Now
+interior rank faces read the halo ghost (open_faces mask) and the driver refreshes the solidvol
+halo before every Jacobi sweep, which makes the multi-rank sweep arithmetic identical to the
+single-rank closed-box sweep (global faces stay zero-flux, matching the validated single-rank
+path byte-for-byte).
+
+This test deposits a deterministic particle cloud, smooths, and checks:
+  1. global solid-volume conservation (smoothing must not create/destroy hold-up), and
+  2. the gathered global eps field matches the np=1 reference to ~machine precision.
+
+Run:  mpirun -np 1 python test_mpi_smoothing.py   (writes the reference)
+      mpirun -np {2,4} python test_mpi_smoothing.py
+"""
+import os
+import numpy as np
+import peclet.flow
+import peclet.dem
+from peclet.coupling import CfdDem
+from mpi4py import MPI
+
+REF_FILE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "smoothing_ref_eps.npy")
+N = 16          # global grid N^3, h = 1
+R = 0.3         # particle radius
+SMOOTH_W = 2.0  # smoothing length in cells
+EPS_MIN = 0.05
+
+
+def global_particles():
+    rng = np.random.default_rng(42)
+    # keep a margin off the domain faces so the trilinear deposit never lands in a non-periodic
+    # corner case; the box is fully periodic anyway.
+    return (rng.uniform(0.5, N - 0.5, size=(200, 3))).astype(np.float32)
+
+
+def run(comm):
+    rank, size = comm.Get_rank(), comm.Get_size()
+    gpos = global_particles()
+
+    if size > 1:
+        (ox, oy, oz), (lnx, lny, lnz) = peclet.flow.mpi_block(N, N, N)
+    else:
+        (ox, oy, oz), (lnx, lny, lnz) = (0, 0, 0), (N, N, N)
+    cell = np.floor(gpos).astype(int)
+    keep = ((cell[:, 0] >= ox) & (cell[:, 0] < ox + lnx) &
+            (cell[:, 1] >= oy) & (cell[:, 1] < oy + lny) &
+            (cell[:, 2] >= oz) & (cell[:, 2] < oz + lnz))
+    mine = gpos[keep]
+    Np = mine.shape[0]
+
+    s = peclet.flow.Solver(lnx, lny, lnz)
+    s.set_rho(1.0); s.set_mu(1.0); s.set_dt(0.1)
+    if size > 1:
+        s.init_mpi(N, N, N)
+    s.set_pressure_geometry(np.asfortranarray(np.full((lnx, lny, lnz), 10.0)))
+
+    d = peclet.dem.Simulation(max(Np, 1))
+    d.initialize(shape_type=1, radius=R)
+    d.set_domain((0, 0, 0), (N, N, N))
+    d.enable_periodicity(True, True, True)
+    posw = np.concatenate([mine, np.zeros((Np, 1), dtype=np.float32)], axis=1)  # invMass 0: fixed
+    d.set_positions(posw)
+    d.set_velocities(np.zeros((Np, 3), dtype=np.float32))
+
+    cpl = CfdDem(s, d, fluid_dt=0.1, mu=1.0, rho=1.0, radius=R, drag="stokes",
+                 eps_min=EPS_MIN, smooth_width=SMOOTH_W, move_particles=False)
+    assert cpl._smooth_sweeps > 0, "smoothing must be active under MPI now"
+    cpl._resize_particles(Np)
+    cpl.update_void_fraction(cpl.xp.asarray(mine))
+
+    g = cpl.g
+    sv = cpl._fv("solidvol") if cpl._eps_is_field else cpl._solidvol
+    ep = cpl._eps
+    if cpl.device:
+        sv, ep = sv.get(), ep.get()
+    sv_in = np.asarray(sv)[g:g + lnx, g:g + lny, g:g + lnz]
+    ep_in = np.asarray(ep)[g:g + lnx, g:g + lny, g:g + lnz]
+
+    # 1) conservation: smoothing must preserve the total deposited solid volume.
+    vol = comm.allreduce(float(sv_in.sum()), op=MPI.SUM)
+    r32 = float(np.float32(R))  # the kernel deposits with the float32-cast radius
+    vol_exact = gpos.shape[0] * (4.0 / 3.0) * np.pi * r32 ** 3
+    cons_err = abs(vol - vol_exact) / vol_exact
+
+    # 2) gather the global eps and compare with the np=1 reference.
+    blocks = comm.gather(((ox, oy, oz), np.ascontiguousarray(ep_in)), root=0)
+    ok = cons_err < 1e-12
+    if rank == 0:
+        geps = np.zeros((N, N, N))
+        for (bx, by, bz), b in blocks:
+            geps[bx:bx + b.shape[0], by:by + b.shape[1], bz:bz + b.shape[2]] = b
+        if size == 1:
+            np.save(REF_FILE, geps)
+            tag = "reference written"
+        elif os.path.exists(REF_FILE):
+            ref = np.load(REF_FILE)
+            err = float(np.max(np.abs(geps - ref)))
+            ok = ok and err < 1e-12
+            tag = f"vs np=1 max|deps|={err:.3e}"
+        else:
+            tag = "NO REFERENCE (run np=1 first)"
+            ok = False
+        print(f"[np={size}] conservation rel-err={cons_err:.3e}  {tag}")
+        print(f"MPI SMOOTHING (np={size}): {'PASS' if ok else 'FAIL'}")
+    ok = comm.bcast(ok if rank == 0 else None, root=0)
+    if not ok:
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    run(MPI.COMM_WORLD)

{peclet_coupling-0.2.0 → peclet_coupling-0.3.0}/tests/test_terminal_velocity.py

@@ -27,7 +27,8 @@ def terminal(drag, g=1e-3, r=1.0, mu=1.0, rho_p=1.0, rho_f=1.0, N=32, steps=120)
     d.set_gravity(0, 0, -g)  # acceleration
     d.set_positions(np.array([[N / 2, N / 2, N / 2, 1.0 / m_p]], dtype=np.float32))  # w = invMass
     d.set_velocities(np.zeros((1, 3), dtype=np.float32))
-    cpl = CfdDem(s, d, fluid_dt=0.1, mu=mu, rho=rho_f, radius=r, drag=drag, dem_substeps=10)
+    cpl = CfdDem(s, d, fluid_dt=0.1, mu=mu, rho=rho_f, radius=r, drag=drag, dem_substeps=10,
+                 porous=False, gravity=(0, 0, -g))
     slip_hist = []
     for _ in range(steps):
         cpl.step()