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

├── 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

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:

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

Generate Output: The simulation writes dump.custom.* files.
Generate Shape: Run python generate_particles.py to create particle_shape.stl.
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).

Generate Output: Use Simulation.export_sdf("filename.vti", resolution=...).
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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

peclet_dem-0.4.0.tar.gz (503.7 kB view details)

Uploaded Jul 25, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

peclet_dem-0.4.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (982.7 kB view details)

Uploaded Jul 25, 2026 CPython 3.13manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

peclet_dem-0.4.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (982.8 kB view details)

Uploaded Jul 25, 2026 CPython 3.12manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

peclet_dem-0.4.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (982.4 kB view details)

Uploaded Jul 25, 2026 CPython 3.11manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

peclet_dem-0.4.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (982.8 kB view details)

Uploaded Jul 25, 2026 CPython 3.10manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

File details

Details for the file peclet_dem-0.4.0.tar.gz.

File metadata

Download URL: peclet_dem-0.4.0.tar.gz
Upload date: Jul 25, 2026
Size: 503.7 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for peclet_dem-0.4.0.tar.gz
Algorithm	Hash digest
SHA256	`febe9d91a4df79e98d12f6c14ed24342fefa6719434d80497e542119109e601a`
MD5	`74cab55c6c1cb31e8a227bac43dc1b4b`
BLAKE2b-256	`e1cddafb7ebc9c1d8dd75b28818fa8be9ef20927858648849aec1aa7517cd6e9`

See more details on using hashes here.

Provenance

The following attestation bundles were made for peclet_dem-0.4.0.tar.gz:

Publisher: release.yml on computational-chemical-engineering/peclet-dem

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: peclet_dem-0.4.0.tar.gz
- Subject digest: febe9d91a4df79e98d12f6c14ed24342fefa6719434d80497e542119109e601a
- Sigstore transparency entry: 2252205696
- Sigstore integration time: Jul 25, 2026
Source repository:
- Permalink: computational-chemical-engineering/peclet-dem@c646d1de80afc970f6a9e3c957e4587d5da1af0f
- Branch / Tag: refs/tags/v0.4.0
- Owner: https://github.com/computational-chemical-engineering
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@c646d1de80afc970f6a9e3c957e4587d5da1af0f
- Trigger Event: push

File details

Details for the file peclet_dem-0.4.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

Download URL: peclet_dem-0.4.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Upload date: Jul 25, 2026
Size: 982.7 kB
Tags: CPython 3.13, manylinux: glibc 2.27+ x86-64, manylinux: glibc 2.28+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for peclet_dem-0.4.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm	Hash digest
SHA256	`63b3d98394eddcdd558dab77260929715a846aba3ea40d554edd1243aa9d91b9`
MD5	`a152d080793273cdf9f9519f90458fd4`
BLAKE2b-256	`aca7ffd73b13beda8f3e80a09ab8458012fe7928cf57d89b3875c75343c1df0f`

See more details on using hashes here.

Provenance

The following attestation bundles were made for peclet_dem-0.4.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on computational-chemical-engineering/peclet-dem

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: peclet_dem-0.4.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
- Subject digest: 63b3d98394eddcdd558dab77260929715a846aba3ea40d554edd1243aa9d91b9
- Sigstore transparency entry: 2252206459
- Sigstore integration time: Jul 25, 2026
Source repository:
- Permalink: computational-chemical-engineering/peclet-dem@c646d1de80afc970f6a9e3c957e4587d5da1af0f
- Branch / Tag: refs/tags/v0.4.0
- Owner: https://github.com/computational-chemical-engineering
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@c646d1de80afc970f6a9e3c957e4587d5da1af0f
- Trigger Event: push

File details

Details for the file peclet_dem-0.4.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

Download URL: peclet_dem-0.4.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Upload date: Jul 25, 2026
Size: 982.8 kB
Tags: CPython 3.12, manylinux: glibc 2.27+ x86-64, manylinux: glibc 2.28+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for peclet_dem-0.4.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm	Hash digest
SHA256	`c936f0fe2c0e587f3a03adefbeb2e582c52559f658680f8a154a5e1c8d1f0aaa`
MD5	`79da86f16c9106b745491b9343ff986e`
BLAKE2b-256	`cfd7c6228dd6100df57c9f90c354191af3a761c3ebb3022c22d1187c9ad469ad`

