peclet-dem 0.1.0__tar.gz

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

@@ -0,0 +1,73 @@
+name: CI
+
+# Build the Kokkos (OpenMP/Serial) backend + ArborX from source, then build the dem Python module and
+# smoke-import it. The GPU (CUDA/HIP) backends and the multi-rank MPI step (DEM_MPI, needs the
+# core sibling) are NOT exercisable on free GitHub runners (no GPU); this CI covers the
+# portable host build, which catches the bulk of regressions. The single-rank module depends only on
+# Kokkos + ArborX + pybind11 (the distributed step is gated behind DEM_MPI).
+
+on:
+  push:
+    branches: [main, "**"]
+  pull_request:
+  workflow_dispatch:
+
+env:
+  KOKKOS_TAG: "5.1.1"   # keep in lockstep with ../tools/bootstrap_deps.sh
+  ARBORX_TAG: "v2.1"
+
+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 + ArborX install
+        id: deps-cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ github.workspace }}/deps-install
+          key: kokkos-${{ env.KOKKOS_TAG }}-arborx-${{ env.ARBORX_TAG }}-openmp-${{ runner.os }}
+
+      - name: Build Kokkos (OpenMP + Serial) + ArborX
+        if: steps.deps-cache.outputs.cache-hit != 'true'
+        run: |
+          PREFIX="$GITHUB_WORKSPACE/deps-install"
+          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="$PREFIX"
+          cmake --build /tmp/kokkos/build -j && cmake --install /tmp/kokkos/build
+          # ArborX is header-only; it just needs to find the Kokkos we built.
+          git clone --depth 1 --branch "$ARBORX_TAG" https://github.com/arborx/ArborX.git /tmp/arborx
+          cmake -S /tmp/arborx -B /tmp/arborx/build -G Ninja \
+            -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_STANDARD=20 \
+            -DCMAKE_PREFIX_PATH="$PREFIX" -DCMAKE_INSTALL_PREFIX="$PREFIX"
+          cmake --install /tmp/arborx/build
+
+      - name: Build dem module
+        run: |
+          cmake -S . -B build \
+            -DCMAKE_PREFIX_PATH="$GITHUB_WORKSPACE/deps-install;$(python3 -m pybind11 --cmakedir)"
+          cmake --build build -j
+
+      - name: Import smoke test
+        run: PYTHONPATH=$PWD/build python3 -c "import dem; print('dem import OK')"
+
+      - name: Build + run Kokkos kernel unit tests (tests/kokkos)
+        run: |
+          # Kokkos-only unit suite (no ArborX / MPI): contact preprocessing, narrow-phase, the
+          # velocity/position/friction XPBD solves, integration, periodicity and the thermostat,
+          # each validated in isolation against a serial reference.
+          cmake -S tests/kokkos -B build_kokkos \
+            -DCMAKE_PREFIX_PATH="$GITHUB_WORKSPACE/deps-install"
+          cmake --build build_kokkos -j
+          ctest --test-dir build_kokkos --output-on-failure

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

@@ -0,0 +1,51 @@
+name: Documentation
+
+# Build the Doxygen API docs (Kokkos + ArborX C++ in src/ & mpi/) 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 triggered manually. Doxygen only parses the sources (no
+# Kokkos/ArborX toolchain needed), so this runs on a plain ubuntu runner.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'src/**'
+      - 'mpi/**'
+      - 'docs/**'
+      - 'README.md'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+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_dem-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_dem-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-dem) 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_dem-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Build directories + logs
+build/
+build_*/
+build_log*.txt
+*.log
+cmake-build-debug/
+cmake-build-release/
+bin/
+lib/
+*.so
+*.a
+*.o
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+env/
+venv/
+.env
+.venv
+
+# IDEs
+# .vscode/
+.idea/
+*.swp
+*~
+.DS_Store
+
+# Generated artifacts (if any not in build)
+*.egg-info/
+dist/
+.cache/
+output/
+
+# Generated Doxygen output (built in CI, published to Pages)
+docs/html/
+docs/latex/

