peclet-pnm 0.1.0__tar.gz

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

@@ -0,0 +1,74 @@
+name: CI
+
+# Build the Kokkos (OpenMP/Serial) backend from source, then build the peclet.pnm module and run the
+# extraction smoke test on a synthetic sphere-lattice SDF. GPU (CUDA/HIP) backends are not
+# exercisable on free GitHub runners; the portable host build catches the vast majority of
+# regressions (the Kokkos source is backend-agnostic).
+
+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@v7
+
+      - 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 nanobind numpy
+
+      - name: Cache Kokkos install
+        id: kokkos-cache
+        uses: actions/cache@v6
+        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 the pnm module
+        run: |
+          cmake -S . -B build \
+            -DCMAKE_PREFIX_PATH="$GITHUB_WORKSPACE/kokkos-install"
+          cmake --build build -j
+
+      - name: Extraction smoke test (synthetic sphere-lattice SDF)
+        run: |
+          PYTHONPATH=$PWD/build python3 - <<'EOF'
+          import numpy as np
+          import peclet.pnm as pnm
+          print("peclet.pnm on", pnm.execution_space)
+          # 2x2x2 lattice of solid spheres in a periodic-ish box: pores at the interstices.
+          n, R = 32, 10.0
+          z, y, x = np.meshgrid(*(np.arange(n, dtype=np.float32),) * 3, indexing="ij")
+          sdf = np.full((n, n, n), np.inf, dtype=np.float32)
+          for cz in (8, 24):
+              for cy in (8, 24):
+                  for cx in (8, 24):
+                      d = np.sqrt((x - cx) ** 2 + (y - cy) ** 2 + (z - cz) ** 2) - R
+                      sdf = np.minimum(sdf, d.astype(np.float32))
+          pores, seg, conns = pnm.extract_pore_network(sdf, [0.0, 0.0, 0.0], [1.0, 1.0, 1.0])
+          print(f"{len(pores)} pores, {len(set(seg))} segments, {len(conns)} connections")
+          assert len(pores) > 0 and len(conns) > 0
+          # Staged path agrees on the pore count.
+          assert len(pnm.extract_pores(sdf, [0.0] * 3, [1.0] * 3)) == len(pores)
+          EOF

peclet_pnm-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@v7
+
+      - 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@v5
+        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@v5

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

@@ -0,0 +1,56 @@
+name: Release
+
+# Build + publish peclet-pnm to PyPI on a version tag: sdist + self-contained OpenMP CPU wheels
+# (FetchContent Kokkos OpenMP+Serial, PECLET_VENDOR_DEPS=ON from [tool.cibuildwheel]).
+# Uses PyPI Trusted Publishing (OIDC): register this workflow as the publisher for `peclet-pnm` on
+# PyPI first — no API token secret needed. (A CUDA wheel variant à la peclet-flow-cu13 can be added
+# later; the CMake rpath hook PECLET_CUDA_RUNTIME_WHEEL is already in place.)
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        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@v7
+      # 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
+        with:
+          skip-existing: true

peclet_pnm-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Build directories
+build/
+build_*/
+*.so
+*.a
+*.o
+*.log
+
+# Python
+__pycache__/
+*.pyc
+.venv
+venv/
+*.egg-info/
+dist/
+
+# IDE/Editor
+.vscode/
+.idea/
+*.swp
+*~
+.DS_Store
+
+# CMake
+CMakeCache.txt
+CMakeFiles/
+cmake_install.cmake
+_deps/
+.cache/
+
+# Data / output assets
+data/
+*.vti
+*.vtp
+*.edges
+*.png
+output/

peclet_pnm-0.1.0/CITATION.cff

@@ -0,0 +1,19 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it using the metadata below."
+title: "peclet-pnm: GPU pore-network extraction from signed-distance-field geometry"
+abstract: >-
+  Pore-network extraction from a signed-distance-field (SDF) description of a porous solid: pore
+  detection (local SDF maxima + weighted centroids), marker-controlled watershed segmentation of the
+  pore space (union-find CCL + flood fill), and pore-to-pore throat topology. Written in Kokkos C++
+  (CUDA/HIP/OpenMP) and exposed to Python via nanobind as peclet.pnm. Part of the peclet suite;
+  split out of peclet-flow (its former peclet.flow.pnm module).
+type: software
+authors:
+  - family-names: Peters
+    given-names: Frank
+    email: e.a.j.f.peters@gmail.com
+    affiliation: "Eindhoven University of Technology"
+version: 0.1.0
+date-released: 2026-07-25
+license: MIT
+repository-code: "https://github.com/computational-chemical-engineering/peclet-pnm"

