peclet-dem (peclet.dem)

PyPI version Python License: MIT CI DOI

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.

  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.

Project links

Data verified by PyPI on Sep 5, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.5.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for eajfpeters from gravatar.com eajfpeters

Credits

Author: Frank Peters

GitHub Statistics

Data verified by PyPI on Sep 5, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Report project as malware

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.5.0.tar.gz (286.4 kB view details)

Uploaded Source

Built Distributions

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

peclet_dem-0.5.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (1.1 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

peclet_dem-0.5.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (1.1 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

peclet_dem-0.5.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (1.1 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

peclet_dem-0.5.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (1.1 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

File details

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

File metadata

  • Download URL: peclet_dem-0.5.0.tar.gz
  • Upload date:
  • Size: 286.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for peclet_dem-0.5.0.tar.gz
Algorithm Hash digest
SHA256 9eaa4e7676addb65662ace352f3d92b475335d8f40d5e3ffeee340dfd8935577
MD5 e1530b70bf61f8dc4fc9f4213e88a6df
BLAKE2b-256 82fd12f8900a29c9f6eddb041d09c12abec02d61af6db05c702201d99b7cbbcf

See more details on using hashes here.

Provenance

The following attestation bundles were made for peclet_dem-0.5.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.

File details

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

File metadata

File hashes

Hashes for peclet_dem-0.5.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 87b7f57068c29e6221822ce69365e3f8f12a87ed5187ff92f846d8399661a9f5
MD5 d27f155cb63f914e8f93bef70a36c6ad
BLAKE2b-256 1abc995d7ad6633cbe0d85c446823c6aa34bba97404050444b78e1e0ae050f29

See more details on using hashes here.

Provenance

The following attestation bundles were made for peclet_dem-0.5.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.

File details

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

File metadata

File hashes

Hashes for peclet_dem-0.5.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 50536805496e7065bf37866325be70bddcfa2b17461604b2b5558727955b2524
MD5 adb666f8fbc9c9cb41453a75b40bad3e
BLAKE2b-256 636716184c74ea046cbf482f5ac4bd91773476c57e455a52cc37815070f2ca9d

See more details on using hashes here.

Provenance

The following attestation bundles were made for peclet_dem-0.5.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.

File details

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

File metadata

File hashes

Hashes for peclet_dem-0.5.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 a34ead2d6cab18c6addad366c279f5a8843ea2b992b4e7ebf063ad1a97084dcd
MD5 71211f5168f0c662b503e88fb51ab83b
BLAKE2b-256 89cf393ff5eeb16d6a313f78725396c2d4ef9c0b60de0a83231d728371b32863

See more details on using hashes here.

Provenance

The following attestation bundles were made for peclet_dem-0.5.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.

File details

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

File metadata

File hashes

Hashes for peclet_dem-0.5.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 7d39dfeb39abd7b01eae6ad67b8b5a4ebb7046a8f9e7395fe156b1df14ad3033
MD5 378b8a246ac54effedfe69fecc1a2709
BLAKE2b-256 45bdd114fd04c0d02b606150054efbca13747db2c41e1af5b470e70bf76dea2d

See more details on using hashes here.

Provenance

The following attestation bundles were made for peclet_dem-0.5.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.

Release history Release notifications | RSS feed

0.5.1

5 files

This release

0.5.0 This release

5 files

0.4.0

5 files

0.3.2

5 files

0.3.1

5 files

0.3.0

5 files

0.2.1

5 files

0.2.0

5 files

0.1.0

5 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page