peclet-coupling 0.2.0__tar.gz

peclet_coupling-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,41 @@
+name: Release
+
+# Publish peclet-coupling to PyPI on a version tag via Trusted Publishing (OIDC) — configure the
+# publisher on PyPI first (environment: pypi); no API token secret needed. SDIST ONLY: the coupling
+# kernels are Kokkos device code built from source against the consumer's backend (like peclet-core),
+# so a portable binary wheel is not meaningful. Consumers `pip install peclet-coupling` (or
+# `peclet[cfd-dem]`) and build against a Kokkos prefix, or use the suite containers.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build --sdist
+      - uses: actions/upload-artifact@v7
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  publish:
+    needs: [sdist]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      id-token: write   # required for trusted publishing
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1

peclet_coupling-0.2.0/.gitignore

@@ -0,0 +1,4 @@
+build*/
+__pycache__/
+*.so
+tests/.moving_ref.json

peclet_coupling-0.2.0/CMakeLists.txt

@@ -0,0 +1,56 @@
+cmake_minimum_required(VERSION 3.24)
+project(peclet_coupling LANGUAGES CXX)
+
+# peclet.coupling -- CFD-DEM exchange kernels (particle<->grid deposition, drag, momentum feedback)
+# as an importable Python module. Physics-free glue: the Python CfdDem driver (python/peclet_coupling)
+# composes peclet.flow + peclet.dem, and this module runs the kernels in place on the arrays they
+# expose. Header-only compute (core interp primitive + drag laws), Kokkos backend from the install
+# prefix (extern/install/<backend>), nanobind via the shared SuiteNanobind helper.
+#
+#   cmake -S . -B build -DCMAKE_PREFIX_PATH="$PWD/../extern/install/host-openmp"
+#   cmake --build build -j        ->  build/peclet/coupling/_coupling.*.so
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+if(NOT CMAKE_BUILD_TYPE)
+  set(CMAKE_BUILD_TYPE Release CACHE STRING "" FORCE)
+endif()
+
+# Dependencies via the vendored PecletDeps helper: an installed Kokkos prefix + sibling checkout for
+# the dev/suite build, or FetchContent-built Kokkos + fetched core headers (v-pinned) for a
+# self-contained sdist build (`pip install peclet-coupling`). See cmake/PecletDeps.cmake.
+list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
+include(PecletDeps)
+peclet_require_kokkos()
+peclet_require_nanobind()
+peclet_sibling_include(peclet-core "${PECLET_TPX_TAG}" "../core" CORE_INC)
+
+nanobind_add_module(coupling NB_STATIC NOMINSIZE src/coupling_bindings.cpp)
+set_target_properties(coupling PROPERTIES OUTPUT_NAME _coupling  # -> peclet.coupling._coupling
+  LIBRARY_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/peclet/coupling")
+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)
+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)
+endif()
+
+option(PECLET_COUPLING_TESTS "Register the Python CFD-DEM integration tests as ctests" OFF)
+if(PECLET_COUPLING_TESTS)
+  enable_testing()
+  add_subdirectory(tests)
+endif()
+
+# --- pip / scikit-build-core install rule --------------------------------------------------------
+# Places the extension + the peclet/coupling package (__init__.py + driver.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
+          DESTINATION peclet/coupling COMPONENT python)
+endif()

peclet_coupling-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frank Peters
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

