peclet 0.1.0__tar.gz

peclet-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+# Phase 0 toolchain artifacts
+/build/
+/extern/
+
+# MkDocs site output (built in CI, published to Pages)
+/site/

peclet-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-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: peclet
+Version: 0.1.0
+Summary: GPU-accelerated & parallel simulation of transport phenomena (CFD, DEM, Voronoi) — CPU family metapackage
+Project-URL: Homepage, https://github.com/computational-chemical-engineering/peclet
+Project-URL: Documentation, https://github.com/computational-chemical-engineering/peclet
+Author-email: Frank Peters <e.a.j.f.peters@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: peclet-dem==0.1.0
+Requires-Dist: peclet-flow==0.1.0
+Requires-Dist: peclet-morton==0.1.0
+Requires-Dist: peclet-voro==0.1.0
+Provides-Extra: mpi
+Requires-Dist: peclet-core==0.1.0; extra == 'mpi'
+Description-Content-Type: text/markdown
+
+# peclet
+
+A suite of codes for **simulation of transport phenomena** — Eulerian (CFD/Navier–Stokes), Lagrangian
+(DEM/particle packing) and mixed (Voronoi) methods — sharing one MPI **block domain decomposition**
+with efficient **asynchronous ghost-layer exchange**, **SDF**-described solids, a common **immersed
+boundary** methodology, **GPU** support, and **Python bindings**.
+
+The name nods to the [Péclet number](https://en.wikipedia.org/wiki/P%C3%A9clet_number) — the ratio of
+advective to diffusive transport, the dimensionless heart of transport phenomena.
+
+📖 **Documentation site:** <https://computational-chemical-engineering.github.io/peclet/> — the suite's front
+door (design docs + install/deployment guide + links to each code's Doxygen API). Built from `docs/`
+via MkDocs ([mkdocs.yml](mkdocs.yml)).
+
+This is an **umbrella repository**: each code is a git **submodule** (its own repo and history); this
+repo pins compatible commits and holds the shared design docs.
+
+## Clone
+
+```bash
+git clone --recursive git@github.com:computational-chemical-engineering/peclet.git
+# or, after a plain clone:
+git submodule update --init --recursive
+```
+
+## Layout
+
+| Submodule | Role |
+|-----------|------|
+| `core/` | **Shared infrastructure** (header-only C++20 + MPI, optional Kokkos): ORB block decomposition, async grid ghost-layer exchange + Lagrangian particle migration/ghosts, SDF geometry, VTI I/O. Every method depends on it. |
+| `flow/` | Eulerian **Kokkos** incompressible Navier–Stokes (porous media; staggered MAC grid + cut-cell IBM). Complete, validated, MPI-optional distributed solver on `core`; `pnm` is its pore-network-extraction module. |
+| `dem/` | Lagrangian **Kokkos + ArborX** DEM/XPBD particle packing. Full XPBD step with a validated distributed `step_mpi` (core particle halo). |
+| `voro/` | Mixed Lagrangian/Eulerian dynamic 3D Voronoi tessellation (header-only C++17; periodic & Lees–Edwards). |
+| `morton/` | Morton/Z-order spatial-index primitive — arithmetic directly in Morton space (header-only C++17 + BMI2/AVX-512, Python). |
+
+Both GPU codes are **Kokkos**-based; the same source runs on CUDA, HIP (AMD/LUMI), and OpenMP backends,
+chosen by the bootstrapped install prefix (`tools/bootstrap_deps.sh`). The reusable parts of the original
+`block_decomposer` prototype were extracted into `core/`.
+
+## Shared design docs
+
+`docs/` is the cross-code contract every method follows:
+[ARCHITECTURE](docs/ARCHITECTURE.md) · [CONVENTIONS](docs/CONVENTIONS.md) · [STYLE](docs/STYLE.md) ·
+[INTERFACES](docs/INTERFACES.md) · [ROADMAP](docs/ROADMAP.md) ·
+[PORTABILITY](docs/PORTABILITY.md). See `CLAUDE.md` for an agent-facing overview.
+
+## Install & run (Python)
+
+Everything ships under one **`peclet` namespace** — installable parts of one family:
+
+| PyPI package | Import | Role |
+|---|---|---|
+| `peclet-morton` | `peclet.morton` | Morton/Z-order spatial index |
+| `peclet-flow` | `peclet.flow` (+ `.pnm`) | Eulerian incompressible Navier–Stokes solver |
+| `peclet-dem` | `peclet.dem` | Lagrangian DEM/XPBD particle packing |
+| `peclet-voro` | `peclet.voro` | Dynamic Voronoi tessellation + mesh generator |
+| `peclet-core` | `peclet.core` (`.mpi`, `.amr`) | Shared infra (particle halo, AMR) — sdist only |
+| `peclet` | — | metapackage: `pip install peclet` pulls the CPU family |
+
+**Multicore CPU (OpenMP):** the compute packages ship **self-contained wheels** — `pip install peclet`
+(or an individual `pip install peclet-flow`) just works and runs multi-threaded (`OMP_NUM_THREADS`).
+
+**GPU (CUDA/HIP) and multi-rank MPI:** a portable binary wheel is impossible (arch × CUDA/ROCm × MPI-ABI),
+so you build the packages from source against a Kokkos prefix, or use a container. Because the backend
+(Serial / OpenMP / CUDA / HIP) is compiled in, you build for your hardware —
+[**docs/DEPLOYMENT.md**](docs/DEPLOYMENT.md) is the guide: the backend×MPI matrix, `pip install` recipes
+per environment, and **Apptainer containers** for Snellius (CUDA) and LUMI (HIP) in [`containers/`](containers).
+
+## Continuous integration & docs
+
+Each submodule carries its own `.github/workflows/`: a **CI** workflow (build + test where feasible —
+`core` and `morton` run full CPU/MPI suites; `flow` and `dem` build the Kokkos OpenMP host
+backend) and a **Documentation** workflow that builds the Doxygen API docs and publishes them to that
+repo's GitHub Pages. Enabling Pages once per repo (Settings → Pages → "Source: GitHub Actions") is the
+only manual step.
+
+## Note on submodule pins
+
+This umbrella pins each submodule to a compatible commit on `main`. Update to the latest upstream with
+`git submodule update --remote` followed by a commit here that bumps the pointers.

peclet-0.1.0/README.md

@@ -0,0 +1,80 @@
+# peclet
+
+A suite of codes for **simulation of transport phenomena** — Eulerian (CFD/Navier–Stokes), Lagrangian
+(DEM/particle packing) and mixed (Voronoi) methods — sharing one MPI **block domain decomposition**
+with efficient **asynchronous ghost-layer exchange**, **SDF**-described solids, a common **immersed
+boundary** methodology, **GPU** support, and **Python bindings**.
+
+The name nods to the [Péclet number](https://en.wikipedia.org/wiki/P%C3%A9clet_number) — the ratio of
+advective to diffusive transport, the dimensionless heart of transport phenomena.
+
+📖 **Documentation site:** <https://computational-chemical-engineering.github.io/peclet/> — the suite's front
+door (design docs + install/deployment guide + links to each code's Doxygen API). Built from `docs/`
+via MkDocs ([mkdocs.yml](mkdocs.yml)).
+
+This is an **umbrella repository**: each code is a git **submodule** (its own repo and history); this
+repo pins compatible commits and holds the shared design docs.
+
+## Clone
+
+```bash
+git clone --recursive git@github.com:computational-chemical-engineering/peclet.git
+# or, after a plain clone:
+git submodule update --init --recursive
+```
+
+## Layout
+
+| Submodule | Role |
+|-----------|------|
+| `core/` | **Shared infrastructure** (header-only C++20 + MPI, optional Kokkos): ORB block decomposition, async grid ghost-layer exchange + Lagrangian particle migration/ghosts, SDF geometry, VTI I/O. Every method depends on it. |
+| `flow/` | Eulerian **Kokkos** incompressible Navier–Stokes (porous media; staggered MAC grid + cut-cell IBM). Complete, validated, MPI-optional distributed solver on `core`; `pnm` is its pore-network-extraction module. |
+| `dem/` | Lagrangian **Kokkos + ArborX** DEM/XPBD particle packing. Full XPBD step with a validated distributed `step_mpi` (core particle halo). |
+| `voro/` | Mixed Lagrangian/Eulerian dynamic 3D Voronoi tessellation (header-only C++17; periodic & Lees–Edwards). |
+| `morton/` | Morton/Z-order spatial-index primitive — arithmetic directly in Morton space (header-only C++17 + BMI2/AVX-512, Python). |
+
+Both GPU codes are **Kokkos**-based; the same source runs on CUDA, HIP (AMD/LUMI), and OpenMP backends,
+chosen by the bootstrapped install prefix (`tools/bootstrap_deps.sh`). The reusable parts of the original
+`block_decomposer` prototype were extracted into `core/`.
+
+## Shared design docs
+
+`docs/` is the cross-code contract every method follows:
+[ARCHITECTURE](docs/ARCHITECTURE.md) · [CONVENTIONS](docs/CONVENTIONS.md) · [STYLE](docs/STYLE.md) ·
+[INTERFACES](docs/INTERFACES.md) · [ROADMAP](docs/ROADMAP.md) ·
+[PORTABILITY](docs/PORTABILITY.md). See `CLAUDE.md` for an agent-facing overview.
+
+## Install & run (Python)
+
+Everything ships under one **`peclet` namespace** — installable parts of one family:
+
+| PyPI package | Import | Role |
+|---|---|---|
+| `peclet-morton` | `peclet.morton` | Morton/Z-order spatial index |
+| `peclet-flow` | `peclet.flow` (+ `.pnm`) | Eulerian incompressible Navier–Stokes solver |
+| `peclet-dem` | `peclet.dem` | Lagrangian DEM/XPBD particle packing |
+| `peclet-voro` | `peclet.voro` | Dynamic Voronoi tessellation + mesh generator |
+| `peclet-core` | `peclet.core` (`.mpi`, `.amr`) | Shared infra (particle halo, AMR) — sdist only |
+| `peclet` | — | metapackage: `pip install peclet` pulls the CPU family |
+
+**Multicore CPU (OpenMP):** the compute packages ship **self-contained wheels** — `pip install peclet`
+(or an individual `pip install peclet-flow`) just works and runs multi-threaded (`OMP_NUM_THREADS`).
+
+**GPU (CUDA/HIP) and multi-rank MPI:** a portable binary wheel is impossible (arch × CUDA/ROCm × MPI-ABI),
+so you build the packages from source against a Kokkos prefix, or use a container. Because the backend
+(Serial / OpenMP / CUDA / HIP) is compiled in, you build for your hardware —
+[**docs/DEPLOYMENT.md**](docs/DEPLOYMENT.md) is the guide: the backend×MPI matrix, `pip install` recipes
+per environment, and **Apptainer containers** for Snellius (CUDA) and LUMI (HIP) in [`containers/`](containers).
+
+## Continuous integration & docs
+
+Each submodule carries its own `.github/workflows/`: a **CI** workflow (build + test where feasible —
+`core` and `morton` run full CPU/MPI suites; `flow` and `dem` build the Kokkos OpenMP host
+backend) and a **Documentation** workflow that builds the Doxygen API docs and publishes them to that
+repo's GitHub Pages. Enabling Pages once per repo (Settings → Pages → "Source: GitHub Actions") is the
+only manual step.
+
+## Note on submodule pins
+
+This umbrella pins each submodule to a compatible commit on `main`. Update to the latest upstream with
+`git submodule update --remote` followed by a commit here that bumps the pointers.

peclet-0.1.0/containers/README.md

@@ -0,0 +1,88 @@
+# Containers
+
+Apptainer (Singularity) definition files that bake the toolchain + a bootstrapped Kokkos/ArborX prefix
+and pip-install the `peclet.flow`, `peclet.dem`, and `peclet.morton` Python packages. Apptainer is the de-facto
+container runtime on HPC (both **Snellius** and **LUMI** use it; Docker is not permitted on the compute
+nodes).
+
+| File | Backend | Target |
+|------|---------|--------|
+| `cpu.def` | Kokkos OpenMP + Serial | laptops, CI, CPU HPC partitions |
+| `cuda.def` | Kokkos CUDA | **Snellius** (A100 `sm_80` default; H100 `sm_90` via env) |
+| `hip.def` | Kokkos HIP | **LUMI-G** (MI250X `gfx90a`) |
+
+## Build
+
+Run from the **suite root** so the `%files . /opt/peclet` section copies the full source tree
+(check out submodules first):
+
+```bash
+git submodule update --init --recursive
+apptainer build peclet-cpu.sif  containers/cpu.def
+# GPU images compile device code for a chosen arch (no GPU needed at build time):
+KOKKOS_ARCH=AMPERE80 CUDA_ARCH=80 apptainer build peclet-cuda.sif containers/cuda.def   # A100
+apptainer build peclet-hip.sif  containers/hip.def
+```
+
+The GPU images are large and slow to build (they compile Kokkos for the device arch); build them on a
+build node, or pull/convert a prebuilt image. The arch is read from the build environment — see the
+header comment in each `.def`.
+
+## Run
+
+```bash
+# CPU, single process:
+apptainer exec peclet-cpu.sif python3 -c "import peclet.flow, peclet.dem, peclet.morton"
+
+# CPU, 4 MPI ranks (host mpirun launches one container per rank):
+mpirun -np 4 apptainer exec peclet-cpu.sif python3 your_distributed_script.py
+
+# NVIDIA GPU (Snellius) — --nv binds the host driver:
+srun apptainer exec --nv peclet-cuda.sif python3 your_script.py
+
+# AMD GPU (LUMI) — use the Cray-MPICH launcher wrapper (see below):
+module load LUMI partition/G cray-mpich rocm
+srun -n8 --gpus-per-node=8 containers/lumi-run.sh peclet-hip.sif your_script.py
+```
+
+## LUMI / Cray-MPICH (the `hip.def` MPI model)
+
+LUMI-G runs **Cray-MPICH** over the **Slingshot-11** interconnect (libfabric `cxi` provider), not
+OpenMPI. `hip.def` therefore uses the **MPICH-ABI hybrid** model:
+
+1. The container is **built against vanilla MPICH** (Ubuntu's MPICH 4.0 exports `libmpi.so.12`, the
+   same SONAME Cray-MPICH provides), so `dem`'s distributed step links the MPICH ABI.
+2. At **runtime**, [`lumi-run.sh`](lumi-run.sh) binds the host Cray-MPICH + libfabric + GPU-transport-
+   layer (GTL) libraries over the container's MPICH, so the app actually talks Slingshot and does
+   GPU-aware transfers. It injects `CRAY_LD_LIBRARY_PATH` (which the Cray PE sets once
+   `cray-mpich`/`rocm` are loaded) into the container and sets `MPICH_GPU_SUPPORT_ENABLED=1`.
+
+```bash
+module load LUMI partition/G cray-mpich rocm          # populates CRAY_LD_LIBRARY_PATH
+srun -n8 --gpus-per-node=8 containers/lumi-run.sh peclet-hip.sif my_run.py
+# override the host-library bind list if LUMI's layout differs:
+PECLET_LUMI_BIND=/opt/cray,/var/spool/slurmd,/usr/lib64/libcxi.so.1 \
+  srun ... containers/lumi-run.sh peclet-hip.sif my_run.py
+```
+
+Notes / gotchas:
+- **ROCm version.** Pin the `hip.def` base (`rocm/dev-ubuntu-22.04:6.2.4`) to **≤** the LUMI driver's
+  ROCm (`module show rocm`); a container ROCm newer than the host driver fails at load.
+- **GTL vs hsa.** The GPU-transport-layer lib (`libmpi_gtl_hsa.so`) is built against the host ROCm; if
+  you hit hsa-symbol errors, also bind the host `/opt/rocm` ahead of the container's in
+  `PECLET_LUMI_BIND` / the injected `LD_LIBRARY_PATH`.
+- **Simpler path.** If your project has LUMI's `singularity-bindings` (EasyBuild) module, load it
+  instead — it sets the bind list + `LD_LIBRARY_PATH` for you, and `lumi-run.sh` will compose with it.
+
+## Snellius / other HPC notes
+
+- **MPI ABI.** Same hybrid model: `srun`/`mpirun` on the host, MPI inside the container. `cpu.def` and
+  `cuda.def` ship OpenMPI; if your Snellius MPI module is OpenMPI this composes directly, otherwise bind
+  the host MPI or rebuild against the matching ABI.
+- **GPU-aware MPI (Snellius).** Use the CUDA-aware OpenMPI module + `--nv`. The codes host-stage the
+  halo by default and opt into GPU-aware MPI explicitly — see `core/docs/cuda-aware-mpi.md`.
+- **Arch.** `cuda.def` defaults to A100 (`sm_80`); pass `KOKKOS_ARCH=HOPPER90 CUDA_ARCH=90` for H100.
+  `hip.def` targets MI250X (`gfx90a`).
+
+These `.def` files have **not** been built/tested in CI (no GPU runners); treat them as a starting
+point to build on the target cluster. Roadblocks/assumptions are noted in `../docs/DEPLOYMENT.md`.

peclet-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+# The `peclet` metapackage — `pip install peclet` pulls the self-contained CPU (OpenMP) build of the
+# suite: the Morton index, the Eulerian NS solver, the DEM packer, and the Voronoi engine. It ships NO
+# code of its own (so `peclet` stays an implicit PEP-420 namespace owned by the member packages) — it is
+# purely a convenience dependency set.
+#
+#   pip install peclet          # CPU family: peclet-morton + peclet-flow + peclet-dem + peclet-voro
+#   pip install peclet[mpi]     # + peclet-core (MPI particle halo / AMR — builds from sdist, needs MPI)
+#
+# GPU (CUDA/HIP) and multi-rank MPI are NOT pip-installable as portable wheels (arch x CUDA/ROCm x
+# MPI-ABI): build the member packages from source against a Kokkos prefix, or use the containers.
+# See docs/DEPLOYMENT.md.
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "peclet"
+version = "0.1.0"
+description = "GPU-accelerated & parallel simulation of transport phenomena (CFD, DEM, Voronoi) — CPU family metapackage"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Frank Peters", email = "e.a.j.f.peters@gmail.com" }]
+dependencies = [
+  "peclet-morton==0.1.0",
+  "peclet-flow==0.1.0",
+  "peclet-dem==0.1.0",
+  "peclet-voro==0.1.0",
+]
+
+[project.optional-dependencies]
+# peclet-core is sdist-only (MPI particle halo + Kokkos AMR): installing it builds from source and needs
+# an MPI toolchain (+ optional Kokkos prefix for the AMR module).
+mpi = ["peclet-core==0.1.0"]
+
+[project.urls]
+Homepage = "https://github.com/computational-chemical-engineering/peclet"
+Documentation = "https://github.com/computational-chemical-engineering/peclet"
+
+# No Python package is built — this metapackage is dependencies only. Point hatchling at an empty target
+# so it produces a valid (code-free) wheel/sdist.
+[tool.hatch.build.targets.wheel]
+bypass-selection = true
+
+[tool.hatch.build.targets.sdist]
+include = ["pyproject.toml", "README.md", "LICENSE"]