peclet 0.4.0

GPU-accelerated & parallel simulation of transport phenomena (CFD, DEM, Voronoi) — CPU family metapackage

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 — 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).

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

git clone --recursive [e-mail]: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 · CONVENTIONS · STYLE · INTERFACES · ROADMAP · PORTABILITY. 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 is the guide: the backend×MPI matrix, pip install recipes per environment, and Apptainer containers for Snellius (CUDA) and LUMI (HIP) in 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.

Contributing & community

Contributions are welcome — see CONTRIBUTING.md for the submodule dev setup, build/test, and PR flow. Participation is governed by the Contributor Covenant. Report security issues privately per the Security Policy. Release history lives in the CHANGELOG.

Citing

If you use Peclet in your research, please cite it. Each release is archived on Zenodo:

• All versions (concept DOI): 10.5281/zenodo.21132445 — always resolves to the latest release; use this unless you need to pin an exact version.
• This release (v0.2.0): 10.5281/zenodo.21132446.

Machine-readable metadata is in CITATION.cff — use GitHub's "Cite this repository" button for ready-made BibTeX/APA.

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.