peclet_dem-0.1.0/.vscode/launch.json

@@ -0,0 +1,57 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "(gdb) Launch Python Script (C++ Only)",
+            "type": "cppdbg",
+            "request": "launch",
+            "program": "${workspaceFolder}/.venv/bin/python",
+            "args": [
+                "${workspaceFolder}/verify_packing_hollow_cylinders_test.py"
+            ],
+            "stopAtEntry": false,
+            "cwd": "${workspaceFolder}",
+            "environment": [
+                {
+                    "name": "PYTHONPATH",
+                    "value": "${workspaceFolder}/build:${env:PYTHONPATH}"
+                }
+            ],
+            "externalConsole": false,
+            "MIMode": "gdb",
+            "setupCommands": [
+                {
+                    "description": "Enable pretty-printing for gdb",
+                    "text": "-enable-pretty-printing",
+                    "ignoreFailures": true
+                }
+            ]
+        },
+        {
+            "name": "Python: Current File",
+            "type": "python",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal",
+            "justMyCode": false,
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}/build:${env:PYTHONPATH}"
+            }
+        },
+        {
+            "name": "(gdb) Attach to Python Process",
+            "type": "cppdbg",
+            "request": "attach",
+            "program": "${workspaceFolder}/.venv/bin/python",
+            "processId": "${command:pickProcess}",
+            "MIMode": "gdb",
+            "setupCommands": [
+                {
+                    "description": "Enable pretty-printing for gdb",
+                    "text": "-enable-pretty-printing",
+                    "ignoreFailures": true
+                }
+            ]
+        }
+    ]
+}

peclet_dem-0.1.0/CMakeLists.txt