peclet_pnm-0.1.0/CLAUDE.md

@@ -0,0 +1,91 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`peclet.pnm` — pore-network extraction from SDF geometry, as an importable Python module. Split out
+of `peclet-flow` (2026-07; it was `peclet.flow.pnm`, the original "pnm_from_sdf" feature). The
+compute is **Kokkos** (CUDA / HIP / OpenMP — backend selected by the install prefix); the VTI reader
+is pure C++. Part of the peclet suite (see `../CLAUDE.md` and `../docs/` for suite-wide conventions).
+
+**Sources** (all under `src/`):
+- `pore_extraction.hpp` — `namespace pnm`, header-only Kokkos compute: pore detection (local SDF
+  maxima + weighted centroid), marker-controlled watershed segmentation (marker init → union-find
+  CCL → flood fill), gradient-path pore basins, boundary-pair throat topology. Device kernels live
+  in the `.hpp` compiled as C++ (never `.cu`).
+- `pnm_bindings.cpp` — the nanobind module `peclet.pnm._pnm`: `SDFReader`, `extract_pores`,
+  `segment_volume`, `extract_topology_gpu`, and the fused `extract_pore_network` (SDF uploaded once,
+  segmentation device-resident across stages). Uses core's zero-copy View↔ndarray bridge.
+- `sdf_reader.{h,cpp}` — pure-C++ VTI (VTK ImageData) reader, backend-free.
+- `pore_extraction.hpp` also holds **`extract_network_flow_k`** (binding `extract_network_flow`):
+  throat flow rates + pore-center pressures from a peclet.flow MAC field — the method from the
+  Voronoi PNM (`~/Codes/pnm_voronoi`). KEY FACTS: flow's `u(i,j,k)` is the **-x face** of cell
+  (i,j,k) and the conserved flux is `ox·u·A` (openness-weighted; `cutcell_pressure=True`
+  REQUIRED or all openness is 0); fluxes accumulate on **flow basins** (gradient ascent from
+  EVERY cell — seg-keyed accumulation lets near-wall staircase flux bypass throats, measured 6%);
+  throat dp uses a throat-anchored two-leg min-image (single min-image is ambiguous at L/2);
+  per-pore residual ~ solver tolerance is the built-in correctness check. Validated:
+  `scripts/verify_network_flow.py` (|Q|=F to 1e-11 on tube networks, g>0, Kirchhoff exact).
+  On loose packings per-throat g=Q/dp scatters (intra-pore viscous variation ~ throat drops —
+  real physics, not a bug; the p field's grid-scale roughness μ∇²u·h ≈ 20× the macro gradient).
+  GHOST-CELL IBM (`set_ghost_projection`): pass flow's `get_ox_proj/...` (binary COUPLED
+  openness); bookkeeping is truncation-accurate there (ghost IBM is NOT locally conservative at
+  the wall — pore_residual = wall leak, 3.2e-2·F at r=4h, order ~2.7). MPI:
+  `extract_network_flow_mpi` (pore_extraction_mpi.hpp) — flow-basin labels resolved by
+  propagating the LABEL with the hold-at-ghost finalization trick; global network identical on
+  every rank. GOTCHA: periodic-image decisions (face min-image + the throat dp image count) MUST
+  anchor on integer peak-voxel coords / snapped-integer arithmetic — float-centroid anchoring
+  flips images at exactly L/2 under CUDA FMA wobble (measured flaky np4 failures on symmetric
+  lattices). THROATS ARE PER-PATCH (parallel throats resolved): face-CCL keyed by min global
+  face id (fid = 3*gid+d); CORE tier = both cells FLUID-centered (an OPENNESS threshold cannot
+  separate throats bridged by wall films — staircase faces reach opn ~0.7; the fluid-centered
+  criterion is geometric and parameter-free); films attach to the min reachable core patch by
+  Jacobi min-propagation (cannot bridge two cores), unreachable films form their own patches.
+- `pore_extraction_mpi.hpp` — the **distributed** pipeline (gated `PECLET_PNM_MPI`): core ORB
+  decomposition + g=1 `GridHalo` exchange; labels are GLOBAL voxel ids so every fixpoint is
+  decomposition-independent → **bit-exact to single-rank**. Stage design: local union-find CCL +
+  one-shot boundary-graph merge (allgathered surface pairs, host union-find); Jacobi flood
+  (sweep-for-sweep = the single-rank Jacobi flood); gradient roots via hold-at-ghost pointer
+  jumping with a `~root` finalization marker (NEVER store a remote mid-chain gid — that strands
+  the chase outside the ghost ring and fragments basins; measured on plateau-heavy fields);
+  renumber by global min-appearance gid (= single-rank first-encounter order).
+
+## Build & test
+
+```bash
+# nanobind found via the active interpreter; Kokkos from the suite prefix
+# (../extern/install/<backend>, built once by ../tools/bootstrap_deps.sh).
+cmake -S . -B build -DCMAKE_PREFIX_PATH="$PWD/../extern/install/nvidia-cuda"
+cmake --build build -j            # -> build/peclet/pnm/_pnm.*.so
+PYTHONPATH=$PWD/build python scripts/test_extraction.py <sdf.vti>      # pore extraction smoke test
+PYTHONPATH=$PWD/build python scripts/verify_segmentation.py <sdf.vti>  # watershed + topology
+# Canonical install: CMAKE_PREFIX_PATH=... pip install .   (-> peclet.pnm)
+```
+
+Without a prefix, `cmake/PecletDeps.cmake` vendors Kokkos (OpenMP+Serial) + the peclet-core headers
+via FetchContent (self-contained wheel path, `PECLET_VENDOR_DEPS=ON` in cibuildwheel). Keep the
+`PECLET_*_TAG` pins in lockstep with `../tools/bootstrap_deps.sh`.
+
+Multi-rank (MPI): add `-DPECLET_PNM_MPI=ON` to expose `mpi_rank`/`mpi_size`/`mpi_block` +
+`extract_pore_network_mpi` (collective; see README). The C++ MPI ctests (np=1,2,4, distributed vs
+single-rank oracle, bit-exact):
+```bash
+cmake -S tests/kokkos_mpi -B build_kmpi -DCMAKE_PREFIX_PATH=$PWD/../extern/install/nvidia-cuda \
+  -DMPIEXEC_EXECUTABLE=/usr/bin/mpirun          # FORCE mpirun — ParaView's mpiexec runs singletons
+cmake --build build_kmpi -j && ctest --test-dir build_kmpi --output-on-failure
+```
+GPU pore-centroid caveat: nvcc FMA-contracts the centroid accumulation differently in the oracle
+vs distributed kernels, so pore POSITIONS are compared to 1e-5·spacing on CUDA (bitwise on
+OpenMP); seg ids, radii and connections are bitwise everywhere. The single-rank flood fill is
+deliberately Jacobi (double-buffered) — deterministic AND what the distributed flood matches
+sweep-for-sweep; don't "optimize" it back to in-place.
+
+## Conventions
+
+- SDF sign: **negative inside solid**, positive in the pore space (suite-wide).
+- Python arrays are `(Nz, Ny, Nx)` C-order (x fastest — contiguous with the flat x-fastest layout);
+  `origin`/`spacing` tuples are **z-y-x**. `segment_volume` returns a flat label vector.
+- `Kokkos::initialize` happens at import; `Kokkos::finalize` is registered via `atexit`
+  (REQUIRED on CUDA — see the comment in `pnm_bindings.cpp`).
+- Test VTI inputs live in the suite (e.g. `../flow/data/packing_ring.vti`), not in this repo.