peclet_coupling-0.2.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: peclet-coupling
+Version: 0.2.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
+License-File: LICENSE
+Project-URL: Homepage, https://github.com/computational-chemical-engineering/peclet
+Project-URL: Documentation, https://github.com/computational-chemical-engineering/peclet
+Project-URL: Source, https://github.com/computational-chemical-engineering/peclet-coupling
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.20
+Requires-Dist: peclet-flow>=0.3.0
+Requires-Dist: peclet-dem>=0.3.2
+Description-Content-Type: text/markdown
+
+# peclet.coupling — unresolved point-particle CFD-DEM
+
+Two-way coupling of `peclet.flow` (Eulerian fluid) and `peclet.dem` (Lagrangian particles) for
+dilute-to-dense point-particle suspensions and packed beds. Multiphysics Phase 6 — see
+`../docs/MULTIPHYSICS_PLAN.md`.
+
+## Design
+
+Physics-free glue. The compute kernels (particle↔grid deposition, drag laws, momentum feedback) live
+in the `_coupling` nanobind extension and run **in place** on the arrays the two solvers already
+expose — the fluid grid fields zero-copy through `flow.field_view(...)`, the particle drag
+round-tripped through the dem host API. **There is no C++ link between flow and dem**: the Python
+`CfdDem` driver (`python/peclet_coupling/driver.py`) composes them. This mirrors the suite's
+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).
+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.
+3. **Advance** — apply the drag to the particles and sub-step dem `dem_substeps` times (drag held
+   constant), then advance the fluid one step (its RHS/operator now carry the feedback).
+
+### Implicit drag (the key stability piece)
+
+An explicit reaction force `−β(u−u_p)` in the fluid RHS **diverges** for the stiff drag coefficient
+β of a dense bed (β·dt/ρ ≫ 1; local β reaches ~10³). So the default feedback is **semi-implicit**:
+the coupling deposits the linear-drag *coefficient* density onto flow's `drag_beta` field (added to
+the momentum diagonal by `flow.enable_drag()`) and the target `β·u_p` onto `force_*` (the RHS), so
+the fluid solve becomes `(ρ/dt + β)u = … + β u_p` — unconditionally stable for any β. The particle
+side stays explicit (fine for moving particles at moderate β). `implicit_drag=False` selects the
+explicit `−F/Vcell` feedback (dilute only).
+
+### Two fluid modes
+
+- **`porous=True` — volume-averaged (use this for beds).** The fluid solves the full volume-averaged
+  continuity `∂ε/∂t + ∇·(εu) = 0` (u = the **interstitial** gas velocity) with a SIMPLE-like eps- and
+  drag-weighted pressure projection — scheme, defaults and validation in
+  `flow/doc/porous_drag_scheme.md`. The pressure-force split is **Model B**: the gas carries the full
+  `−∇p`, the particles get drag + gravity, and the literature (Model-A) drag closures are converted
+  once inside the kernel, `β_B = β_A/ε` (`model_b` flag). Gas convection (implicit FOU + explicit
+  deferred-correction TVD) is enabled by the driver by default (`advection=True`).
+- **`porous=False` — dilute simplification.** The fluid stays incompressible (`div u = 0`); ε enters
+  the drag correlation only. Cheap and validated dilute→moderate. Note this is *not* "Model B":
+  Models A and B both use the full continuity and differ only in the `−ε∇p` vs `−∇p` split.
+
+Other scope notes: deposition uses `atomic_add` ⇒ results are tolerance-, not bit-exact; the `"ergun"`
+drag *kind* is the superficial-velocity form built for the incompressible mode — for porous beds use
+`"gidaspow"` (its dense branch is the classic interstitial Ergun form).
+
+## Backends
+
+`CfdDem` runs on whatever Kokkos backend `peclet.flow` was built for. On a **CUDA/HIP** build the
+coupling kernels run on-device, so the driver array-programs through **CuPy** and takes the grid
+fields (`flow.field_view`) and particle state (`dem.get_*_view`) zero-copy via DLPack; on a host
+build it uses NumPy over the same buffers. Detected automatically from `peclet.flow.execution_space`.
+
+## Validation (`tests/`)
+
+Both cases pass identically on **host-openmp and CUDA (RTX 5080)**:
+- **`test_terminal_velocity.py`** — single settling sphere: the slip velocity matches Stokes to
+  **0.1–0.2 %** and Schiller–Naumann to **1.4–1.6 %** (the lab-frame speed is ~2× the slip because
+  the particle drags its own Stokeslet flow, so the physical comparison is the slip).
+- **`test_fixed_bed_ergun.py`** — uniform fixed bed (one particle per cell, ε = 0.6): the measured
+  (f_drive, U) pair lands on the Ergun curve to **0.0 %** across the viscous, transition and inertial
+  (Re_p ≈ 6) regimes — validating ε deposition, both Ergun terms, and the stable two-way feedback.
+- **`test_fixed_bed_ergun_porous.py`** — the same bed on the **volume-averaged (porous, Model B)**
+  path with the Gidaspow closure: (f_drive, U = ε·u_interstitial) lands on the Ergun curve to ~3 %
+  across all three regimes with no fitted factors — validating the eps-weighted projection, the
+  interstitial kinematics and the `β_B = β_A/ε` conversion together.
+- **`test_mpi_fixed_bed_ergun.py`** — the fixed-bed Ergun benchmark run **distributed** (flow
+  `init_mpi`, each rank couples its ORB block; particle deposits fold across ranks + periodically via
+  the reverse/add-reduce halo `exchange_field_add`, deposit origin shifted by the block origin). The
+  superficial velocity U (reduced over ranks) lands on the Ergun curve to **0.0 %** and is
+  **bit-identical at np=1/2/4** — the distributed deposition + fold + solve reproduce the coupled
+  physics exactly.
+- P2G/G2P conservation + the gather/scatter adjoint identity: `core` `test_particle_grid` (host + CUDA).
+
+## Multi-rank coupling
+
+`CfdDem` runs distributed when the flow solver is decomposed (`flow.init_mpi(...)`, world size > 1):
+each rank couples its **local block**, the deposit grid map is shifted by the block origin (so
+particles in global coordinates land locally), and cross-rank + periodic ghost deposits (void
+fraction + drag reaction) fold onto their owner with the reverse halo (`exchange_field_add`) instead
+of the single-rank NumPy fold. `CfdDem.rebalance(gamma)` forms one weight field
+(`1 + gamma * particle_count`) and redistributes BOTH codes onto the same weighted ORB
+(`flow.rebalance_by_weights` + `dem.migrate_to_weights`). Give the flow + dem the same decomposition
+(matching grid dims / domain) before constructing `CfdDem`.
+
+**Moving particles** (`move_particles=True`): each fluid step `CfdDem` first migrates dem onto flow's
+grid partition (`dem.migrate_to_weights`) so every owned particle sits in its rank's block, then runs
+the DISTRIBUTED DEM substeps (`dem.step_mpi`, requires `dem.init_mpi` + `dem.enable_mpi_step`). A rank
+that momentarily owns no particles still runs the halo collectives (the per-particle kernels are
+skipped). Validated `test_mpi_fixed_bed_ergun.py` (static, bit-identical np 1/2/4) and
+`test_mpi_moving_suspension.py` (drifting cloud crossing rank boundaries: the distributed
+migrate + step + deposit-fold + gather reproduce single-rank to ~2e-7, np 1/2).
+
+Two known limitations of the underlying dem distributed step (not the coupling — every distributed
+coupling op is bit-identical to single-rank in isolation): (1) a rank with **zero owned particles but
+an incoming ghost** deadlocks the dem step (affects very dilute clouds / np=4 of the moving test);
+(2) a *sustained* dilute settling suspension in a triply-periodic box with no buoyancy is an ill-posed,
+numerically unstable configuration — at np>1 the flow solve's reduction-floor non-determinism seeds
+that instability. Well-posed cases (bounded / driven flow, denser beds) are unaffected.
+
+Note: `dem.get_velocities()` (host copy getter) has a pre-existing failure after a *periodic* DEM
+step on CUDA (a Kokkos strided-subview-after-resize limitation, unrelated to the coupling); the
+driver uses the zero-copy device *views* throughout and exposes `last_slip` for inspection.
+
+## Build
+
+```bash
+cmake -S . -B build -DCMAKE_PREFIX_PATH="$PWD/../extern/install/host-openmp"
+cmake --build build -j        # -> build/peclet/coupling/_coupling.*.so
+# run the tests (all three build trees on PYTHONPATH):
+PYTHONPATH="$PWD/build:$PWD/../flow/build:$PWD/../dem/build" \
+  python tests/test_fixed_bed_ergun.py
+```
+
+## Follow-ups
+
+Kernel-width (vs trilinear) deposition smoothing; the `ρε` volume-averaged inertia and
+`∇·[εμ(∇u+∇uᵀ)]` viscous forms in the gas momentum (accuracy — see
+`flow/doc/porous_drag_scheme.md` §6); a PEA-style implicit particle-drag substep for very stiff
+*moving* beds (`m_p/β < Δt` — the fluid side is already implicit).

