peclet-flow 0.1.0__tar.gz

peclet_flow-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+# Build the Kokkos (OpenMP/Serial) backend from source, then build the sdflow + pnm Python modules and
+# run the single-rank Kokkos kernel unit tests. The GPU (CUDA/HIP) backends and the multi-rank MPI
+# tests are NOT exercisable on free GitHub runners (no GPU); this CI covers the portable host build and
+# the CPU kernel tests, which is what catches the vast majority of regressions. The single-rank modules
+# never link MPI/core (the distributed path is gated behind CFD_MPI), so Kokkos + pybind11 is
+# the whole dependency set here.
+
+on:
+  push:
+    branches: [main, "**"]
+  pull_request:
+  workflow_dispatch:
+
+env:
+  KOKKOS_TAG: "5.1.1"   # keep in lockstep with ../tools/bootstrap_deps.sh
+
+jobs:
+  build-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install toolchain
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y cmake ninja-build libomp-dev python3-dev python3-pip
+          python3 -m pip install --upgrade pip pybind11 numpy
+
+      - name: Cache Kokkos install
+        id: kokkos-cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ github.workspace }}/kokkos-install
+          key: kokkos-${{ env.KOKKOS_TAG }}-openmp-${{ runner.os }}
+
+      - name: Build Kokkos (OpenMP + Serial)
+        if: steps.kokkos-cache.outputs.cache-hit != 'true'
+        run: |
+          git clone --depth 1 --branch "$KOKKOS_TAG" https://github.com/kokkos/kokkos.git /tmp/kokkos
+          cmake -S /tmp/kokkos -B /tmp/kokkos/build -G Ninja \
+            -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_STANDARD=20 \
+            -DCMAKE_POSITION_INDEPENDENT_CODE=ON \
+            -DKokkos_ENABLE_OPENMP=ON -DKokkos_ENABLE_SERIAL=ON \
+            -DCMAKE_INSTALL_PREFIX="$GITHUB_WORKSPACE/kokkos-install"
+          cmake --build /tmp/kokkos/build -j
+          cmake --install /tmp/kokkos/build
+
+      - name: Build sdflow + pnm modules
+        run: |
+          cmake -S . -B build \
+            -DCMAKE_PREFIX_PATH="$GITHUB_WORKSPACE/kokkos-install;$(python3 -m pybind11 --cmakedir)"
+          cmake --build build -j
+
+      - name: Import smoke test
+        run: PYTHONPATH=$PWD/build python3 -c "import sdflow, pnm; print('sdflow + pnm import OK')"
+
+      - name: Build + run Kokkos kernel unit tests (tests/kokkos)
+        run: |
+          # Kokkos-only unit suite (no MPI / core): the ported cut-cell IBM, advection,
+          # multigrid-transfer, BC and reduction kernels, each checked against a serial reference.
+          cmake -S tests/kokkos -B build_kokkos \
+            -DCMAKE_PREFIX_PATH="$GITHUB_WORKSPACE/kokkos-install"
+          cmake --build build_kokkos -j
+          ctest --test-dir build_kokkos --output-on-failure

peclet_flow-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,59 @@
+name: Documentation
+
+# Build the Doxygen API documentation (Kokkos C++ in src/, Python in scripts/ & tests/) and publish it
+# to GitHub Pages. Requires Pages to be enabled for the repository with "Source: GitHub Actions"
+# (Settings -> Pages). Runs on every push to main; can also be triggered manually. Doxygen only parses
+# the sources (no Kokkos toolchain needed), so this runs on a plain ubuntu runner.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'src/**'
+      - 'scripts/**'
+      - 'tests/**'
+      - 'docs/**'
+      - 'README.md'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# allow one concurrent deployment; cancel an in-progress run for a newer push
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Doxygen + Graphviz
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y doxygen graphviz
+
+      - name: Build documentation
+        run: doxygen docs/Doxyfile
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/html
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

peclet_flow-0.1.0/.github/workflows/quality.yml