peclet_pnm-0.1.0/CMakeLists.txt

@@ -0,0 +1,79 @@
+cmake_minimum_required(VERSION 3.24)
+project(peclet_pnm LANGUAGES CXX)
+
+# peclet.pnm — pore-network extraction from SDF geometry (Kokkos GPU compute + the pure-C++ SDFReader
+# VTI reader), as an importable Python module. Split out of peclet-flow (2026-07): the CFD solve lives
+# in peclet.flow; this package is the "pnm_from_sdf" extraction feature on its own.
+#
+# The Kokkos backend (CUDA / HIP / OpenMP) is selected by the install prefix
+# (extern/install/<backend>, built by ../tools/bootstrap_deps.sh), exactly like flow/dem.
+#
+# Build (nanobind is found via the active interpreter):
+#   cmake -S . -B build -DCMAKE_PREFIX_PATH="$PWD/../extern/install/nvidia-cuda"
+#   cmake --build build -j        ->  build/peclet/pnm/_pnm.*.so   (import as peclet.pnm)
+
+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()
+
+# Redistributable single-GPU CUDA wheel: libcudart is provided by the `nvidia-cuda-runtime` PyPI
+# dependency (installed to site-packages/nvidia/cu13/lib), not the system. Mirrors peclet-flow.
+option(PECLET_CUDA_RUNTIME_WHEEL "RPATH the module to the nvidia-cuda-runtime wheel's libcudart" OFF)
+
+# Multi-rank: -DPECLET_PNM_MPI=ON links MPI + exposes mpi_rank/mpi_size/mpi_block and
+# extract_pore_network_mpi (the distributed extraction on the core ORB decomposition, bit-exact to
+# single-rank). OFF (default) leaves the single-rank module byte-identical. Mirrors PECLET_FLOW_MPI.
+option(PECLET_PNM_MPI "Build the pnm module with the distributed (MPI) extraction exposed" OFF)
+
+# 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)
+
+# pnm — pore-network extraction (Kokkos compute + pure-C++ SDFReader VTI reader).
+# NB_STATIC: bundle nanobind's runtime into the module. NOMINSIZE: nanobind's -Os is rejected by nvcc
+# since the Kokkos device sources compile as CXX through the launch compiler. The extension is
+# assembled into the PEP-420 peclet namespace as `peclet.pnm` (private `_pnm` re-exported by
+# peclet/pnm/__init__.py, kept as a plain file under packaging/ and staged into <build>/peclet/... so
+# `PYTHONPATH=<build> python …` works in the dev loop too).
+nanobind_add_module(pnm NB_STATIC NOMINSIZE src/pnm_bindings.cpp src/sdf_reader.cpp)
+set_target_properties(pnm PROPERTIES OUTPUT_NAME _pnm        # -> peclet.pnm._pnm (NB_MODULE(_pnm))
+  LIBRARY_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/peclet/pnm")
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/packaging/pnm_init.py
+               ${CMAKE_CURRENT_BINARY_DIR}/peclet/pnm/__init__.py COPYONLY)
+target_include_directories(pnm PRIVATE src "${TPX_INC}")
+target_link_libraries(pnm PRIVATE Kokkos::kokkos)
+# HIP/lld strictness: nanobind's --gc-sections can drop Kokkos SharedAllocationRecord<HIPSpace>
+# vtables it only later finds referenced. Keep sections on HIP (nvcc/ld is lenient).
+if(Kokkos_ENABLE_HIP)
+  target_link_options(pnm PRIVATE -Wl,--no-gc-sections)
+endif()
+
+# Distributed (MPI) extraction: compile the binding TU with the gating flag + link MPI (the core
+# grid halo lives in the header-only TPX_INC). Mirrors flow's PECLET_FLOW_MPI wiring.
+if(PECLET_PNM_MPI)
+  find_package(MPI REQUIRED COMPONENTS CXX)
+  target_compile_definitions(pnm PRIVATE PECLET_PNM_MPI=1)
+  target_link_libraries(pnm PRIVATE MPI::MPI_CXX)
+  message(STATUS "pnm: distributed extraction ENABLED (MPI)")
+endif()
+
+# Redistributable CUDA wheel: point the module at the nvidia-cuda-runtime wheel's libcudart via a
+# relative $ORIGIN RPATH (peclet/pnm -> site-packages -> nvidia/cu13/lib).
+if(PECLET_CUDA_RUNTIME_WHEEL)
+  set_target_properties(pnm PROPERTIES
+    INSTALL_RPATH "$ORIGIN/../../nvidia/cu13/lib" INSTALL_RPATH_USE_LINK_PATH OFF)
+endif()
+
+# --- pip / scikit-build-core install rule -------------------------------------------------------
+if(DEFINED SKBUILD)
+  install(TARGETS pnm LIBRARY DESTINATION peclet/pnm COMPONENT python)
+  install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/packaging/pnm_init.py
+          DESTINATION peclet/pnm RENAME __init__.py COMPONENT python)
+endif()