@@ -0,0 +1,65 @@
+cmake_minimum_required(VERSION 3.24)
+project(dem LANGUAGES CXX)
+
+# Canonical packing-gpu build: the Kokkos + ArborX `dem` XPBD DEM module (CUDA / HIP / OpenMP backends,
+# selected by the install prefix). Kokkos, ArborX and pybind11 are found via find_package against the
+# bootstrapped install prefix (../extern/install/<backend>, built once by ../tools/bootstrap_deps.sh -- a
+# HARD build dependency). With nvcc, put it on PATH (export PATH=/usr/local/cuda-13.2/bin:$PATH).
+#
+# Build (single-rank Python module); 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/dem.*.so
+#
+# Multi-rank: -DDEM_MPI=ON links MPI + exposes init_mpi/enable_mpi_step/step_mpi in the module; the
+# distributed step is also covered by the tests/kokkos_mpi ctests (run under mpirun).
+
+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()
+
+option(PECLET_DEM_MPI "Build the dem module with the distributed (MPI) step exposed" OFF)
+
+# Dependencies via the vendored PecletDeps helper: installed Kokkos+ArborX prefix + sibling checkout for
+# the dev/suite build, or FetchContent-built Kokkos+ArborX + 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_arborx()
+peclet_require_nanobind()   # nanobind + core's View<->ndarray zero-copy bridge
+peclet_sibling_include(peclet-core "${PECLET_TPX_TAG}" "../core" TPX_INCLUDE)
+
+# NB_STATIC: bundle nanobind's runtime into the module; the Kokkos device path is routed by the
+# launch compiler regardless. NOMINSIZE: nanobind's default -Os is rejected by nvcc ("'s': expected a
+# number") since Kokkos device sources compile as CXX through the launch compiler.
+nanobind_add_module(dem NB_STATIC NOMINSIZE src/dem_bindings.cpp)
+# -> peclet.dem._dem (NB_MODULE(_dem)), re-exported by peclet/dem/__init__.py. The __init__ is kept as a
+# plain file under packaging/ (OUTSIDE any importable peclet/ dir, so an incomplete source package can
+# never shadow the installed one) and staged into <build>/peclet/dem so `PYTHONPATH=<build> python …`
+# (`import peclet.dem`) works in the dev loop too.
+set_target_properties(dem PROPERTIES OUTPUT_NAME _dem
+  LIBRARY_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/peclet/dem")
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/packaging/dem_init.py
+               ${CMAKE_CURRENT_BINARY_DIR}/peclet/dem/__init__.py COPYONLY)
+target_include_directories(dem PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src ${TPX_INCLUDE})
+target_link_libraries(dem PRIVATE ArborX::ArborX Kokkos::kokkos)
+
+if(PECLET_DEM_MPI)
+  find_package(MPI REQUIRED COMPONENTS CXX)
+  target_compile_definitions(dem PRIVATE PECLET_DEM_MPI=1)
+  target_link_libraries(dem PRIVATE MPI::MPI_CXX)
+  message(STATUS "dem: distributed step ENABLED (MPI)")
+endif()
+
+# --- pip / scikit-build-core install rule -------------------------------------------------------
+# `pip install .` (driven by pyproject.toml) builds against a Kokkos+ArborX prefix on
+# CMAKE_PREFIX_PATH and installs the extension as a top-level `dem` module. The rule is inert for a
+# plain `cmake --build` (no `cmake --install`), so the developer workflow is unchanged. SKBUILD is set
+# by scikit-build-core; SKBUILD_PROJECT_NAME-style guards keep it from interfering elsewhere.
+if(DEFINED SKBUILD)
+  install(TARGETS dem LIBRARY DESTINATION peclet/dem COMPONENT python)
+  install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/packaging/dem_init.py
+          DESTINATION peclet/dem RENAME __init__.py COMPONENT python)
+endif()

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

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: peclet-dem
+Version: 0.1.0
+Summary: peclet.dem — performance-portable XPBD Discrete Element Method (Kokkos + ArborX)
+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-dem
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.20
+Description-Content-Type: text/markdown
+
+# peclet-dem (`peclet.dem`)
+
+Performance-portable Discrete Element Method (DEM) particle simulation: an XPBD solver with SDF-based point-shell collision detection. Built on **Kokkos + ArborX**, so the same source runs on **CUDA, HIP (AMD/LUMI), and OpenMP** backends (selected at build time by the install prefix). Optional MPI for domain partitioning, with **nanobind** Python bindings (zero-copy, via scikit-build-core) for scripting and visualization.
+
+> The CUDA implementation was retired (2026-06): the Kokkos `peclet.dem` module was validated against it before the CUDA sources were removed. Restore point: git tag `pre-cuda-retirement`.
+
+## Features
+
+- **Hybrid XPBD Solver**: Two-pass velocity/position solver for stable high-density packing.
+- **SDF Collision**: Point-shell collision detection using Signed Distance Fields (supports analytic shapes like hollow cylinders).
+- **Periodicity**: Full periodic boundary conditions (Ghost Particles).
+- **Python Bindings**: Control simulation logic, data initialization, and export entirely from Python.
+- **MPI Support**: Optional Multi-GPU/Node support via domain decomposition.
+
+## Folder Structure
+
+```text
+├── CMakeLists.txt              # Build configuration (find_package Kokkos + ArborX)
+├── src                         # Kokkos sources (header-only, namespace peclet::dem)
+│   ├── dem_bindings.cpp        # nanobind module entry point (the `peclet.dem` module)
+│   ├── sim.hpp                 # Simulation facade + the demStep XPBD substep
+│   ├── integration.hpp         # Time integration & prediction
+│   ├── broadphase_arborx.hpp   # ArborX BVH broad-phase
+│   ├── narrowphase.hpp         # Narrow-phase point-shell-vs-SDF collision
+│   ├── solver_velocity.hpp     # Velocity solver kernels
+│   ├── solver_position.hpp     # Position solver kernels (XPBD overlap removal)
+│   ├── solver_friction.hpp     # Coulomb friction cluster
+│   ├── output_sdf.hpp          # SDF/VTI grid generation (Eikonal)
+│   ├── shapes_portable.hpp     # Analytic shapes (sphere / hollow cylinder / box)
+│   ├── io.hpp                  # LAMMPS-dump + SDF-VTI export
+│   └── mpi_halo.hpp            # Distributed particle halo (core), gated PECLET_DEM_MPI
+├── tests                       # C++ unit tests: kokkos/ (kernels), arborx/, kokkos_mpi/
+├── docs                        # Documentation
+└── *.py                        # Python verification/example scripts (verify_*.py)
+```
+
+## Prerequisites
+
+- **Linux**
+- **CMake** >= 3.24
+- **Kokkos 5.x + ArborX** (C++20) — provisioned by `../tools/bootstrap_deps.sh` into
+  `../extern/install/<backend>` (`nvidia-cuda` / `host-openmp` / `lumi-hip`). A **hard build dependency**.
+- **nanobind** + **scikit-build-core** (found via the active Python interpreter; see `pyproject.toml`)
+- a backend compiler: **nvcc** (CUDA) on `PATH`, **hipcc** (ROCm), or just a host C++ compiler (OpenMP)
+- **Python** >= 3.10
+- **MPI** (optional, `-DDEM_MPI=ON`) — OpenMPI or MPICH
+
+## Build Instructions
+
+```bash
+python -m venv .venv && source .venv/bin/activate && pip install nanobind numpy
+export PATH=/usr/local/cuda-13.2/bin:$PATH        # if building the CUDA backend
+
+# Canonical: build + install the module via scikit-build-core
+CMAKE_PREFIX_PATH="$PWD/../extern/install/nvidia-cuda" pip install .
+
+# Or a dev cmake build (nanobind is found via the active interpreter, no cmakedir needed):
+cmake -B build -S . -DCMAKE_PREFIX_PATH="$PWD/../extern/install/nvidia-cuda"
+cmake --build build -j$(nproc)
+```
+*Swap the prefix to `../extern/install/host-openmp` for the OpenMP backend. `-DDEM_MPI=ON` links MPI
+and exposes the distributed step (`init_mpi` / `enable_mpi_step` / `step_mpi`), including dynamic load
+balancing — `enable_mpi_step(..., rebalance_every=N)` or an explicit `rebalance()` re-decomposes by
+particle count (weighted ORB) and migrates ownership so each rank keeps a near-equal share.*
+
+The compiled `peclet.dem` extension is placed in `build/peclet/dem/`; run scripts with `build/` on `PYTHONPATH` (`import peclet.dem`).
+
+## Running Simulations
+
+Example scripts are provided in the root directory:
+
+```bash
+# Add build artifact to python path if needed (or symlink it)
+export PYTHONPATH=$PYTHONPATH:$(pwd)/build
+
+# Run a verification script
+python verify_packing_hollow_cylinders.py
+```
+
+## Output & Visualization
+
+The simulation supports two primary output formats:
+
+### 1. LAMMPS + STL (Ovito)
+
+For particle visualization (especially non-spherical shapes), we use the LAMMPS dump format combined with an STL mesh.
+
+1.  **Generate Output**: The simulation writes `dump.custom.*` files.
+2.  **Generate Shape**: Run `python generate_particles.py` to create `particle_shape.stl`.
+3.  **Visualize**:
+    - Open **Ovito**.
+    - Load the `dump.custom.*` sequence.
+    - Add a **Particle Types** modifier.
+    - Set the shape visualization to **Mesh/User-defined** and load `particle_shape.stl`.
+    - Ovito will automatically scale the mesh by the particle radius.
+
+*See `docs/visualization.md` for a detailed guide.*
+
+### 2. VTI (ParaView)
+
+For visualizing fields (like the Signed Distance Field or occupancy grids), the simulation exports VTI files (`.vti`).
+
+1.  **Generate Output**: Use `Simulation.export_sdf("filename.vti", resolution=...)`.
+2.  **Visualize**:
+    - Open **ParaView**.
+    - Load the `.vti` file.
+    - Use "Volume" representation or "Slice" filter to inspect the field.
+
+## Status
+
+The single-GPU engine is complete and validated: it reaches stable high-density (random close)
+packing, and energy is conserved to ~0.3% (see `docs/packing_investigation.md`). Friction is
+stabilized for spheres; body-body tangential friction is a known follow-up (currently weaker than
+ideal). Active work is at-scale multi-GPU/MPI tuning.
+
+> [!NOTE]
+> The distributed (MPI) step is validated against the single-rank result (`tests/kokkos_mpi`,
+> np=1,2,4 on OpenMP + CUDA) and supports dynamic load rebalancing; remaining MPI work is at-scale
+> multi-GPU tuning.

