peclet-core 0.1.0__tar.gz

peclet_core-0.1.0/.clang-format

@@ -0,0 +1,25 @@
+# Adopted suite-wide from voronoi_dynamics (Google C++ Style).
+BasedOnStyle: Google
+Language: Cpp
+ColumnLimit: 100
+IndentWidth: 2
+TabWidth: 2
+UseTab: Never
+ContinuationIndentWidth: 4
+BreakBeforeBraces: Attach
+AlignAfterOpenBracket: Align
+AlignTrailingComments: true
+IncludeBlocks: Regroup
+SortIncludes: CaseInsensitive
+PointerAlignment: Left
+ReferenceAlignment: Left
+SpaceBeforeParens: ControlStatements
+AllowShortFunctionsOnASingleLine: Inline
+AllowShortIfStatementsOnASingleLine: false
+AllowShortLoopsOnASingleLine: false
+SpaceAfterTemplateKeyword: true
+BreakConstructorInitializers: BeforeComma
+AccessModifierOffset: -1
+NamespaceIndentation: None
+CompactNamespaces: false
+ReflowComments: true

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

@@ -0,0 +1,53 @@
+name: CI
+
+# Build the header-only library and run the full ctest suite (serial + MPI, np = 1,2,4).
+# core is CPU-testable end-to-end: header-only C++20 + MPI, no GPU required. The optional
+# Kokkos GPU-resident halo path is NOT exercised here (no GPU on the runners) — it is covered by the
+# consumer codes' own CI.
+
+on:
+  push:
+    branches: [main, "**"]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  cpp:
+    name: ubuntu / ${{ matrix.cc }} / MPI / ${{ matrix.build_type }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        build_type: [Debug, Release]
+        include:
+          - cc: gcc
+            cxx: g++
+          - cc: clang
+            cxx: clang++
+    env:
+      CC: ${{ matrix.cc }}
+      CXX: ${{ matrix.cxx }}
+      OMPI_ALLOW_RUN_AS_ROOT: 1
+      OMPI_ALLOW_RUN_AS_ROOT_CONFIRM: 1
+      # GitHub runners have only 2 physical cores; allow OpenMPI to oversubscribe so the
+      # np=4 and np=8 correctness tests run (slower, but the logic is what we check).
+      OMPI_MCA_rmaps_base_oversubscribe: 1
+      PRTE_MCA_rmaps_default_mapping_policy: ":oversubscribe"
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install MPI
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libopenmpi-dev openmpi-bin
+          # morton is an optional sibling (enables PECLET_CORE_HAVE_MORTON); it is a private repo, so CI
+          # builds without it — the halo/decomp tests do not depend on it.
+
+      - name: Configure
+        run: cmake -S . -B build -DCMAKE_BUILD_TYPE=${{ matrix.build_type }}
+
+      - name: Build
+        run: cmake --build build -j
+
+      - name: Test (serial + MPI np=1,2,4)
+        run: ctest --test-dir build --output-on-failure

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

@@ -0,0 +1,50 @@
+name: Documentation
+
+# Build the Doxygen API docs (header-only C++20 in include/, plus the Markdown design notes) and
+# publish them 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 run manually.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'include/**'
+      - '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:
+      - 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_core-0.1.0/.github/workflows/quality.yml

@@ -0,0 +1,40 @@
+name: Quality
+
+# Lightweight code-quality gates. Python hard-fails on critical errors only. The C++ clang-format
+# check is informational for now (continue-on-error) so version skew between the runner's
+# clang-format and the local one can't red the build; promote it to required once a clang-format
+# version is pinned and the tree is reformatted against it.
+
+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"
+
+  cpp-format:
+    name: clang-format (informational)
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - run: sudo apt-get update && sudo apt-get install -y clang-format
+      - name: clang-format dry-run (uses the repo .clang-format)
+        run: |
+          files=$(git ls-files 'include/*.hpp' 'tests/*.hpp' 'tests/*.cpp' 'benchmarks/*.cpp')
+          [ -z "$files" ] && { echo "no C++ sources"; exit 0; }
+          clang-format --dry-run --Werror $files

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

@@ -0,0 +1,41 @@
+name: Release
+
+# Publish peclet-core to PyPI on a version tag via Trusted Publishing (OIDC) — configure the publisher
+# on PyPI first; no API token secret needed. SDIST ONLY: peclet-core's Python surface is the MPI particle
+# halo (peclet.core.mpi) + the Kokkos AMR octree (peclet.core.amr); both link MPI/Kokkos, whose ABI/arch
+# make a portable binary wheel impossible. Consumers `pip install peclet-core` and build against their
+# site MPI (+ optional Kokkos prefix), or use the suite containers. See ../docs/DEPLOYMENT.md.
+
+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
+
+  publish:
+    needs: [sdist]
+    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_core-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+build/
+build_*/
+build-*/
+*.o
+*.so
+.cache/
+compile_commands.json
+
+# Generated Doxygen output (built in CI, published to Pages)
+docs/html/
+
+# Python build/test artifacts
+__pycache__/
+*.pyc

peclet_core-0.1.0/CLAUDE.md

@@ -0,0 +1,117 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+`core` is the shared infrastructure library for the transport-phenomena simulation suite
+(sibling repos under `../`: `flow`, `dem`, `voro`, `morton`). The suite-wide design contract lives in `../docs/` — read
+`../docs/ARCHITECTURE.md`, `CONVENTIONS.md`, `STYLE.md`, `INTERFACES.md`, `ROADMAP.md` before
+cross-cutting changes. Header-only C++20; the device side is compiled through Kokkos (CUDA / HIP /
+OpenMP) and is also C++20 — only the `morton` dependency pins C++17 (see `../docs/STYLE.md`). CUDA is
+retired; Kokkos is the canonical device path.
+
+## Build / test / benchmark
+
+```bash
+# CPU library + tests (no device dependency):
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j
+ctest --test-dir build --output-on-failure   # serial + MPI halo + particle migration + diffusion
+
+# Portable Kokkos device halo (CUDA / HIP / OpenMP) -- opt-in, find_package(Kokkos):
+export PATH=/usr/local/cuda-13.2/bin:$PATH    # if the Kokkos install targets the CUDA backend
+cmake -S . -B build_kokkos -DPECLET_CORE_ENABLE_KOKKOS=ON \
+  -DCMAKE_PREFIX_PATH=../extern/install/nvidia-cuda
+cmake --build build_kokkos -j && ctest --test-dir build_kokkos --output-on-failure  # + GPU halo np=1,2,4
+mpirun -np 4 ./build/benchmarks/bench_halo 48 1 300
+```
+
+The Kokkos halo path is provisioned via `find_package(Kokkos CONFIG)` against a cluster module or the
+suite's local install prefix (`../tools/bootstrap_deps.sh`). The legacy native-CUDA halo was retired.
+
+## Architecture
+
+Header-only under `include/peclet/core/`:
+
+- `common/types.hpp` — `Index` (int64), `Real` (double), `IVec<Dim>`/`Vec<Dim>`, `wrap()`,
+  compile-time `forEachInBox`. **Convention: x-fastest linear index** `I = x + y*nx + z*nx*ny`
+  (matches flow and `../docs/CONVENTIONS.md`). Keep this header C++17-clean (shared with `morton`,
+  which pins C++17).
+- `decomp/block_decomposer.hpp` — ORB decomposition (ported & modernized from
+  `../block_decomposer/src/BlockDecomposer.hpp`). `ownerOf()` walks the implicit binary tree
+  (children at `2i+1`/`2i+2`, leaves carry the block index) and is the key primitive for halo
+  topology. `linearGlobal`/`multiGlobal` are x-fastest and mutually inverse. `init(numBlocks,
+  globalSize, weights)` is the **weighted ORB** for dynamic load balancing: it bisects at the cell
+  boundary whose cumulative weight reaches the sub-block target fraction (vs equal cell count);
+  equal weights reduce to the unweighted `init()` bit-for-bit.
+- `decomp/block_indexer.hpp` — local↔global indexing for an extended (inner+ghost) block.
+- `decomp/morton_indexer.hpp` — `MortonIndexer<Dim>`: Z-order (Morton) cell indexing via the `morton`
+  primitive (`morton::Morton<Dim,Bits>`), guarded by `PECLET_CORE_HAVE_MORTON`. The cache-friendly alternative
+  to the x-fastest order (which stays the convention): `codeOf`/`multiIndex` map global multi-index ↔
+  Z-order code, `neighborCode` steps one cell along an axis directly in Morton space. Methods carry
+  morton's `MORTON_HD`, so they are device-callable under a Kokkos build (the Kokkos build defines
+  `MORTON_ENABLE_KOKKOS` ⇒ `MORTON_HD` is `KOKKOS_FUNCTION`).
+- `halo/nbx.hpp` — `NbxEngine`: canonical NBX (Issend + Ibarrier consensus). Reimplements the engine
+  from `../block_decomposer/src/MPISync.hpp`. Use for dynamic/sparse exchange.
+- `halo/grid_halo_topology.hpp` — `GridHaloTopology<Dim>`: the ghost-layer exchange. **Topology** (who
+  owns each ghost cell, established via one NBX round so owners learn what to send) is built once in
+  `buildTopology()`; **exchange** runs every step. Field-agnostic: any type with
+  `bytesPerElem()`/`pack(localIdx,dst)`/`unpack(localIdx,src)` works (`GridFieldView<T>` is the
+  contiguous-array adapter). Two engines give identical results — `exchangeNbx`/`start`+`wait`
+  (overlap-capable) and `exchangePersistent` (`MPI_Neighbor_alltoallv`, faster for static grids).
+  `flatten()` exposes a device-friendly topology consumed by the device `GridHalo`.
+- `halo/particle_migrator.hpp` — `ParticleMigrator<Dim>`: Lagrangian counterpart. Reassigns particles
+  (positions + opaque fixed-stride payload) to their owning rank via the NBX engine, with periodic wrap.
+  `cellOf()` exposes the global binning cell (`ownerOf == dec.ownerOf(cellOf(x))`).
+- `halo/particle_rebalance.hpp` — `rebalanceByParticleCount(dec, mig, pos, payload, …)`: Lagrangian load
+  balancing. Bins particles onto the grid, re-inits `dec` in place with the **weighted ORB** (so a
+  migrator/halo holding a pointer to it sees the new partition), and migrates. Pure redistribution
+  (count/payload preserved). The dem distributed step is the consumer; also bound in `python/tpx_mpi.cpp`.
+- `halo/grid_halo.hpp` — `GridHalo<T>`: portable GPU-resident halo (Kokkos; CUDA / HIP / OpenMP
+  backends). pack/unpack/self-copy run as `parallel_for` over the device `peclet::core::View<T>` field; only the
+  compact halo buffers are host-staged for MPI by default (the field stays on the device), with an
+  opt-in GPU-aware path (env `PECLET_CORE_GPU_AWARE_MPI`, legacy `PECLET_CORE_CUDA_AWARE_MPI` still honoured). Built
+  from a host `GridHaloTopology<Dim>::flatten()` via `init()`. Bit-for-bit matches the CPU exchange.
+  (The legacy native-CUDA `grid_halo_cuda.cuh` / `DeviceGridExchange<T>` was retired when Kokkos became
+  the canonical device path; see `docs/cuda-aware-mpi.md` for the historical
+  host-staging-vs-GPU-aware analysis.)
+- `halo/particle_halo_topology.hpp` — `ParticleHaloTopology<Dim>`: persistent Lagrangian ghost halo
+  (host topology + field-agnostic exchange). `build()` establishes the owner↔ghost correspondence from
+  particle proximity; `forward` (owner→ghost), `reverse` (ghost→owner, accumulate) and
+  `forwardPositions` (periodic image shift) are the cheap per-step exchanges. The standard distributed
+  particle schemes (frozen/replicate, Newton-on, force-accumulate) are compositions of these.
+- `halo/particle_halo.hpp` — `ParticleHalo<Dim>`: the Kokkos GPU-resident driver for
+  `ParticleHaloTopology` (on-device forward gather + reverse atomic-accumulate; host-staged or
+  GPU-aware MPI). Built from `ParticleHaloTopology::flatten()`; consumed by dem's distributed step.
+- `geom/` — shared SDF solids. `geom/sdf.hpp` is the `Sdf` concept + analytic primitives;
+  `geom/grid_sdf.hpp` is the trilinearly-sampled `GridSdf`; `geom/vti_io.hpp` reads/writes scalar &
+  vector VTI (`.vti`). The shared geometry representation behind flow's and dem's cut-cell IBM.
+- `amr/` — block-local-Morton **AMR octree** flow subsystem (`peclet::core::amr`, guarded by `PECLET_CORE_HAVE_MORTON`).
+  `amr/block_octree.hpp` is the per-block octree; `amr/flow.hpp` is the canonical device `AmrFlow`
+  (collocated-projection Navier–Stokes with `maskSolid` and a div-free face field), with
+  `amr/flow_oracle.hpp` an unexposed serial host reference. Device + distributed multigrid live in
+  `amr/pcg.hpp`, `amr/multigrid.hpp`, `amr/velocity_mg.hpp`, `amr/momentum.hpp` and the
+  `amr/distributed_*.hpp` set (`distributed_octree.hpp::rebalance` is the Eulerian leaf/field load
+  balancer). Cut-cell openness is `amr/cut_cell.hpp`; solution-adaptive refinement is `amr/adapt.hpp` /
+  `amr/indicators.hpp` / `amr/refine.hpp`. Design notes: `docs/amr_collocated_projection.md`,
+  `docs/amr_device_assembly_plan.md`.
+- `python/` + `python/include/peclet/core/python/ndarray_interop.hpp` — **nanobind** Python bindings over a
+  shared **zero-copy `peclet::core::View`↔ndarray bridge** (`include/peclet/core/python/ndarray_interop.hpp`).
+  `python/tpx_mpi.cpp` is host-only (no Kokkos): exposes `ParticleMigrator` / `ParticleHaloTopology` /
+  `rebalanceByParticleCount` for an mpi4py driver. `python/tpx_amr.cpp` exposes the device `AmrFlow`
+  (needs the `morton` sibling + a Kokkos backend). Both are built via `include(SuiteNanobind)` +
+  `suite_require_nanobind()` from `../cmake/SuiteNanobind.cmake` (suite-root).
+
+## Gotchas
+
+- `GridHalo` caches a distributed-graph `MPI_Comm`. Its destructor guards `MPI_Comm_free` with
+  `MPI_Finalized` so an instance that outlives `MPI_Finalize` (e.g. on `main`'s stack) does not abort.
+  Don't remove that guard. The class is non-copyable (it owns the comm).
+- The halo is owner-based, not adjacency-based: a ghost cell maps to whichever rank owns its wrapped
+  global cell, so it is correct for ORB's irregular block neighbours and any ghost width — no
+  Cartesian-grid assumption.
+- Tests are dependency-free (`tests/test_util.hpp`, non-zero exit on failure). MPI tests run under
+  `mpirun` at several rank counts via ctest.
+- `../cmake/SuiteNanobind.cmake` MUST be a CMake **macro**, not a `function()`: it sets/propagates
+  variables (the located nanobind, the interpreter) into the including scope, which a function's nested
+  scope would swallow. Keep `suite_require_nanobind` defined as a macro.

peclet_core-0.1.0/CMakeLists.txt

@@ -0,0 +1,106 @@
+cmake_minimum_required(VERSION 3.24)
+project(transport_core LANGUAGES CXX)
+
+# --- Standard: C++20 host (see suite/docs/STYLE.md). Device/CUDA stays C++17-compatible. ---
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+  set(CMAKE_BUILD_TYPE Release CACHE STRING "" FORCE)
+endif()
+
+option(PECLET_CORE_BUILD_TESTS "Build tests" ON)
+option(PECLET_CORE_BUILD_BENCHMARKS "Build benchmarks" ON)
+option(PECLET_CORE_ENABLE_MPI "Build the halo layer against MPI (OFF = single-rank no-MPI stub)" ON)
+
+# --- Header-only core library ---
+add_library(tpx_core INTERFACE)
+add_library(tpx::core ALIAS tpx_core)
+target_include_directories(tpx_core INTERFACE
+  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+  $<INSTALL_INTERFACE:include>)
+target_compile_features(tpx_core INTERFACE cxx_std_20)
+
+# Optional: the morton spatial-index primitive if present as a sibling checkout.
+set(_morton_inc "${CMAKE_CURRENT_SOURCE_DIR}/../morton/include")
+if(EXISTS "${_morton_inc}/morton/morton.hpp")
+  target_include_directories(tpx_core INTERFACE $<BUILD_INTERFACE:${_morton_inc}>)
+  target_compile_definitions(tpx_core INTERFACE PECLET_CORE_HAVE_MORTON=1)
+  message(STATUS "transport-core: morton found at ${_morton_inc}")
+endif()
+
+# --- Halo layer: against MPI (default), or a single-rank no-MPI stub (PECLET_CORE_ENABLE_MPI=OFF). One code
+#     path either way -- see tpx/common/mpi.hpp + mpi_stub.hpp. PECLET_CORE_HALO_OK marks the layer available
+#     (MPI tests/benchmarks still guard on MPI_FOUND; the no-MPI build runs single-rank). ---
+set(PECLET_CORE_HALO_OK OFF)
+if(PECLET_CORE_ENABLE_MPI)
+  find_package(MPI COMPONENTS CXX)
+  if(MPI_FOUND)
+    # Pin the launcher to the MPI compiler's own prefix. FindMPI locates the compiler
+    # wrapper (mpicxx) deterministically, but searches MPIEXEC_EXECUTABLE on PATH — so a
+    # foreign launcher earlier on PATH (e.g. ParaView's bundled mpiexec) gets picked up
+    # while the binary is built against the system MPI. That mismatch is silent and nasty:
+    # every rank inits as a singleton (MPI_Comm_size==1), so `mpirun -n N` runs N
+    # independent serial processes and multi-rank tests "pass" without ever communicating.
+    # The launcher next to mpicxx always belongs to the same MPI, on any system.
+    # Scheduler-launcher clusters (srun/aprun) pass -DTPX_PIN_MPIEXEC=OFF and set
+    # MPIEXEC_EXECUTABLE themselves.
+    option(PECLET_CORE_PIN_MPIEXEC "Pin MPIEXEC_EXECUTABLE to the MPI compiler's prefix" ON)
+    if(PECLET_CORE_PIN_MPIEXEC AND MPI_CXX_COMPILER)
+      get_filename_component(_mpi_bin "${MPI_CXX_COMPILER}" DIRECTORY)
+      unset(_mpi_launcher CACHE)
+      find_program(_mpi_launcher NAMES mpirun mpiexec HINTS "${_mpi_bin}" NO_DEFAULT_PATH)
+      if(_mpi_launcher AND NOT _mpi_launcher STREQUAL "${MPIEXEC_EXECUTABLE}")
+        message(STATUS "transport-core: MPIEXEC_EXECUTABLE was '${MPIEXEC_EXECUTABLE}' — "
+                       "pinning to '${_mpi_launcher}' (matches ${MPI_CXX_COMPILER})")
+        set(MPIEXEC_EXECUTABLE "${_mpi_launcher}" CACHE FILEPATH "MPI launcher" FORCE)
+      endif()
+      unset(_mpi_launcher CACHE)
+    endif()
+    add_library(tpx_halo INTERFACE)
+    add_library(tpx::halo ALIAS tpx_halo)
+    target_link_libraries(tpx_halo INTERFACE tpx_core MPI::MPI_CXX)
+    set(PECLET_CORE_HALO_OK ON)
+    message(STATUS "transport-core: MPI found (${MPI_CXX_COMPILER}) — halo layer enabled")
+  else()
+    message(WARNING "transport-core: MPI not found — halo layer and its tests are disabled")
+  endif()
+else()
+  add_library(tpx_halo INTERFACE)
+  add_library(tpx::halo ALIAS tpx_halo)
+  target_link_libraries(tpx_halo INTERFACE tpx_core)
+  target_compile_definitions(tpx_halo INTERFACE PECLET_CORE_NO_MPI=1)
+  set(PECLET_CORE_HALO_OK ON)
+  message(STATUS "transport-core: MPI disabled — halo uses the single-rank no-MPI stub")
+endif()
+
+# --- Optional Kokkos: portable (CUDA/HIP/OpenMP) GPU-resident halo exchange ---
+# (The legacy native-CUDA halo, grid_halo_cuda.cuh, was retired in favour of the Kokkos path below.)
+# Consumed via find_package(Kokkos CONFIG); provide it with a cluster module or the suite's local
+# install prefix (suite/tools/bootstrap_deps.sh) on CMAKE_PREFIX_PATH. Independent of the legacy
+# native-CUDA path above — both can be built at once.
+option(PECLET_CORE_ENABLE_KOKKOS "Build the portable Kokkos halo path (find_package(Kokkos))" OFF)
+set(PECLET_CORE_HAVE_KOKKOS OFF)
+if(PECLET_CORE_ENABLE_KOKKOS AND PECLET_CORE_HALO_OK)
+  find_package(Kokkos CONFIG REQUIRED)
+  set(PECLET_CORE_HAVE_KOKKOS ON)
+  message(STATUS "transport-core: Kokkos ${Kokkos_VERSION} found (${Kokkos_DEVICES}) — "
+                 "portable halo path enabled")
+  # When morton is present, build it in Kokkos mode so MORTON_HD resolves to
+  # KOKKOS_FUNCTION — the MortonIndexer (tpx/decomp/morton_indexer.hpp) is then
+  # callable from device kernels on any backend.
+  if(TARGET Kokkos::kokkos AND EXISTS "${_morton_inc}/morton/morton.hpp")
+    target_link_libraries(tpx_core INTERFACE Kokkos::kokkos)
+    target_compile_definitions(tpx_core INTERFACE MORTON_ENABLE_KOKKOS=1)
+  endif()
+endif()
+
+if(PECLET_CORE_BUILD_TESTS)
+  enable_testing()
+  add_subdirectory(tests)
+endif()
+
+if(PECLET_CORE_BUILD_BENCHMARKS AND MPI_FOUND)
+  add_subdirectory(benchmarks)
+endif()

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

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: peclet-core
+Version: 0.1.0
+Summary: peclet.core — shared transport-core infrastructure: Lagrangian particle halo (MPI) + AMR octree
+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-core
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.20
+Description-Content-Type: text/markdown
+
+# core
+
+Shared infrastructure for the transport-phenomena simulation suite (see `../docs/` for the suite-wide
+[architecture](../docs/ARCHITECTURE.md), [conventions](../docs/CONVENTIONS.md),
+[style](../docs/STYLE.md), [interfaces](../docs/INTERFACES.md) and [roadmap](../docs/ROADMAP.md)).
+
+It provides the pieces every method code (`flow`, `dem`, `voro`, …) should
+share: a common MPI **block domain decomposition**, an efficient **asynchronous ghost-layer
+exchange** (CPU + portable Kokkos GPU), **particle migration**, **dynamic load balancing**, unified
+**SDF geometry** (`peclet::core::geom`), an **AMR octree** flow subsystem (`peclet::core::amr`), and **nanobind Python
+bindings**. Header-only C++20 (the device side, compiled through Kokkos, is also C++20; only the
+`morton` dependency pins C++17 — see `../docs/STYLE.md`). Cut-cell IBM is not a standalone shared
+module: it currently lives inside the AMR flow solver (`peclet::core::amr`) and in `flow`.
+
+## What works today
+
+- `peclet::core::decomp::BlockDecomposer<Dim>` — orthogonal recursive bisection of a global cell grid into
+  rank-owned blocks; `ownerOf()` tree-walk; x-fastest global/local linear indexing.
+- `peclet::core::decomp::BlockIndexer<Dim>` — local↔global indexing for a block with a ghost layer.
+- `peclet::core::halo::NbxEngine` — nonblocking-consensus sparse exchange (Issend + Ibarrier), for dynamic
+  patterns.
+- `peclet::core::halo::GridHaloTopology<Dim>` (`grid_halo_topology.hpp`) — asynchronous ghost-layer exchange
+  with **topology separated from exchange** and a **field-agnostic** pack/unpack interface.
+  `buildTopology()` runs once; two interchangeable exchange engines give identical results:
+  - `exchangeNbx()` / `start()`+`wait()` — NBX, supports compute/comm overlap.
+  - `exchangePersistent()` — `MPI_Neighbor_alltoallv` on a cached distributed-graph communicator;
+    fastest for the static neighbour pattern of a fixed grid.
+- `peclet::core::halo::GridFieldView<T>` — wraps a contiguous local array as an exchangeable field.
+- `peclet::core::halo::GridHalo<T>` (`grid_halo.hpp`) — portable **GPU-resident** ghost-layer exchange (Kokkos:
+  CUDA / HIP / OpenMP). Built once from a host `GridHaloTopology<Dim>::flatten()`; pack / unpack /
+  periodic self-copy run as `Kokkos::parallel_for` over the device `peclet::core::View<T>` field, so the full
+  field never crosses the bus — only the compact halo buffers are host-staged for MPI by default, with
+  an opt-in GPU-aware path (env `PECLET_CORE_GPU_AWARE_MPI`). Bit-for-bit identical to the CPU exchange.
+- `peclet::core::halo::ParticleMigrator<Dim>` — Lagrangian particle migration to owning ranks (NBX), the
+  dynamic counterpart to the Eulerian grid halo.
+- `peclet::core::halo::ParticleHaloTopology<Dim>` (`particle_halo_topology.hpp`) — persistent Lagrangian ghost
+  halo: `forward` (owner→ghost), `reverse` (ghost→owner, accumulate) and `forwardPositions` (periodic
+  image shift). `peclet::core::halo::ParticleHalo<Dim>` (`particle_halo.hpp`) is its GPU-resident Kokkos driver
+  (on-device gather/scatter, host-staged or GPU-aware MPI), consumed by dem's distributed step.
+- `peclet::core::halo::rebalanceByParticleCount(...)` (`particle_rebalance.hpp`) — **dynamic load balancing**
+  for the Lagrangian path: re-inits the decomposition in place with the **weighted ORB**
+  (`BlockDecomposer::init(numBlocks, globalSize, weights)`) and migrates. The Eulerian/AMR counterpart
+  is `peclet::core::amr::DistributedOctree::rebalance`.
+- `peclet::core::geom` (`sdf.hpp`, `grid_sdf.hpp`, `vti_io.hpp`) — shared SDF solids: analytic primitives +
+  trilinear `GridSdf` behind one `Sdf` concept, with VTI (.vti) read/write.
+- `peclet::core::amr` (`include/peclet/core/amr/`) — block-local-Morton **AMR octree** flow subsystem: `peclet::core::amr::AmrFlow`
+  (collocated projection Navier–Stokes), device + distributed multigrid (`pcg.hpp`, `multigrid.hpp`,
+  `velocity_mg.hpp`, `distributed_*.hpp`), cut-cell IBM (`cut_cell.hpp`) and solution-adaptive refinement
+  (`adapt.hpp`, `indicators.hpp`). See `docs/amr_collocated_projection.md`.
+- **Python bindings** (`python/tpx_mpi.cpp`, `python/tpx_amr.cpp`) — **nanobind** modules over the
+  shared zero-copy `View`↔ndarray bridge (`include/peclet/core/python/ndarray_interop.hpp`). `peclet.core.mpi` exposes
+  the host Lagrangian halo / migration / rebalance; `peclet.core.amr` exposes the device AMR flow.
+
+Validated end-to-end by distributed explicit heat-diffusion solvers (plain, and **around an SDF solid
+obstacle**) matching a serial reference cell-for-cell across ranks, and consumed by the validated
+`flow` and `dem` distributed solvers. 26 ctests pass (`np` 1–8 CPU, 1–4 GPU).
+
+## Build / test / benchmark
+
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build -j
+ctest --test-dir build --output-on-failure          # 26 ctests: serial + MPI (np=1,2,4,8)
+
+# halo microbenchmark: weak scaling, NBX vs persistent
+mpirun -np 4 ./build/benchmarks/bench_halo 48 1 300  # cells/rank/axis, ghost, iters
+```
+
+Requires MPI (OpenMPI/MPICH) and a C++20 compiler. `morton` is picked up automatically if
+checked out as a sibling directory (enables `PECLET_CORE_HAVE_MORTON`).
+
+## Status
+
+Complete and in production. The block decomposition, the async ghost-layer exchange (CPU + portable
+Kokkos GPU, host-staged and opt-in GPU-aware), particle migration, dynamic load balancing (weighted
+ORB + AMR/Lagrangian rebalancing), SDF geometry, the AMR octree flow subsystem (device + distributed
+multigrid, collocated projection), and the nanobind Python bindings are all shipped and tested
+(26 ctests, `np` 1–8 CPU / 1–4 GPU). `flow` (distributed cut-cell IBM Navier–Stokes) and `dem`
+(distributed XPBD with load rebalancing) are validated consumers. CUDA is retired; Kokkos
+(CUDA / HIP / OpenMP) is the canonical device path. Remaining work is at-scale multi-GPU tuning.

peclet_core-0.1.0/README.md

@@ -0,0 +1,80 @@
+# core
+
+Shared infrastructure for the transport-phenomena simulation suite (see `../docs/` for the suite-wide
+[architecture](../docs/ARCHITECTURE.md), [conventions](../docs/CONVENTIONS.md),
+[style](../docs/STYLE.md), [interfaces](../docs/INTERFACES.md) and [roadmap](../docs/ROADMAP.md)).
+
+It provides the pieces every method code (`flow`, `dem`, `voro`, …) should
+share: a common MPI **block domain decomposition**, an efficient **asynchronous ghost-layer
+exchange** (CPU + portable Kokkos GPU), **particle migration**, **dynamic load balancing**, unified
+**SDF geometry** (`peclet::core::geom`), an **AMR octree** flow subsystem (`peclet::core::amr`), and **nanobind Python
+bindings**. Header-only C++20 (the device side, compiled through Kokkos, is also C++20; only the
+`morton` dependency pins C++17 — see `../docs/STYLE.md`). Cut-cell IBM is not a standalone shared
+module: it currently lives inside the AMR flow solver (`peclet::core::amr`) and in `flow`.
+
+## What works today
+
+- `peclet::core::decomp::BlockDecomposer<Dim>` — orthogonal recursive bisection of a global cell grid into
+  rank-owned blocks; `ownerOf()` tree-walk; x-fastest global/local linear indexing.
+- `peclet::core::decomp::BlockIndexer<Dim>` — local↔global indexing for a block with a ghost layer.
+- `peclet::core::halo::NbxEngine` — nonblocking-consensus sparse exchange (Issend + Ibarrier), for dynamic
+  patterns.
+- `peclet::core::halo::GridHaloTopology<Dim>` (`grid_halo_topology.hpp`) — asynchronous ghost-layer exchange
+  with **topology separated from exchange** and a **field-agnostic** pack/unpack interface.
+  `buildTopology()` runs once; two interchangeable exchange engines give identical results:
+  - `exchangeNbx()` / `start()`+`wait()` — NBX, supports compute/comm overlap.
+  - `exchangePersistent()` — `MPI_Neighbor_alltoallv` on a cached distributed-graph communicator;
+    fastest for the static neighbour pattern of a fixed grid.
+- `peclet::core::halo::GridFieldView<T>` — wraps a contiguous local array as an exchangeable field.
+- `peclet::core::halo::GridHalo<T>` (`grid_halo.hpp`) — portable **GPU-resident** ghost-layer exchange (Kokkos:
+  CUDA / HIP / OpenMP). Built once from a host `GridHaloTopology<Dim>::flatten()`; pack / unpack /
+  periodic self-copy run as `Kokkos::parallel_for` over the device `peclet::core::View<T>` field, so the full
+  field never crosses the bus — only the compact halo buffers are host-staged for MPI by default, with
+  an opt-in GPU-aware path (env `PECLET_CORE_GPU_AWARE_MPI`). Bit-for-bit identical to the CPU exchange.
+- `peclet::core::halo::ParticleMigrator<Dim>` — Lagrangian particle migration to owning ranks (NBX), the
+  dynamic counterpart to the Eulerian grid halo.
+- `peclet::core::halo::ParticleHaloTopology<Dim>` (`particle_halo_topology.hpp`) — persistent Lagrangian ghost
+  halo: `forward` (owner→ghost), `reverse` (ghost→owner, accumulate) and `forwardPositions` (periodic
+  image shift). `peclet::core::halo::ParticleHalo<Dim>` (`particle_halo.hpp`) is its GPU-resident Kokkos driver
+  (on-device gather/scatter, host-staged or GPU-aware MPI), consumed by dem's distributed step.
+- `peclet::core::halo::rebalanceByParticleCount(...)` (`particle_rebalance.hpp`) — **dynamic load balancing**
+  for the Lagrangian path: re-inits the decomposition in place with the **weighted ORB**
+  (`BlockDecomposer::init(numBlocks, globalSize, weights)`) and migrates. The Eulerian/AMR counterpart
+  is `peclet::core::amr::DistributedOctree::rebalance`.
+- `peclet::core::geom` (`sdf.hpp`, `grid_sdf.hpp`, `vti_io.hpp`) — shared SDF solids: analytic primitives +
+  trilinear `GridSdf` behind one `Sdf` concept, with VTI (.vti) read/write.
+- `peclet::core::amr` (`include/peclet/core/amr/`) — block-local-Morton **AMR octree** flow subsystem: `peclet::core::amr::AmrFlow`
+  (collocated projection Navier–Stokes), device + distributed multigrid (`pcg.hpp`, `multigrid.hpp`,
+  `velocity_mg.hpp`, `distributed_*.hpp`), cut-cell IBM (`cut_cell.hpp`) and solution-adaptive refinement
+  (`adapt.hpp`, `indicators.hpp`). See `docs/amr_collocated_projection.md`.
+- **Python bindings** (`python/tpx_mpi.cpp`, `python/tpx_amr.cpp`) — **nanobind** modules over the
+  shared zero-copy `View`↔ndarray bridge (`include/peclet/core/python/ndarray_interop.hpp`). `peclet.core.mpi` exposes
+  the host Lagrangian halo / migration / rebalance; `peclet.core.amr` exposes the device AMR flow.
+
+Validated end-to-end by distributed explicit heat-diffusion solvers (plain, and **around an SDF solid
+obstacle**) matching a serial reference cell-for-cell across ranks, and consumed by the validated
+`flow` and `dem` distributed solvers. 26 ctests pass (`np` 1–8 CPU, 1–4 GPU).
+
+## Build / test / benchmark
+
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build -j
+ctest --test-dir build --output-on-failure          # 26 ctests: serial + MPI (np=1,2,4,8)
+
+# halo microbenchmark: weak scaling, NBX vs persistent
+mpirun -np 4 ./build/benchmarks/bench_halo 48 1 300  # cells/rank/axis, ghost, iters
+```
+
+Requires MPI (OpenMPI/MPICH) and a C++20 compiler. `morton` is picked up automatically if
+checked out as a sibling directory (enables `PECLET_CORE_HAVE_MORTON`).
+
+## Status
+
+Complete and in production. The block decomposition, the async ghost-layer exchange (CPU + portable
+Kokkos GPU, host-staged and opt-in GPU-aware), particle migration, dynamic load balancing (weighted
+ORB + AMR/Lagrangian rebalancing), SDF geometry, the AMR octree flow subsystem (device + distributed
+multigrid, collocated projection), and the nanobind Python bindings are all shipped and tested
+(26 ctests, `np` 1–8 CPU / 1–4 GPU). `flow` (distributed cut-cell IBM Navier–Stokes) and `dem`
+(distributed XPBD with load rebalancing) are validated consumers. CUDA is retired; Kokkos
+(CUDA / HIP / OpenMP) is the canonical device path. Remaining work is at-scale multi-GPU tuning.