peclet_coupling-0.2.0/README.md

@@ -0,0 +1,128 @@
+# peclet.coupling — unresolved point-particle CFD-DEM
+
+Two-way coupling of `peclet.flow` (Eulerian fluid) and `peclet.dem` (Lagrangian particles) for
+dilute-to-dense point-particle suspensions and packed beds. Multiphysics Phase 6 — see
+`../docs/MULTIPHYSICS_PLAN.md`.
+
+## Design
+
+Physics-free glue. The compute kernels (particle↔grid deposition, drag laws, momentum feedback) live
+in the `_coupling` nanobind extension and run **in place** on the arrays the two solvers already
+expose — the fluid grid fields zero-copy through `flow.field_view(...)`, the particle drag
+round-tripped through the dem host API. **There is no C++ link between flow and dem**: the Python
+`CfdDem` driver (`python/peclet_coupling/driver.py`) composes them. This mirrors the suite's
+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).
+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.
+3. **Advance** — apply the drag to the particles and sub-step dem `dem_substeps` times (drag held
+   constant), then advance the fluid one step (its RHS/operator now carry the feedback).
+
+### Implicit drag (the key stability piece)
+
+An explicit reaction force `−β(u−u_p)` in the fluid RHS **diverges** for the stiff drag coefficient
+β of a dense bed (β·dt/ρ ≫ 1; local β reaches ~10³). So the default feedback is **semi-implicit**:
+the coupling deposits the linear-drag *coefficient* density onto flow's `drag_beta` field (added to
+the momentum diagonal by `flow.enable_drag()`) and the target `β·u_p` onto `force_*` (the RHS), so
+the fluid solve becomes `(ρ/dt + β)u = … + β u_p` — unconditionally stable for any β. The particle
+side stays explicit (fine for moving particles at moderate β). `implicit_drag=False` selects the
+explicit `−F/Vcell` feedback (dilute only).
+
+### Two fluid modes
+
+- **`porous=True` — volume-averaged (use this for beds).** The fluid solves the full volume-averaged
+  continuity `∂ε/∂t + ∇·(εu) = 0` (u = the **interstitial** gas velocity) with a SIMPLE-like eps- and
+  drag-weighted pressure projection — scheme, defaults and validation in
+  `flow/doc/porous_drag_scheme.md`. The pressure-force split is **Model B**: the gas carries the full
+  `−∇p`, the particles get drag + gravity, and the literature (Model-A) drag closures are converted
+  once inside the kernel, `β_B = β_A/ε` (`model_b` flag). Gas convection (implicit FOU + explicit
+  deferred-correction TVD) is enabled by the driver by default (`advection=True`).
+- **`porous=False` — dilute simplification.** The fluid stays incompressible (`div u = 0`); ε enters
+  the drag correlation only. Cheap and validated dilute→moderate. Note this is *not* "Model B":
+  Models A and B both use the full continuity and differ only in the `−ε∇p` vs `−∇p` split.
+
+Other scope notes: deposition uses `atomic_add` ⇒ results are tolerance-, not bit-exact; the `"ergun"`
+drag *kind* is the superficial-velocity form built for the incompressible mode — for porous beds use
+`"gidaspow"` (its dense branch is the classic interstitial Ergun form).
+
+## Backends
+
+`CfdDem` runs on whatever Kokkos backend `peclet.flow` was built for. On a **CUDA/HIP** build the
+coupling kernels run on-device, so the driver array-programs through **CuPy** and takes the grid
+fields (`flow.field_view`) and particle state (`dem.get_*_view`) zero-copy via DLPack; on a host
+build it uses NumPy over the same buffers. Detected automatically from `peclet.flow.execution_space`.
+
+## Validation (`tests/`)
+
+Both cases pass identically on **host-openmp and CUDA (RTX 5080)**:
+- **`test_terminal_velocity.py`** — single settling sphere: the slip velocity matches Stokes to
+  **0.1–0.2 %** and Schiller–Naumann to **1.4–1.6 %** (the lab-frame speed is ~2× the slip because
+  the particle drags its own Stokeslet flow, so the physical comparison is the slip).
+- **`test_fixed_bed_ergun.py`** — uniform fixed bed (one particle per cell, ε = 0.6): the measured
+  (f_drive, U) pair lands on the Ergun curve to **0.0 %** across the viscous, transition and inertial
+  (Re_p ≈ 6) regimes — validating ε deposition, both Ergun terms, and the stable two-way feedback.
+- **`test_fixed_bed_ergun_porous.py`** — the same bed on the **volume-averaged (porous, Model B)**
+  path with the Gidaspow closure: (f_drive, U = ε·u_interstitial) lands on the Ergun curve to ~3 %
+  across all three regimes with no fitted factors — validating the eps-weighted projection, the
+  interstitial kinematics and the `β_B = β_A/ε` conversion together.
+- **`test_mpi_fixed_bed_ergun.py`** — the fixed-bed Ergun benchmark run **distributed** (flow
+  `init_mpi`, each rank couples its ORB block; particle deposits fold across ranks + periodically via
+  the reverse/add-reduce halo `exchange_field_add`, deposit origin shifted by the block origin). The
+  superficial velocity U (reduced over ranks) lands on the Ergun curve to **0.0 %** and is
+  **bit-identical at np=1/2/4** — the distributed deposition + fold + solve reproduce the coupled
+  physics exactly.
+- P2G/G2P conservation + the gather/scatter adjoint identity: `core` `test_particle_grid` (host + CUDA).
+
+## Multi-rank coupling
+
+`CfdDem` runs distributed when the flow solver is decomposed (`flow.init_mpi(...)`, world size > 1):
+each rank couples its **local block**, the deposit grid map is shifted by the block origin (so
+particles in global coordinates land locally), and cross-rank + periodic ghost deposits (void
+fraction + drag reaction) fold onto their owner with the reverse halo (`exchange_field_add`) instead
+of the single-rank NumPy fold. `CfdDem.rebalance(gamma)` forms one weight field
+(`1 + gamma * particle_count`) and redistributes BOTH codes onto the same weighted ORB
+(`flow.rebalance_by_weights` + `dem.migrate_to_weights`). Give the flow + dem the same decomposition
+(matching grid dims / domain) before constructing `CfdDem`.
+
+**Moving particles** (`move_particles=True`): each fluid step `CfdDem` first migrates dem onto flow's
+grid partition (`dem.migrate_to_weights`) so every owned particle sits in its rank's block, then runs
+the DISTRIBUTED DEM substeps (`dem.step_mpi`, requires `dem.init_mpi` + `dem.enable_mpi_step`). A rank
+that momentarily owns no particles still runs the halo collectives (the per-particle kernels are
+skipped). Validated `test_mpi_fixed_bed_ergun.py` (static, bit-identical np 1/2/4) and
+`test_mpi_moving_suspension.py` (drifting cloud crossing rank boundaries: the distributed
+migrate + step + deposit-fold + gather reproduce single-rank to ~2e-7, np 1/2).
+
+Two known limitations of the underlying dem distributed step (not the coupling — every distributed
+coupling op is bit-identical to single-rank in isolation): (1) a rank with **zero owned particles but
+an incoming ghost** deadlocks the dem step (affects very dilute clouds / np=4 of the moving test);
+(2) a *sustained* dilute settling suspension in a triply-periodic box with no buoyancy is an ill-posed,
+numerically unstable configuration — at np>1 the flow solve's reduction-floor non-determinism seeds
+that instability. Well-posed cases (bounded / driven flow, denser beds) are unaffected.
+
+Note: `dem.get_velocities()` (host copy getter) has a pre-existing failure after a *periodic* DEM
+step on CUDA (a Kokkos strided-subview-after-resize limitation, unrelated to the coupling); the
+driver uses the zero-copy device *views* throughout and exposes `last_slip` for inspection.
+
+## Build
+
+```bash
+cmake -S . -B build -DCMAKE_PREFIX_PATH="$PWD/../extern/install/host-openmp"
+cmake --build build -j        # -> build/peclet/coupling/_coupling.*.so
+# run the tests (all three build trees on PYTHONPATH):
+PYTHONPATH="$PWD/build:$PWD/../flow/build:$PWD/../dem/build" \
+  python tests/test_fixed_bed_ergun.py
+```
+
+## Follow-ups
+
+Kernel-width (vs trilinear) deposition smoothing; the `ρε` volume-averaged inertia and
+`∇·[εμ(∇u+∇uᵀ)]` viscous forms in the gas momentum (accuracy — see
+`flow/doc/porous_drag_scheme.md` §6); a PEA-style implicit particle-drag substep for very stiff
+*moving* beds (`m_p/β < Δt` — the fluid side is already implicit).

