flow

pip install peclet-flow          # CPU (OpenMP) wheels — or `pip install peclet` for the whole family
pip install peclet-flow-cu13     # the CUDA 13 build of the same module, in its OWN venv

Both ship the incompressible cut-cell IBM Navier–Stokes solver as peclet.flow; they provide the same import, so they are mutually exclusive in one environment — one venv per backend. Multi-GPU/MPI and AMD/HIP are source or container builds: see Install & run.

GPU-accelerated incompressible Navier–Stokes solver for flow in complex geometry, built around a staggered MAC grid, a signed-distance-field (SDF) description of the solid, a cut-cell Immersed Boundary Method, and a pressure-projection step with a geometric multigrid Poisson solve. The code is written in Kokkos C++ (one source runs on the CUDA, HIP/AMD, and OpenMP backends, selected at build time) and exposed to Python through nanobind (zero-copy, on core's View↔ndarray bridge); simulations are driven from Python.

The repository is also known as pnm_from_sdf (its GitLab origin) — it computes pore-network–scale flow directly from segmented SDF geometry. The pore-network extraction itself (the former peclet.flow.pnm module) now lives in its own suite project, peclet-pnm (peclet.pnm).

Modules

Module

Role

flow

The CFD solver — a distributed (MPI-optional) GPU cut-cell IBM Navier–Stokes solver in physical units, built on the shared core block-decomposition + async halo layer. One code / one API / MPI-optional, with native domain boundary conditions. Exposes peclet.flow.Solver (staggered MAC, default) and peclet.flow.SolverColocated (collocated/cell-centered velocities, ABC approximate projection) — identical API via a GridLayout policy. Validated against analytics and Zick & Homsy sphere-array drag (scripts/validate_zick_homsy_sdflow.py).

The original CUDA implementation has been retired (Kokkos became canonical, 2026-06); flow was validated bit-identical to the CUDA solver — to machine precision, and against Zick & Homsy sphere-array drag — before the CUDA sources were deleted (restore point: git tag pre-cuda-retirement). The shared cut-cell IBM primitives now live in src/cut_cell_ibm.hpp; the operator headers are src/mac_*.hpp + src/flow_ibm.hpp (the Solver class declarations + state; its member definitions are split by physics domain across twelve src/flow_ibm_*.hpp headers it includes -- see CLAUDE.md's Layout section).

Capabilities

• Geometry: SDF solids (negative inside); the cut-cell IBM applies a Robust-Scaled no-slip / moving-wall condition and a matching cut-cell pressure operator (face openness from the SDF).
• Native domain boundary conditions (flow): per-face periodic / no-slip wall / Dirichlet velocity (inflow) / outflow / free-slip (symmetry plane), plus per-position inlet velocity profiles. Validated on the lid-driven cavity (Ghia et al.), the developing plane channel (Poiseuille), the backward-facing step (Armaly/Gartling), and a half channel closed by a symmetry plane (pointwise equal to the full one).
• Pressure multigrid: rediscretized geometric V-cycle, grid-independent, with MG-PCG, flexible MG-CG and Chebyshev outer accelerators, an agglomerated coarse solve and coarse-level telescoping. Works on periodic, IBM and non-periodic (BC) domains, including semi-coarsening for thin (quasi-2D) grids.
• Two-phase flow: geometric VoF (PLIC + Weymouth–Yue advection), height-function curvature, balanced-force surface tension, contact angles and phase change.
• Time integration: pressure projection with optional incremental pressure, explicit (Koren) or implicit-deferred-correction advection, and Picard outer iteration.
• Steady states: peclet.flow.march_to_steady(solver, monitor) marches to a certified steady state, Anderson-accelerated by default (a dense sphere bed in 93 steps instead of 325); converged=True certifies stationarity at the given time step.
• Forces on bodies: hydro_force_torque_reaction(), the discrete momentum reaction (exactly conservative). The surface-traction integral with its pressure/viscous split is the diagnostic diagnostics.hydro_force_torque_traction(); hydro_force_torque() is deprecated.

Build

# Canonical: build + install via scikit-build-core
CMAKE_PREFIX_PATH="$PWD/../extern/install/<backend>" pip install .   # -> peclet.flow
# Or a dev cmake build (nanobind found via the active interpreter, no cmakedir needed).
# ONE tree per backend: add the test suites, and MPI, to the same tree.
cmake -S . -B build_dev -DCMAKE_PREFIX_PATH="$PWD/../extern/install/<backend>" \
  -DPECLET_FLOW_BUILD_TESTS=ON -DPECLET_FLOW_MPI=ON -DMPIEXEC_EXECUTABLE=/usr/bin/mpirun
cmake --build build_dev -j

<backend> is one of nvidia-cuda / host-openmp / lumi-hip under ../extern/install/, produced once by ../tools/bootstrap_deps.sh (a hard build dependency). Requirements: a Kokkos backend (CUDA/HIP/OpenMP — CUDA is just one option, not required), a C++20 host compiler, nanobind + scikit-build-core, and — for distributed flow — MPI. Python dependencies live in a virtual environment (.venv).

Run / verify

Simulations are scripts, not C++ mains. The scripts/verify_*_sdflow.py files are the canonical verification entry points:

source ../.venv/bin/activate                   # THE suite venv (see ../CLAUDE.md, "One venv")
export PYTHONPATH=$PWD/build_dev
python scripts/verify_lid_cavity_sdflow.py     # lid-driven cavity vs Ghia, Ghia & Shin (1982)
python scripts/verify_channel_sdflow.py        # developing plane channel -> Poiseuille
python scripts/verify_bfs_sdflow.py            # backward-facing step (reattachment length)
# the C++ kernel + multi-rank suites, from the tree built above (156 registered, 154 without
# the `bench`-labelled timing instruments):
OMP_NUM_THREADS=8 OMP_PROC_BIND=false ctest --test-dir build_dev --output-on-failure -LE bench

Documentation

API documentation (C++ classes/kernels and Python scripts) is generated with Doxygen and published to GitHub Pages by the Documentation CI workflow. Build it locally with:

doxygen docs/Doxyfile      # output in docs/html/index.html

The architecture, conventions and design rationale are in CLAUDE.md and the design notes under doc/; the campaign records and work orders that produced them are archived, indexed and unmaintained under doc/history/.