Metadata-Version: 2.4
Name: peclet-flow
Version: 1.1.0
Summary: peclet.flow — Kokkos cut-cell IBM incompressible Navier-Stokes solver
Author-Email: Frank Peters <e.a.j.f.peters@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
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-flow
Requires-Python: >=3.10
Requires-Dist: numpy>=1.20
Description-Content-Type: text/markdown

# flow

[![PyPI version](https://img.shields.io/pypi/v/peclet-flow.svg)](https://pypi.org/project/peclet-flow/)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://pypi.org/project/peclet-flow/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/computational-chemical-engineering/peclet-flow/blob/main/LICENSE)
[![CI](https://github.com/computational-chemical-engineering/peclet-flow/actions/workflows/ci.yml/badge.svg)](https://github.com/computational-chemical-engineering/peclet-flow/actions/workflows/ci.yml)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21132439.svg)](https://doi.org/10.5281/zenodo.21132439)

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](https://github.com/computational-chemical-engineering/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.

## Build

```bash
# 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:

```bash
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:

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

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