See more details on using hashes here.

Provenance

The following attestation bundles were made for peclet_dem-0.4.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on computational-chemical-engineering/peclet-dem

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: peclet_dem-0.4.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
- Subject digest: c936f0fe2c0e587f3a03adefbeb2e582c52559f658680f8a154a5e1c8d1f0aaa
- Sigstore transparency entry: 2252205906
- Sigstore integration time: Jul 25, 2026
Source repository:
- Permalink: computational-chemical-engineering/peclet-dem@c646d1de80afc970f6a9e3c957e4587d5da1af0f
- Branch / Tag: refs/tags/v0.4.0
- Owner: https://github.com/computational-chemical-engineering
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@c646d1de80afc970f6a9e3c957e4587d5da1af0f
- Trigger Event: push

File details

Details for the file peclet_dem-0.4.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

Download URL: peclet_dem-0.4.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Upload date: Jul 25, 2026
Size: 982.4 kB
Tags: CPython 3.11, manylinux: glibc 2.27+ x86-64, manylinux: glibc 2.28+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for peclet_dem-0.4.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm	Hash digest
SHA256	`66acb0ceacc483f14fecc615fe34224f34e5f563eccfcf708c6faf42a711287e`
MD5	`5369f2e522fc682274ef3729f46c19c1`
BLAKE2b-256	`0a439cfa0fd5f1e46b15d37d62a7fab7e65fac374511c7adf409501d0dc78fd7`

See more details on using hashes here.

Provenance

The following attestation bundles were made for peclet_dem-0.4.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on computational-chemical-engineering/peclet-dem

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: peclet_dem-0.4.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
- Subject digest: 66acb0ceacc483f14fecc615fe34224f34e5f563eccfcf708c6faf42a711287e
- Sigstore transparency entry: 2252206271
- Sigstore integration time: Jul 25, 2026
Source repository:
- Permalink: computational-chemical-engineering/peclet-dem@c646d1de80afc970f6a9e3c957e4587d5da1af0f
- Branch / Tag: refs/tags/v0.4.0
- Owner: https://github.com/computational-chemical-engineering
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@c646d1de80afc970f6a9e3c957e4587d5da1af0f
- Trigger Event: push

File details

Details for the file peclet_dem-0.4.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

Download URL: peclet_dem-0.4.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Upload date: Jul 25, 2026
Size: 982.8 kB
Tags: CPython 3.10, manylinux: glibc 2.27+ x86-64, manylinux: glibc 2.28+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for peclet_dem-0.4.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm	Hash digest
SHA256	`08c4e2c6871ea766f8c396d495101555f660fa046eaadc4e4020e44066fb7350`
MD5	`bed0a4be16afe34e3d0f784b6aab6dda`
BLAKE2b-256	`706490a3712d180b143660c0d8ddd40b577c831f95605bc224c5dec3662cca22`

See more details on using hashes here.

Provenance

The following attestation bundles were made for peclet_dem-0.4.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on computational-chemical-engineering/peclet-dem

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: peclet_dem-0.4.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
- Subject digest: 08c4e2c6871ea766f8c396d495101555f660fa046eaadc4e4020e44066fb7350
- Sigstore transparency entry: 2252206077
- Sigstore integration time: Jul 25, 2026
Source repository:
- Permalink: computational-chemical-engineering/peclet-dem@c646d1de80afc970f6a9e3c957e4587d5da1af0f
- Branch / Tag: refs/tags/v0.4.0
- Owner: https://github.com/computational-chemical-engineering
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@c646d1de80afc970f6a9e3c957e4587d5da1af0f
- Trigger Event: push

Release history Release notifications | RSS feed

This release

0.4.0 This release

Jul 25, 2026 5 files

Jul 6, 2026 5 files

Jul 3, 2026 5 files

Jul 3, 2026 5 files

Jul 3, 2026 5 files

Jul 2, 2026 5 files

Jul 1, 2026 5 files

peclet-dem 0.4.0

peclet-dem (peclet.dem)

Features

Folder Structure

Prerequisites

Build Instructions

Running Simulations

Output & Visualization

1. LAMMPS + STL (Ovito)

2. VTI (ParaView)

Status

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License expression

Requires

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed

peclet-dem (`peclet.dem`)