peclet_pnm-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.

peclet_pnm-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: peclet-pnm
+Version: 0.1.0
+Summary: peclet.pnm — Kokkos pore-network extraction from SDF geometry (pores, watershed segmentation, throat topology)
+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-pnm
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.20
+Description-Content-Type: text/markdown
+
+# peclet-pnm
+
+**`peclet.pnm` — GPU pore-network extraction from SDF geometry.**
+
+Given a signed-distance-field (SDF) description of a porous solid (negative inside the solid,
+positive in the pore space), `peclet.pnm` extracts the pore network:
+
+- **`SDFReader`** — pure-C++ VTI (VTK ImageData) reader for SDF volumes.
+- **`extract_pores`** — pore detection: local maxima of the SDF + weighted centroids and radii.
+- **`segment_volume`** — marker-controlled watershed segmentation of the pore space
+  (marker init → union-find connected-component labelling → flood fill).
+- **`extract_topology_gpu`** — pore-to-pore connectivity (throats) from boundary pairs between basins.
+- **`extract_pore_network`** — the fused pipeline (SDF uploaded once, segmentation device-resident
+  across all three stages): returns `(pores, segmentation, connections)` in one call.
+
+The compute is [Kokkos](https://github.com/kokkos/kokkos) — the same source runs on **CUDA, HIP, and
+OpenMP** backends, selected at build time by the install prefix. Part of the
+[peclet](https://github.com/computational-chemical-engineering/peclet) suite; split out of
+[peclet-flow](https://github.com/computational-chemical-engineering/peclet-flow) (its former
+`peclet.flow.pnm` module — the repo's original "pnm_from_sdf" feature).
+
+## Install / build
+
+```bash
+# From the peclet suite checkout (Kokkos prefix bootstrapped once by ../tools/bootstrap_deps.sh):
+CMAKE_PREFIX_PATH="$PWD/../extern/install/nvidia-cuda" pip install .
+
+# Or a dev cmake build (nanobind found via the active interpreter):
+cmake -S . -B build -DCMAKE_PREFIX_PATH="$PWD/../extern/install/nvidia-cuda"
+cmake --build build -j            # -> build/peclet/pnm/_pnm.*.so ; PYTHONPATH=$PWD/build to import
+```
+
+Without a Kokkos prefix on `CMAKE_PREFIX_PATH`, the build vendors Kokkos (OpenMP+Serial) via
+FetchContent, so `pip install .` works standalone on any Linux with a C++20 toolchain.
+
+## Usage
+
+```python
+import peclet.pnm as pnm
+
+sdf_3d, origin_zyx, spacing_zyx = pnm.SDFReader.read_vti("packing.vti")  # (Nz,Ny,Nx) C-order
+pores = pnm.extract_pores(sdf_3d, origin_zyx, spacing_zyx)               # Pore(x,y,z,radius) list
+seg = pnm.segment_volume(sdf_3d, spacing_zyx)                            # flat per-voxel pore label
+conns = pnm.extract_topology_gpu(seg, list(sdf_3d.shape))                # [(label_a, label_b), ...]
+
+# or fused (SDF uploaded once, segmentation stays device-resident across stages):
+pores, seg, conns = pnm.extract_pore_network(sdf_3d, origin_zyx, spacing_zyx)
+```
+
+Conventions: the SDF array is `(Nz, Ny, Nx)` C-order (x fastest), `origin`/`spacing` are z-y-x;
+SDF sign is negative inside the solid — see the suite's `docs/CONVENTIONS.md`.
+
+Smoke tests: `python scripts/test_extraction.py <sdf.vti>` and
+`python scripts/verify_segmentation.py <sdf.vti>` (writes a labelled `.vti` + a pore-pair edge list).
+
+## Network flow: throat flow rates + pore pressures from a DNS
+
+`extract_network_flow` turns a converged [peclet-flow](https://github.com/computational-chemical-engineering/peclet-flow)
+velocity/pressure field on the same grid into pore-network flow data — the method carried over
+from the Voronoi-tessellation PNM of sphere packings (`pnm_voronoi`), where the throat flow was
+∫u·n over the Voronoi facet and the pore pressure a trilinear sample at the pore center:
+
+```python
+s = peclet.flow.Solver(nx, ny, nz)
+...; s.set_body_force(fx, 0, 0); s.set_solid(sdf_xyz, cutcell_pressure=True); ...steps...
+net = pnm.extract_network_flow(
+    sdf_zyx, origin_zyx, spacing_zyx,
+    s.get_uf().T, s.get_vf().T, s.get_wf().T, s.get_p().T,   # zero-copy transposes to zyx
+    s.get_ox().T, s.get_oy().T, s.get_oz().T,                # cut-cell face openness
+    grad_p_zyx=[0, 0, -fx])                                  # body force f == -grad p_macro
+net["throat_flow"]     # Q through each pore-pore interface (o·u·A summed over MAC faces)
+net["pore_pressure"]   # periodic p interpolated at each pore center (basin SDF peak)
+net["throat_dp"]       # total-pressure drop P_i - P_j (periodic parts + macro gradient
+                       # along the throat-anchored min-image path)
+net["pore_residual"]   # signed flux over each pore's whole boundary — ~ solver tolerance
+```
+
+On the voxel network the throat integral is exact: a throat is a set of grid-aligned MAC faces
+and the openness-weighted face velocity is the discrete flux carrier, so per-pore mass balance
+holds to the pressure-solve tolerance (`pore_residual` is the built-in check). Fluxes are
+accumulated on **flow basins** (gradient-ascent assignment of *every* cell, including cut cells
+whose center is inside the solid) — keyed on the segmentation labels alone, the near-wall
+staircase flux would bypass the interface (measured 6% on a tube).
+
+**Both IBM variants are supported.** With the cut-cell IBM the bookkeeping is machine-exact
+(pass `get_ox()...`). With the **ghost-cell IBM** (`set_ghost_projection(True)`) pass flow's
+`get_ox_proj()/get_oy_proj()/get_oz_proj()` — the binary (COUPLED) openness the ghost projection
+conserves. Ghost-cell IBM is pointwise 2nd-order but not locally mass-conserving at the wall, so
+there the network data is truncation-accurate: `pore_residual` becomes the per-pore wall leak
+(measured 3.2e-2·F at a 4-cell tube radius, converging at order ~2.7 under refinement).
+
+**MPI:** `extract_network_flow_mpi(sdf_local, global_shape_zyx, ..., u_local, ...)` runs the whole
+pipeline distributed on the core ORB blocks (fields from a distributed peclet.flow run on the
+same decomposition); every rank returns the identical global network. Matches the single-rank
+result to accumulation-order tolerance (`tests/kokkos_mpi/test_pnm_flow_mpi`, np = 1, 2, 4).
+
+Validated in `scripts/verify_network_flow.py` (chamber-tube chain + asymmetric tube lattice +
+the ghost-IBM chain, DNS by peclet.flow): every throat carries the DNS flux to ~1e-11 relative
+(cut-cell), residuals ~1e-12·F, g = Q/dp > 0 on all throats, and the dp sum around each loop
+equals the macroscopic drop.
+`scripts/demo_network_flow_packing.py` runs the pipeline on a real sphere packing.
+
+**Throats are per-patch:** a throat is a *connected patch* of interface faces (CCL over the
+interface, core faces = both cells fluid-centered, wall-film faces attached by propagation), so
+two disjoint interfaces between the same two pores — e.g. two parallel tubes, or a direct contact
+plus one through the periodic wrap — are separate parallel throats and the throat list can repeat
+a pore pair (validated: two capsules of different radii report two (1,2) throats whose fluxes sum
+to the DNS flux exactly). Remaining caveat: on loose packings (porosity ≳ 0.6) intra-pore
+pressure variation is comparable to throat drops, so per-throat g = Q/dp scatters — a property of
+the point-pressure PNM abstraction, not of the extraction.
+
+## Distributed (MPI) extraction
+
+Built with `-DPECLET_PNM_MPI=ON`, the module also runs the whole pipeline **multi-rank**: the SDF
+is decomposed over ranks by the shared peclet-core ORB (the same deterministic partition flow/dem
+use), every stage runs per-rank on a 1-cell ghost layer (core `GridHalo` exchange), and the result
+is **bit-exact to the single-rank pipeline** — labels are global voxel ids, so the CCL fixpoint,
+the watershed flood (Jacobi), the gradient-path pore basins, and the renumbering are all
+decomposition-independent.
+
+```python
+# mpirun -np 4 python extract.py
+import peclet.pnm as pnm
+origin, shape = pnm.mpi_block(global_shape_zyx)      # this rank's ORB block of the global grid
+local = sdf[origin[0]:origin[0]+shape[0], origin[1]:origin[1]+shape[1], origin[2]:origin[2]+shape[2]]
+pores, seg, conns = pnm.extract_pore_network_mpi(local, global_shape_zyx, origin_zyx, spacing_zyx)
+# pores: the pores whose peak this rank owns; seg: this rank's block; conns: global (identical everywhere)
+```
+
+Validated by `tests/kokkos_mpi` (ctest, np = 1, 2, 4, OpenMP + CUDA): per-voxel segmentation ids,
+the pore set, and the connection list all match the single-rank oracle exactly (pore centroid
+positions to 1e-5·spacing on GPU — FMA contraction noise; radii and everything integer bitwise).
+
+## License
+
+MIT.