peclet_dem-0.1.0/README.md

@@ -0,0 +1,119 @@
+# peclet-dem (`peclet.dem`)
+
+Performance-portable Discrete Element Method (DEM) particle simulation: an XPBD solver with SDF-based point-shell collision detection. Built on **Kokkos + ArborX**, so the same source runs on **CUDA, HIP (AMD/LUMI), and OpenMP** backends (selected at build time by the install prefix). Optional MPI for domain partitioning, with **nanobind** Python bindings (zero-copy, via scikit-build-core) for scripting and visualization.
+
+> The CUDA implementation was retired (2026-06): the Kokkos `peclet.dem` module was validated against it before the CUDA sources were removed. Restore point: git tag `pre-cuda-retirement`.
+
+## Features
+
+- **Hybrid XPBD Solver**: Two-pass velocity/position solver for stable high-density packing.
+- **SDF Collision**: Point-shell collision detection using Signed Distance Fields (supports analytic shapes like hollow cylinders).
+- **Periodicity**: Full periodic boundary conditions (Ghost Particles).
+- **Python Bindings**: Control simulation logic, data initialization, and export entirely from Python.
+- **MPI Support**: Optional Multi-GPU/Node support via domain decomposition.
+
+## Folder Structure
+
+```text
+├── CMakeLists.txt              # Build configuration (find_package Kokkos + ArborX)
+├── src                         # Kokkos sources (header-only, namespace peclet::dem)
+│   ├── dem_bindings.cpp        # nanobind module entry point (the `peclet.dem` module)
+│   ├── sim.hpp                 # Simulation facade + the demStep XPBD substep
+│   ├── integration.hpp         # Time integration & prediction
+│   ├── broadphase_arborx.hpp   # ArborX BVH broad-phase
+│   ├── narrowphase.hpp         # Narrow-phase point-shell-vs-SDF collision
+│   ├── solver_velocity.hpp     # Velocity solver kernels
+│   ├── solver_position.hpp     # Position solver kernels (XPBD overlap removal)
+│   ├── solver_friction.hpp     # Coulomb friction cluster
+│   ├── output_sdf.hpp          # SDF/VTI grid generation (Eikonal)
+│   ├── shapes_portable.hpp     # Analytic shapes (sphere / hollow cylinder / box)
+│   ├── io.hpp                  # LAMMPS-dump + SDF-VTI export
+│   └── mpi_halo.hpp            # Distributed particle halo (core), gated PECLET_DEM_MPI
+├── tests                       # C++ unit tests: kokkos/ (kernels), arborx/, kokkos_mpi/
+├── docs                        # Documentation
+└── *.py                        # Python verification/example scripts (verify_*.py)
+```
+
+## Prerequisites
+
+- **Linux**
+- **CMake** >= 3.24
+- **Kokkos 5.x + ArborX** (C++20) — provisioned by `../tools/bootstrap_deps.sh` into
+  `../extern/install/<backend>` (`nvidia-cuda` / `host-openmp` / `lumi-hip`). A **hard build dependency**.
+- **nanobind** + **scikit-build-core** (found via the active Python interpreter; see `pyproject.toml`)
+- a backend compiler: **nvcc** (CUDA) on `PATH`, **hipcc** (ROCm), or just a host C++ compiler (OpenMP)
+- **Python** >= 3.10
+- **MPI** (optional, `-DDEM_MPI=ON`) — OpenMPI or MPICH
+
+## Build Instructions
+
+```bash
+python -m venv .venv && source .venv/bin/activate && pip install nanobind numpy
+export PATH=/usr/local/cuda-13.2/bin:$PATH        # if building the CUDA backend
+
+# Canonical: build + install the module via scikit-build-core
+CMAKE_PREFIX_PATH="$PWD/../extern/install/nvidia-cuda" pip install .
+
+# Or a dev cmake build (nanobind is found via the active interpreter, no cmakedir needed):
+cmake -B build -S . -DCMAKE_PREFIX_PATH="$PWD/../extern/install/nvidia-cuda"
+cmake --build build -j$(nproc)
+```
+*Swap the prefix to `../extern/install/host-openmp` for the OpenMP backend. `-DDEM_MPI=ON` links MPI
+and exposes the distributed step (`init_mpi` / `enable_mpi_step` / `step_mpi`), including dynamic load
+balancing — `enable_mpi_step(..., rebalance_every=N)` or an explicit `rebalance()` re-decomposes by
+particle count (weighted ORB) and migrates ownership so each rank keeps a near-equal share.*
+
+The compiled `peclet.dem` extension is placed in `build/peclet/dem/`; run scripts with `build/` on `PYTHONPATH` (`import peclet.dem`).
+
+## Running Simulations
+
+Example scripts are provided in the root directory:
+
+```bash
+# Add build artifact to python path if needed (or symlink it)
+export PYTHONPATH=$PYTHONPATH:$(pwd)/build
+
+# Run a verification script
+python verify_packing_hollow_cylinders.py
+```
+
+## Output & Visualization
+
+The simulation supports two primary output formats:
+
+### 1. LAMMPS + STL (Ovito)
+
+For particle visualization (especially non-spherical shapes), we use the LAMMPS dump format combined with an STL mesh.
+
+1.  **Generate Output**: The simulation writes `dump.custom.*` files.
+2.  **Generate Shape**: Run `python generate_particles.py` to create `particle_shape.stl`.
+3.  **Visualize**:
+    - Open **Ovito**.
+    - Load the `dump.custom.*` sequence.
+    - Add a **Particle Types** modifier.
+    - Set the shape visualization to **Mesh/User-defined** and load `particle_shape.stl`.
+    - Ovito will automatically scale the mesh by the particle radius.
+
+*See `docs/visualization.md` for a detailed guide.*
+
+### 2. VTI (ParaView)
+
+For visualizing fields (like the Signed Distance Field or occupancy grids), the simulation exports VTI files (`.vti`).
+
+1.  **Generate Output**: Use `Simulation.export_sdf("filename.vti", resolution=...)`.
+2.  **Visualize**:
+    - Open **ParaView**.
+    - Load the `.vti` file.
+    - Use "Volume" representation or "Slice" filter to inspect the field.
+
+## Status
+
+The single-GPU engine is complete and validated: it reaches stable high-density (random close)
+packing, and energy is conserved to ~0.3% (see `docs/packing_investigation.md`). Friction is
+stabilized for spheres; body-body tangential friction is a known follow-up (currently weaker than
+ideal). Active work is at-scale multi-GPU/MPI tuning.
+
+> [!NOTE]
+> The distributed (MPI) step is validated against the single-rank result (`tests/kokkos_mpi`,
+> np=1,2,4 on OpenMP + CUDA) and supports dynamic load rebalancing; remaining MPI work is at-scale
+> multi-GPU tuning.

peclet_dem-0.1.0/activate_env.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+# Source this script to set up the development environment
+# Usage: source activate_env.sh
+
+# Get the absolute path of the script directory
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+BUILD_DIR="$SCRIPT_DIR/build"
+
+if [ ! -d "$BUILD_DIR" ]; then
+    echo "Warning: Build directory '$BUILD_DIR' does not exist yet."
+    echo "Make sure to run: mkdir build && cd build && cmake .. && make"
+fi
+
+# Add build directory to PYTHONPATH
+export PYTHONPATH="$BUILD_DIR:$PYTHONPATH"
+
+echo "Environment configured."
+echo "PYTHONPATH includes: $BUILD_DIR"