peclet_coupling-0.2.0/cmake/PecletDeps.cmake

@@ -0,0 +1,123 @@
+# PecletDeps.cmake — self-contained dependency provisioning for a peclet compute package.
+#
+# A peclet compute wheel must build both ways:
+#   * DEV / suite build — Kokkos (+ArborX) come from an installed prefix on CMAKE_PREFIX_PATH
+#     (../extern/install/<backend> from tools/bootstrap_deps.sh) and the sibling headers
+#     (core, morton) from ../<sibling>/include. Fast; the developer workflow.
+#   * SELF-CONTAINED sdist/wheel (cibuildwheel) — the umbrella and siblings are ABSENT (the build runs on
+#     an isolated copy of this one repo), so everything is FetchContent-built at the suite-pinned
+#     versions. This is what makes `pip install peclet-flow` produce a working OpenMP CPU wheel.
+#
+# Selection is automatic (prefix/sibling present -> use it; else fetch), and can be forced off/on with
+# -DPECLET_VENDOR_DEPS=ON. Vendored Kokkos is OpenMP+Serial only (portable CPU wheel); GPU/MPI builds use
+# the prefix path. Keep PECLET_*_TAG in lockstep with tools/bootstrap_deps.sh.
+include_guard(GLOBAL)
+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)")
+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),
+# identical to the umbrella SuiteNanobind helper but vendored so an isolated sdist build needs no ../cmake.
+# MUST be a macro: find_package(Python) sets variables nanobind reads at module-creation time in the
+# caller's scope.
+macro(peclet_require_nanobind)
+  if(NOT COMMAND nanobind_add_module)
+    find_package(Python 3.10 REQUIRED COMPONENTS Interpreter Development.Module)
+    if(NOT nanobind_DIR)
+      execute_process(COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir
+        OUTPUT_VARIABLE _peclet_nb OUTPUT_STRIP_TRAILING_WHITESPACE RESULT_VARIABLE _peclet_nb_rc)
+      if(_peclet_nb_rc EQUAL 0 AND EXISTS "${_peclet_nb}")
+        set(nanobind_DIR "${_peclet_nb}")
+      endif()
+    endif()
+    find_package(nanobind CONFIG REQUIRED)
+    message(STATUS "[peclet] nanobind from ${nanobind_DIR}")
+  endif()
+endmacro()
+
+# Vendored Kokkos/ArborX are *installed* to a staging prefix (not added as bare build-tree subprojects):
+# ArborX REQUIREs an installed Kokkos package config (`find_package(Kokkos ... CONFIG)`), which a
+# FetchContent subproject target does not provide — so a subproject Kokkos makes ArborX's own
+# find_package(Kokkos) fail. Instead we build+install each into a shared staging prefix exactly like
+# tools/bootstrap_deps.sh, then find_package() both (satisfying our code AND ArborX). Built once (marker).
+set(PECLET_STAGE_PREFIX "${CMAKE_BINARY_DIR}/_peclet_deps" CACHE PATH "Vendored-deps staging install prefix")
+
+function(_peclet_stage_build name url tag)  # extra -D configure args via ARGN
+  FetchContent_Declare(${name} GIT_REPOSITORY "${url}" GIT_TAG "${tag}" GIT_SHALLOW TRUE)
+  FetchContent_GetProperties(${name})
+  if(NOT ${name}_POPULATED)
+    FetchContent_Populate(${name})
+  endif()
+  if(EXISTS "${PECLET_STAGE_PREFIX}/.peclet_${name}_installed")
+    return()
+  endif()
+  message(STATUS "[peclet] building+installing ${name} ${tag} -> ${PECLET_STAGE_PREFIX}")
+  execute_process(
+    COMMAND ${CMAKE_COMMAND} -S "${${name}_SOURCE_DIR}" -B "${${name}_BINARY_DIR}"
+            -DCMAKE_BUILD_TYPE=Release "-DCMAKE_INSTALL_PREFIX=${PECLET_STAGE_PREFIX}"
+            "-DCMAKE_PREFIX_PATH=${PECLET_STAGE_PREFIX}" -DCMAKE_CXX_STANDARD=20
+            -DCMAKE_POSITION_INDEPENDENT_CODE=ON ${ARGN}
+    RESULT_VARIABLE _rc)
+  if(NOT _rc EQUAL 0)
+    message(FATAL_ERROR "[peclet] ${name} configure failed (${_rc})")
+  endif()
+  execute_process(COMMAND ${CMAKE_COMMAND} --build "${${name}_BINARY_DIR}" --target install --parallel
+                  RESULT_VARIABLE _rc)
+  if(NOT _rc EQUAL 0)
+    message(FATAL_ERROR "[peclet] ${name} build/install failed (${_rc})")
+  endif()
+  file(WRITE "${PECLET_STAGE_PREFIX}/.peclet_${name}_installed" "")
+endfunction()
+
+# Kokkos — prefix if present (unless forced), else vendored OpenMP+Serial installed to the staging prefix.
+macro(peclet_require_kokkos)
+  if(NOT PECLET_VENDOR_DEPS)
+    find_package(Kokkos CONFIG QUIET)
+  endif()
+  if(Kokkos_FOUND)
+    message(STATUS "[peclet] Kokkos ${Kokkos_VERSION} from prefix (${Kokkos_DEVICES})")
+  else()
+    _peclet_stage_build(kokkos "https://github.com/kokkos/kokkos.git" "${PECLET_KOKKOS_TAG}"
+                        -DKokkos_ENABLE_OPENMP=ON -DKokkos_ENABLE_SERIAL=ON)
+    list(APPEND CMAKE_PREFIX_PATH "${PECLET_STAGE_PREFIX}")
+    find_package(Kokkos CONFIG REQUIRED)
+    message(STATUS "[peclet] vendored Kokkos ${Kokkos_VERSION} @ ${PECLET_STAGE_PREFIX}")
+  endif()
+endmacro()
+
+# ArborX — header-only but REQUIREs an installed Kokkos config; built against + installed to the same prefix.
+macro(peclet_require_arborx)
+  if(NOT PECLET_VENDOR_DEPS)
+    find_package(ArborX CONFIG QUIET)
+  endif()
+  if(NOT ArborX_FOUND)
+    _peclet_stage_build(arborx "https://github.com/arborx/ArborX.git" "${PECLET_ARBORX_TAG}")
+    list(APPEND CMAKE_PREFIX_PATH "${PECLET_STAGE_PREFIX}")
+    find_package(ArborX CONFIG REQUIRED)
+    message(STATUS "[peclet] vendored ArborX ${ArborX_VERSION} @ ${PECLET_STAGE_PREFIX}")
+  endif()
+endmacro()
+
+# Sibling header include dir (core / morton). Returns the sibling checkout if present, else a
+# FetchContent-fetched source tree's include/ (header-only — declared but not built).
+function(peclet_sibling_include repo tag sibling_reldir outvar)
+  set(_local "${CMAKE_CURRENT_SOURCE_DIR}/${sibling_reldir}/include")
+  if(EXISTS "${_local}" AND NOT PECLET_VENDOR_DEPS)
+    set(${outvar} "${_local}" PARENT_SCOPE)
+    return()
+  endif()
+  string(TOLOWER "peclet_sib_${repo}" _name)
+  FetchContent_Declare(${_name}
+    GIT_REPOSITORY "https://github.com/computational-chemical-engineering/${repo}.git"
+    GIT_TAG ${tag} GIT_SHALLOW TRUE)
+  FetchContent_GetProperties(${_name})
+  if(NOT ${_name}_POPULATED)
+    FetchContent_Populate(${_name})
+  endif()
+  set(${outvar} "${${_name}_SOURCE_DIR}/include" PARENT_SCOPE)
+  message(STATUS "[peclet] vendored ${repo} headers -> ${${_name}_SOURCE_DIR}/include")
+endfunction()