@@ -0,0 +1,26 @@
+name: Quality
+
+# Lightweight, non-breaking code-quality gates. The Python job hard-fails on *critical* errors only
+# (syntax errors, undefined names, bad string formatting / comparisons — the classic stop-the-build
+# set), so it catches real bugs without drowning research scripts in style nits.
+
+on:
+  push:
+    branches: [main, "**"]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  python-lint:
+    name: ruff (critical errors)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - name: Ruff critical-error check
+        run: |
+          ruff check . --select E9,F63,F7,F82 \
+            --exclude ".venv,venv,build,build_*,__pycache__,_deps,extern,legacy,notebooks"

peclet_flow-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,53 @@
+name: Release
+
+# Build the sdist + self-contained OpenMP CPU wheels and publish to PyPI (peclet-flow) on a version tag.
+# Uses PyPI Trusted Publishing (OIDC) — configure the publisher on PyPI first; no API token secret needed.
+# The wheels FetchContent-build Kokkos (OpenMP+Serial) + the core headers inside each build
+# (PECLET_VENDOR_DEPS=ON, from pyproject's [tool.cibuildwheel]); GPU/HIP + MPI are the source (sdist) path.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build --sdist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  wheels:
+    name: wheels (manylinux_2_28 x86_64)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # cibuildwheel reads [tool.cibuildwheel] from pyproject.toml (PECLET_VENDOR_DEPS=ON): each wheel
+      # compiles Kokkos as a subproject, so builds are slow but self-contained.
+      - uses: pypa/cibuildwheel@v2.21
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-linux
+          path: wheelhouse/*.whl
+
+  publish:
+    needs: [sdist, wheels]
+    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@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1

peclet_flow-0.1.0/.gitignore

@@ -0,0 +1,77 @@
+# Build directories
+build/
+build_*/
+bin/
+lib/
+*.so
+*.a
+*.o
+*.log
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+env/
+venv/
+.env
+.venv
+*.egg-info/
+
+# IDE/Editor
+.vscode/
+.idea/
+*.swp
+*~
+.DS_Store
+
+# CMake
+CMakeCache.txt
+CMakeFiles/
+cmake_install.cmake
+Makefile
+install_manifest.txt
+_deps/
+
+# Cache
+.cache/
+
+# Data
+data/
+
+# Output files
+*.vtp
+*.vti
+*.edges
+*.npz
+output/
+*.png
+*.csv
+*.pvsm
+
+# Generated documentation (built by Doxygen / CI)
+docs/html/
+docs/latex/
+doxygen_warn.txt
+
+# Agent/scratch cruft — old planning notes, AI context dumps, session logs (keep these out of
+# `git add -A`). Tracked design docs (e.g. doc/sdflow_*_plan.md) are unaffected; force-add a new
+# plan with `git add -f` if it should be versioned.
+.codex
+codebase_context.txt
+output.txt
+doc/tmp.txt
+doc/refactor_claude.txt
+doc/session-*.json
+doc/plan_*.md
+doc/implementation_plan_*.md
+doc/*_handoff.md
+doc/*_review*.md
+doc/*investigation*.md
+doc/IBM_Implementation_Plan.md
+doc/continuation_force_sweep_*.md
+doc/pressure_from_phi_plan.md
+doc/pymrm_ghost_cell_ibm_transfer.md
+

peclet_flow-0.1.0/AGENTS.md

@@ -0,0 +1,41 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `src/`: header-only **Kokkos** C++ sources for the CFD solver + **nanobind** bindings (`.hpp` + `.cpp`; no `.cu/.cuh` — CUDA retired).
+- `tests/`: C++ Kokkos kernel tests (`tests/kokkos/`) + multi-rank ctests (`tests/kokkos_mpi/test_*.cpp`) + a couple of pore-extraction Python scripts.
+- `scripts/`: `flow` verification/analysis scripts (e.g., `verify_poiseuille_sdflow.py`).
+- `build/`: CMake build output (expects `build/peclet.flow.*.so` + `build/pnm.*.so`).
+- `doc/`, `notebooks/`, `data/`: design notes, experiments, and input datasets.
+
+## Build, Test, and Development Commands
+```bash
+# Build/install the Python extensions via scikit-build-core (Kokkos prefix from ../tools/bootstrap_deps.sh)
+CMAKE_PREFIX_PATH="$PWD/../extern/install/<backend>" pip install .
+# Or a dev cmake build (nanobind found via the active interpreter; CMake 3.24+):
+cmake -S . -B build -DCMAKE_PREFIX_PATH="$PWD/../extern/install/<backend>" && cmake --build build -j
+
+# Activate venv and run flow verification (canonical scripts are scripts/verify_*_sdflow.py)
+source .venv/bin/activate
+PYTHONPATH=$PWD/build python scripts/verify_poiseuille_sdflow.py
+PYTHONPATH=$PWD/build python scripts/verify_periodic_spheres_sdflow.py
+PYTHONPATH=$PWD/build python scripts/verify_lid_cavity_sdflow.py
+```
+
+## Coding Style & Naming Conventions
+- C++ uses 2-space indentation and K&R-style braces; device code is plain Kokkos C++ in `.hpp` headers.
+- Python uses 4-space indentation.
+- Files and functions use `snake_case`; types/classes use `PascalCase`.
+- Kokkos device work is `parallel_for`/`parallel_reduce` over `Kokkos::View`s; keep functor types suffixed `_kernel`/`_op`.
+
+## Testing Guidelines
+- Tests are executable Python scripts under `tests/`.
+- Name tests as `test_*.py` and keep import paths pointed at `build/`.
+- No formal coverage target; prefer adding a small validation script when fixing numerics.
+
+## Commit & Pull Request Guidelines
+- Recent history uses Conventional Commit prefixes (`feat:`, `fix:`); follow this when possible.
+- Keep commits scoped to one change; include the numerical/physical intent in the message.
+- PRs should describe the change, list commands run, and attach plots or outputs if results change.
+
+## Agent Notes
+- For more detailed architecture and build guidance, see `CLAUDE.md`.

peclet_flow-0.1.0/CLAUDE.md

@@ -0,0 +1,246 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Performance-portable incompressible Navier-Stokes CFD solver for porous media simulations. Uses a staggered MAC grid with the Immersed Boundary Method (IBM) over complex geometries defined by Signed Distance Functions (SDF), with cut-cell pressure projection. Built on **Kokkos** — the same source runs on **CUDA, HIP (AMD/LUMI), and OpenMP** backends, selected at build time by the install prefix.
+
+**`flow` is THE solver** (`src/flow_bindings.cpp` → `peclet::flow::IbmSolver` in `src/flow_ibm.hpp`):
+cut-cell IBM physics on a staggered MAC grid, with a grid-independent geometric **multigrid** pressure
+solve, and a multi-rank MPI path (core grid halo). It solves the equations in **physical units**
+(density `rho`, dynamic viscosity `mu`, physical pressure `p`). See the "MPI / flow" section below.
+
+The CUDA implementation was **retired** (Kokkos became canonical, 2026-06): `flow` was validated
+bit-identical to the CUDA solver (machine-precision, and against the Zick & Homsy sphere-array Stokes drag)
+before the CUDA sources were deleted. Restore point: the git tag `pre-cuda-retirement`. The cut-cell IBM
+primitives live in `src/cut_cell_ibm.hpp`; the operator headers are `src/mac_*.hpp` + `src/flow_ibm.hpp`.
+
+**`pnm` is the pore-network-extraction module** (`src/pnm_bindings.cpp` + `src/pore_extraction.hpp`
+Kokkos compute + the pure-C++ `src/sdf_reader.cpp` VTI reader): `SDFReader`, `extract_pores`,
+`segment_volume`, `extract_topology_gpu` — the repo's namesake "pnm_from_sdf" feature, unrelated to the CFD solve.
+
+## Build Commands
+
+Kokkos is found via `find_package` against the bootstrapped install prefix
+(`../extern/install/<backend>`, built once by `../tools/bootstrap_deps.sh` — a **hard build dependency**;
+backend = `nvidia-cuda` / `host-openmp` / `lumi-hip`); **nanobind** is provisioned by the shared
+`SuiteNanobind` helper (found through the active Python interpreter, no cmakedir prefix needed). With
+`nvcc`, put it on `PATH` (`export PATH=/usr/local/cuda-13.2/bin:$PATH`).
+
+```bash
+source .venv/bin/activate
+# Canonical: build + install both modules (flow solver + pnm) via scikit-build-core.
+CMAKE_PREFIX_PATH="$PWD/../extern/install/nvidia-cuda" pip install .
+
+# Or a dev cmake build (single-rank Python modules):
+cmake -S . -B build -DCMAKE_PREFIX_PATH="$PWD/../extern/install/nvidia-cuda"
+cmake --build build -j
+# Output: build/peclet.flow.*.so (the CFD solver) + build/pnm.*.so (pore extraction)
+
+# OpenMP backend: same source, just swap the prefix (extern/install/host-openmp).
+```
+
+**Requirements:** Kokkos 5.x (C++20), CMake 3.24+, Python 3.10+, nanobind + scikit-build-core;
+`../core` (header-only) + MPI for the multi-rank test suite. The Kokkos/ArborX install prefix is
+produced by `../tools/bootstrap_deps.sh`.
+
+## Running Tests and Verification
+
+Drive `flow` verification from Python:
+```bash
+source .venv/bin/activate
+export PYTHONPATH=$PWD/build
+python scripts/verify_periodic_spheres_sdflow.py   # cut-cell Stokes through a sphere packing
+python scripts/verify_poiseuille_sdflow.py         # analytic parabola
+python scripts/verify_lid_cavity_sdflow.py         # lid cavity vs Ghia
+python scripts/verify_channel_sdflow.py            # developing channel
+python scripts/verify_bfs_sdflow.py                # backward-facing step
+python scripts/verify_chebyshev_sdflow.py          # Chebyshev pressure driver == MG-PCG
+python scripts/validate_zick_homsy_sdflow.py       # external ground truth (Z&H drag)
+```
+
+C++ kernel + multi-rank test suites (own `find_package` projects; build against the same prefix):
+```bash
+# Single-rank Kokkos kernel unit tests:
+cmake -S tests/kokkos -B build_kokkos -DCMAKE_PREFIX_PATH=$PWD/../extern/install/nvidia-cuda
+cmake --build build_kokkos -j && ctest --test-dir build_kokkos --output-on-failure   # 14 tests
+# Multi-rank (MPI) tests, np=1,2,4:
+cmake -S tests/kokkos_mpi -B build_kmpi -DCMAKE_PREFIX_PATH=$PWD/../extern/install/nvidia-cuda \
+  -DMPIEXEC_EXECUTABLE=/usr/bin/mpirun
+cmake --build build_kmpi -j && ctest --test-dir build_kmpi --output-on-failure       # 18 tests (6 x np)
+```
+
+Single-GPU **accuracy + efficiency regression suite** (grid-convergence + recorded solver-iteration
+counts, checked against a saved baseline so regressions are caught — Z&H sphere, random-sphere bed,
+hollow-ring bed): `PYTHONPATH=$PWD/build python tests/regression/sdflow_regression.py` (`--update` to
+re-record the baseline). See [`tests/regression/README.md`](tests/regression/README.md).
+
+Pore-network extraction (the `pnm` module): `python scripts/test_extraction.py`,
+`python scripts/verify_segmentation.py`.
+
+## Architecture
+
+### Memory Layout
+
+- Linear indexing: `I = x + y*nx + z*nx*ny` (x is fastest)
+- Python arrays: Fortran order `order='F'` with shape `(nx, ny, nz)`
+- Periodic boundaries with wrapping: `(x % res.x + res.x) % res.x`
+
+### Numerical Method (`flow`)
+
+The physical incompressible momentum equation `rho*(du/dt + (u.grad)u) = -grad(p) + mu*Lap(u) + f`, solved
+each step (semi-implicit), **scaled by 1/dt** (the "divided" convention — the operator is `(rho/dt)*I -
+mu*Lap`, well-conditioned at large dt / steady state):
+
+1. **Advection**: explicit Koren TVD, or implicit-FOU + deferred-correction TVD (`set_implicit_advection`)
+2. **Diffusion**: backward-Euler implicit, Red-Black Gauss-Seidel (or opt-in velocity multigrid)
+3. **Pressure projection**: `u = u* - grad(phi)`, `Lap(phi) = div(u*)`; physical pressure `p = (rho/dt)*phi`,
+   accumulated rotationally under the default incremental-pressure scheme. Geometric multigrid (V-cycle /
+   MG-PCG / Chebyshev).
+4. **IBM**: Robust-Scaled cut-cell method with D_rescale for near-wall handling.
+
+### Key Source Files
+
+All Kokkos, header-only (`namespace flow`), C++20.
+
+**`flow` (the CFD solver):**
+- `src/flow_ibm.hpp` - `peclet::flow::IbmSolver`: the solver (diffusion, projection, three pressure drivers, Picard, MPI)
+- `src/mac_cutcell_mg.hpp` - `CutcellMG`: geometric pressure MG (V-cycle / PCG / Chebyshev), MPI-folded
+- `src/mac_velocity_mg.hpp` - `VelocityMG`: velocity multigrid (staircase / upwind / domain-BC), MPI-folded
+- `src/mac_ibm.hpp`, `src/mac_cutcell.hpp`, `src/mac_pressure.hpp`, `src/mac_bc.hpp`, `src/mac_reductions.hpp` - IBM stencil, cut-cell openness, projection, domain BCs, reductions
+- `src/cut_cell_ibm.hpp` - the Robust-Scaled cut-cell IBM overlay (`poly_*`, K/M/X/Nbc/R, D_rescale)
+- `src/staggered_advection.hpp` - `sadv::advect`: staggered Koren TVD advection (+ implicit-FOU operator)
+- `src/flow_bindings.cpp` - the `flow` nanobind module: `peclet.flow.Solver` (staggered MAC, default) and
+  `peclet.flow.SolverColocated` (collocated/cell-centered velocities via the `GridLayout` policy + ABC
+  approximate projection — identical Python API; see [`doc/flow_colocated_plan.md`](doc/flow_colocated_plan.md))
+
+**`pnm` (pore-network extraction):**
+- `src/pore_extraction.hpp` (`namespace pnm`, Kokkos compute), `src/sdf_reader.cpp` / `.h` (pure-C++ VTI reader)
+- `src/pnm_bindings.cpp` - the `pnm` nanobind module (`SDFReader`, `extract_pores`, `segment_volume`, ...)
+
+## Python API Usage (`flow`)
+
+```python
+import peclet.flow
+s = peclet.flow.Solver(nx, ny, nz)
+s.set_rho(1.0); s.set_mu(0.01); s.set_dt(60.0)   # physical units; fix before geometry
+s.set_body_force(1e-2, 0, 0)                       # force per unit volume
+s.set_solid(sdf, cutcell_pressure=True, pressure_coarse="rediscretized")  # SDF [x,y,z], <0 inside
+for _ in range(n_steps):
+    s.step()
+u = s.get_u()   # 3-D numpy array [x,y,z];  p = s.get_p() is the physical pressure
+```
+See the "Pressure solver options" table below and `scripts/*_sdflow.py` for the full API.
+
+## Conventions
+
+- **SDF sign**: Negative inside solid, positive in fluid
+- **Kokkos kernels**: `parallel_for` / `parallel_reduce` over `Kokkos::View`s (`MDRangePolicy` for 3-D loops); device sources are `.hpp` compiled as C++ (the launch compiler routes through `nvcc`/`hipcc`), never `.cu`
+- **Staggered grid**: u at (i+1/2,j,k), v at (i,j+1/2,k), w at (i,j,k+1/2), p at cell centers
+
+## MPI / flow (the CFD solver, core integration)
+
+The **`flow`** solver (`peclet::flow::IbmSolver`) is built on the shared `core` library (sibling repo
+`../core`), whose **Kokkos** grid halo (`peclet::core::halo::GridHalo`) carries the
+multi-rank ghost exchange. The single-rank Python module is built by the main `CMakeLists.txt`; the
+multi-rank path is exercised by the `tests/kokkos_mpi` ctests (gated behind `PECLET_FLOW_MPI`, so the single-rank
+module is byte-identical). It was validated bit-identical (machine precision) to the retired CUDA solver
+and against external analytics.
+
+Key pieces (all `src/*.hpp`, Kokkos, header-only, `namespace flow`):
+- `peclet::core::halo::GridHalo` (core) — per-level ORB block ghost exchange for the
+  `double` cell-fields on the extended local block. cfd's x-fastest layout matches `peclet::core::Field3D`.
+- `staggered_advection.hpp` — `sadv::advect`: staggered Koren TVD advection, templated on a field accessor.
+- `flow_ibm.hpp` — `peclet::flow::IbmSolver`: the solver. `step()` does per-component implicit diffusion
+  (RB-GS or velocity-MG, halo exchange between sweeps) + cut-cell incremental-rotational projection, with
+  `set_advection`/`set_implicit_advection`, `set_body_force`, `set_solid` (cut-cell IBM no-slip), domain
+  BCs, and `initMpi(gnx,gny,gnz,comm)` for the multi-rank step.
+
+### Pressure solver options (the `flow` module)
+
+The cut-cell pressure Poisson is solved by a geometric **multigrid** (`mac_cutcell_mg.hpp`, `CutcellMG`)
+whose smoother is **Red-Black Gauss-Seidel** and whose coarse operator is the **rediscretized** cut-cell
+operator. Three outer drivers wrap that V-cycle — **select one per solver**:
+
+| driver | select with | use |
+|---|---|---|
+| **Standalone V-cycle** | default (neither below set) | multi-rank default. `set_pressure_multigrid(True, levels=1)` ⇒ pure RB-GS (no coarse grid) |
+| **MG-PCG** | `set_pressure_pcg(True, max_iter, rtol)` | **single-GPU default** (auto-enabled on 1 rank); ~1.2× faster than the V-cycle to a fixed tolerance |
+| **Chebyshev** | `set_pressure_chebyshev(True, max_iter, rtol)` | communication-light (no per-iteration global dot-products) — for large multi-GPU where PCG's reductions are latency-bound. ≈ PCG iteration count; bounds estimated once on step 1 |
+
+- **PCG and Chebyshev are mutually exclusive** (last set wins); either overrides the single-rank auto-PCG
+  default. With neither set, the solve is `n_pois` standalone V-cycles.
+- Coarse-operator mode: `set_solid(..., pressure_coarse="rediscretized")` (default; also `"galerkin"` /
+  `"const"`). `set_pressure_multigrid(on, levels)` sets the multigrid depth (`levels=1` == pure RB-GS).
+- `set_pressure_warmstart(True)` seeds each solve from the previous step's φ (opt-in, off by default).
+- Validated against Zick & Homsy SC-sphere drag. Design + benchmarks:
+  [`doc/flow_multigrid_plan.md`](doc/flow_multigrid_plan.md).
+
+### Domain boundary conditions
+
+Beyond periodic + IBM no-slip on immersed solids, flow has **native per-face domain BCs** (`mac_bc.hpp`):
+`set_domain_bc(face, type, vx, vy, vz)` for the 6 faces (0=−x,1=+x,2=−y,3=+y,4=−z,5=+z); `type` 0=periodic
+(default), 1=no-slip wall, 2=Dirichlet velocity / inflow, 3=outflow. Velocity ghosts are filled in the
+MAC-staggered convention. Tangential walls use a **face-fold** in the implicit diffusion (drop the wall
+face, fold its β into the diagonal + RHS) so `u_inner` stays implicit — no Gauss–Seidel lag; explicit
+advection keeps the reflection ghost. Call **before** geometry/first step. For a domain-BC problem with no
+immersed solid, use `set_pressure_geometry(all_fluid_sdf)` (the cut-cell pressure operator without the IBM).
+
+**Open boundaries** (outflow, or inflow with a non-zero normal velocity) split the face openness into two
+roles: the **operator** openness α (pressure matrix) is 0 at walls + inflow (Neumann) and open at outflow
+(Dirichlet p=0, ghost held at 0 → non-singular, mean-removal off); the **flux** openness β
+(divergence/correction) stays open at inflow + outflow so their flux is counted. Outflow velocity is
+zero-gradient (∂/∂n=0); the projection corrects the outflow face so mass leaves.
+
+**Non-uniform inlets:** `set_domain_bc_profile(face, profile[Nb,Nc,3])` prescribes a per-position inlet
+velocity over the face's perpendicular plane (sets the face to inflow). Used for a parabolic channel inlet
+or the **backward-facing step**, whose step is realized purely as the inlet condition — the developed
+parabola over the open upper half, zero over the step face (no immersed solid needed).
+
+**Validated:** lid-driven cavity vs Ghia et al. Re=100 to ~0.7% rms (`scripts/verify_lid_cavity_sdflow.py`);
+developing plane channel (uniform inlet → parabolic Poiseuille outlet, `u_max/U_mean`→1.5, exact mass
+conservation, machine-precision divergence; `scripts/verify_channel_sdflow.py`); backward-facing step
+(Gartling expansion-ratio-2, `scripts/verify_bfs_sdflow.py`) — reattachment `x_r/S` 5.3 (Re_S=100) → 8.3
+(Re_S=200) on the Armaly/Biswas curve, `PECLET_FLOW_BFS_RE800=1` pushes to the Gartling Re=800 benchmark.
+
+The **rediscretized geometric pressure multigrid is multilevel on these non-periodic domains** (not just the
+periodic/IBM case): each coarse level re-imposes the boundary face openness (Neumann wall/inflow → 0,
+Dirichlet outflow → open) and the trilinear prolongation fills the non-periodic boundary ghosts
+(Neumann → zero-gradient, Dirichlet → 0). Gated on `has_bc_`, so the periodic/IBM path is byte-identical.
+Convergence is grid-independent — e.g. a 256×64 channel at a fixed 10 V-cycles/step drives the flux
+divergence from `2e-3` (1 level) to `5e-7` (3 levels) at ~the same cost.
+
+**Semi-coarsening** handles thin (quasi-2D) grids: uniform 2:1 coarsening caps an `nz=4` grid at 2 levels,
+so `init(..., semi=true)` halves an axis only while it stays even and ≥2 — a thin axis freezes while the
+wide axes keep coarsening (`MGLevel::ratio`/`cfac`; the transfer + openness kernels take a per-axis
+`int3 ratio`, the operator uses per-axis `idx2/cfac²`). The solver enables it only for native-BC problems
+(`has_domain_bc_`, `semi_level_count`); the periodic/IBM porous path stays uniform + `clamp_levels`, so it
+is byte-identical. A quasi-2D 256×64×4 channel now builds up to 8 levels (was 2): raw V-cycle flux
+divergence at a fixed 8 cycles drops `1.7e-4`→`8.6e-13`. The BC verify scripts request `levels=8`
+(auto-capped). *Follow-ups:* convective outflow for unsteady wakes, multi-rank inlet-profile scatter
+(validated single-rank).
+
+Validated against analytics (Taylor–Green ~2e-15, Poiseuille, momentum conservation) **and against Zick &
+Homsy sphere-array drag**; the multi-rank step is bit-exact to the single-rank — **18 `tests/kokkos_mpi`
+ctests, real multi-rank np=1,2,4, on CUDA + OpenMP**.
+
+Build/test the multi-rank ctests:
+```bash
+export PATH=/usr/local/cuda-13.2/bin:$PATH
+cmake -S tests/kokkos_mpi -B build_kmpi \
+  -DCMAKE_PREFIX_PATH=$PWD/../extern/install/nvidia-cuda \
+  -DMPIEXEC_EXECUTABLE=/usr/bin/mpirun
+cmake --build build_kmpi -j
+ctest --test-dir build_kmpi --output-on-failure
+```
+**Force `-DMPIEXEC_EXECUTABLE=/usr/bin/mpirun`** — FindMPI may pick ParaView's bundled `mpiexec` on
+`PATH`, which launches the OpenMPI-linked test binaries as singletons (so `*_np4` silently runs 4×np=1).
+
+**Status:** `peclet::flow::IbmSolver`/`flow` is the full solver — the Robust-Scaled cut-cell IBM, a grid-independent
+geometric **multigrid** pressure solve (rediscretized cut-cell coarse operator; three selectable outer
+drivers), velocity multigrid, implicit-FOU + Picard, all domain BCs, and a bit-exact multi-rank step
+(`CutcellMG` + `VelocityMG` MPI-folded). The CUDA implementation is **retired** (restore tag
+`pre-cuda-retirement`). **Remaining open items:** the large-np scaling work — an **agglomerated coarse
+solve** and the communication-light **Chebyshev** accelerator's at-scale benchmark, both needing real
+multi-GPU hardware.

peclet_flow-0.1.0/CMakeLists.txt

@@ -0,0 +1,67 @@
+cmake_minimum_required(VERSION 3.24)
+project(peclet_flow LANGUAGES CXX)
+
+# Canonical cfd-gpu build: the Kokkos `sdflow` cut-cell IBM Navier-Stokes solver + the `pnm`
+# pore-network extraction, as importable Python modules. Kokkos provides the backend (CUDA / HIP / OpenMP),
+# selected by the install prefix (extern/install/<backend>, built by ../tools/bootstrap_deps.sh -- a HARD
+# build dependency).
+#
+# Build (single-rank Python modules); nanobind is found via the active interpreter (SuiteNanobind):
+#   cmake -S . -B build -DCMAKE_PREFIX_PATH="$PWD/../extern/install/nvidia-cuda"
+#   cmake --build build -j        ->  build/sdflow.*.so + build/pnm.*.so
+#
+# Multi-rank MPI is exercised by the tests/kokkos_mpi ctest suite (its own find_package project); the
+# single-rank kernel unit tests live in tests/kokkos. See CLAUDE.md.
+
+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 for a self-contained
+# sdist/wheel (cibuildwheel). 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" TPX_INC)
+
+# sdflow -- the cut-cell IBM Navier-Stokes solver (single-rank Python module).
+# NB_STATIC: bundle nanobind's runtime into the module (no shared libnanobind to ship); the Kokkos
+# device path is routed by the launch compiler regardless.
+# NOMINSIZE: nanobind's default -Os size optimization is rejected by nvcc ("'s': expected a number")
+# since the Kokkos device sources compile as CXX through the launch compiler.
+# The two extensions are assembled into the PEP-420 peclet namespace: the solver as `peclet.flow` (the
+# private `_flow` extension re-exported by peclet/flow/__init__.py) and pore extraction as
+# `peclet.flow.pnm`. The package __init__.py files are kept as plain files under packaging/ (OUTSIDE any
+# importable peclet/ dir, so an incomplete source package can never shadow the installed one) and staged
+# into <build>/peclet/... so `PYTHONPATH=<build> python …` (`import peclet.flow`) works in the dev loop
+# too. The SKBUILD install rules (guarded below) place them into the wheel.
+nanobind_add_module(sdflow NB_STATIC NOMINSIZE src/flow_bindings.cpp)
+set_target_properties(sdflow PROPERTIES OUTPUT_NAME _flow   # -> peclet.flow._flow (NB_MODULE(_flow))
+  LIBRARY_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/peclet/flow")
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/packaging/flow_init.py
+               ${CMAKE_CURRENT_BINARY_DIR}/peclet/flow/__init__.py COPYONLY)
+target_include_directories(sdflow PRIVATE src "${TPX_INC}")
+target_link_libraries(sdflow PRIVATE Kokkos::kokkos)
+
+# pnm -- pore-network extraction (Kokkos GPU compute + pure-C++ SDFReader VTI reader).
+nanobind_add_module(pnm NB_STATIC NOMINSIZE src/pnm_bindings.cpp src/sdf_reader.cpp)
+set_target_properties(pnm PROPERTIES OUTPUT_NAME _pnm       # -> peclet.flow.pnm._pnm (NB_MODULE(_pnm))
+  LIBRARY_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/peclet/flow/pnm")
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/packaging/flow_pnm_init.py
+               ${CMAKE_CURRENT_BINARY_DIR}/peclet/flow/pnm/__init__.py COPYONLY)
+target_include_directories(pnm PRIVATE src "${TPX_INC}")
+target_link_libraries(pnm PRIVATE Kokkos::kokkos)
+
+# --- pip / scikit-build-core install rule -------------------------------------------------------
+if(DEFINED SKBUILD)
+  install(TARGETS sdflow LIBRARY DESTINATION peclet/flow COMPONENT python)
+  install(TARGETS pnm    LIBRARY DESTINATION peclet/flow/pnm COMPONENT python)
+  install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/packaging/flow_init.py
+          DESTINATION peclet/flow RENAME __init__.py COMPONENT python)
+  install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/packaging/flow_pnm_init.py
+          DESTINATION peclet/flow/pnm RENAME __init__.py COMPONENT python)
+endif()

peclet_flow-0.1.0/GEMINI.md

@@ -0,0 +1,2 @@
+# Gemini Added Memories
+- Workflow Protocol: For any issue, I must follow this sequence: 1. Form Hypothesis, 2. Investigate, 3. Report Findings, 4. Propose Plan, 5. **STOP AND WAIT for User Agreement**, 6. Execute Plan. I am strictly forbidden from combining Step 4 and 6. I must never assume approval.

peclet_flow-0.1.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.