SBEL Chrono DEM-Engine
Now version 3: GPU-accelerated discrete element simulation built for performance, with C++ and Python APIs.
DEM-Engine (DEME) simulates granular materials using one or two NVIDIA GPUs. This branch supports sphere clumps, mesh particles, analytical boundaries, rigid combined owners, and customizable contact force models. It also provides an interactive visualizer and host/device data access for co-simulation.
What's new in DEME 3?
Get started with DEME 3: installation guide — Python packages, C++ source builds, and system requirements.
- Mesh contact: mesh–mesh collisions and a new clump–mesh scheme that combines triangle contributions into patch/island contacts before evaluating forces.
- Rigid combined bodies: group members into one rigid assembly, replacing geometry-wildcard-based constructions with member-level controls.
- On-device coupling: exchange state and forces directly with other GPU packages.
- Persistent kernel caching: reuse compiled kernels across compatible repeated runs to reduce initialization time.
- Interactive visualization and expanded Python workflows.
When to stay with DEME 2: DEME 3 currently supports only NVIDIA GPUs and may use more memory. If you need non-NVIDIA GPU support, or your application does not need mesh–mesh contact or the new aggregated clump–mesh contact scheme, consider staying with DEME 2.4.2, the final DEME 2 release.
For C++, use the upstream v2.4.2 tag:
git clone --branch v2.4.2 --recurse-submodules https://github.com/projectchrono/DEM-Engine.git DEM-Engine-2.4.2
For pyDEME, explicitly pin the Python distribution: python -m pip install "deme==2.4.2".
Use version 2.4.2's installation requirements and examples for either route.
See DEME 3 features and migration considerations
for details, including the contact-model changes and memory tradeoffs.
Why use DEME?
DEME is designed for large granular simulations where particle shape, contact physics, and computational cost matter. Typical applications include mixing, hopper flow, soil penetration, wheel–terrain interaction, and granular impact.
- Complex particle shapes. Represent grains with clumped spheres or mesh particles, and build rigid assemblies with combined owners. DEME supports mesh–mesh contact, allowing mesh particles to collide with one another.
- Custom contact physics. Define your own contact force models, including cohesion, electrostatic interactions, and bonds that can break. Material properties and per-contact variables let you tailor the model to your problem.
- GPU performance. Use one or two NVIDIA GPUs, including consumer and data center hardware. As an illustrative benchmark from the main-branch README, one million three-sphere clumps simulated for one million timesteps takes around one hour on RTX 3080s. Runtime depends on the geometry, contact model, and simulation settings.
- Control over the simulation. Prescribe motion, extract forces, and update geometry to model processes such as mesh deformation or grain breakage. The examples show how to supply these behaviors through the API.
- On-device co-simulation. Exchange simulation state and forces directly with other GPU-based packages through device buffers, avoiding CPU round trips for the exchanged data. Host data access also supports coupling to solvers such as Chrono for multibody dynamics or other physics.
- C++ and Python workflows. Start with Python or integrate the C++ library into an application. The C++ API follows a Chrono-like design, and the interactive visualizer helps inspect simulations as they run.
Start here
Online documentation · Python API and methods · C++ API reference
| Task | Documentation |
|---|---|
| Install Python, build C++, or install the C++ library | Installation |
| Run a first simulation | Quickstart · Python example |
| Understand owners, families, frames, and runtime setup | Core concepts |
| Use mesh particles, templates, and combined bodies | Mesh particles |
| Find a demo to adapt | Examples · C++ sources |
| Use Python | Python guide · Demos · API reference |
| Look up the C++ API | C++ reference |
| Select GPUs or exchange simulation data | Device selection · Data access |
| Visualize results | Interactive visualization and ParaView |
| Diagnose installation or runtime errors | Troubleshooting |
| Build or host the documentation website | Build and preview · Hosting |
| Contribute or cite DEME | Project information · Architecture |
The documentation index collects the guide sources. The linked
site is currently hosted by the Ruochun fork. GitHub Actions rebuilds and publishes
it on pushes to the branch selected by that repository's DOCS_PUBLISH_BRANCH
variable. See Hosting for setup
and switching publication to main. The C++ reference is generated from headers;
the Python reference must be regenerated and committed when bindings change.
Python in brief
On a supported Linux or WSL2 host with a CUDA 12.8-compatible NVIDIA driver:
python -m pip install "deme[cuda12]"
The cuda12 extra installs CUDA runtime libraries, NVRTC, and headers through pip;
no system CUDA Toolkit installation is needed for Python wheels. This setup applies
only to the Python extension; standalone C++ applications keep their normal CUDA
configuration. Use plain pip install deme to use an existing toolkit.
import deme
solver = deme.DEMSolver()
After installation, run a Python demo from the repository root:
python python/demos/single_sphere_collide.py --smoke-test
This headless example simulates two colliding spheres over meshes and writes visualization files. The first run may take time to compile CUDA kernels. See the Python demos for more examples, command-line options, and instructions for viewing their output.
See installation requirements for wheel compatibility
and source builds. New scripts should use import deme; import DEME remains
a compatibility alias. Features in this checkout may be newer than a released wheel.
Community and license
Demo videos · Project Chrono forum · Contributors · BSD-3-Clause license · Citation
Citation
If you use DEME in your research, please cite the DEM-Engine design and usage paper:
@article{zhang_2024_deme,
title = {Chrono {DEM-Engine}: A Discrete Element Method dual-{GPU} simulator with customizable contact forces and element shape},
journal = {Computer Physics Communications},
volume = {300},
pages = {109196},
year = {2024},
issn = {0010-4655},
doi = {https://doi.org/10.1016/j.cpc.2024.109196},
author = {Ruochun Zhang and Bonaventura Tagliafierro and Colin {Vanden Heuvel} and Shlok Sabarwal and Luning Bakke and Yulong Yue and Xin Wei and Radu Serban and Dan Negruţ},
keywords = {Discrete Element Method, GPU computing, Physics-based simulation, Scientific package, BSD3 open-source},
}
For the clump-based granular solver and its application to rover dynamics, see the granular simulation paper:
@article{ruochunGRC-DEM2023,
title={A {GPU}-accelerated simulator for the {DEM} analysis of granular systems composed of clump-shaped elements},
author={Ruochun Zhang and Colin {Vanden Heuvel} and Alexander Schepelmann and Arno Rogg and Dimitrios Apostolopoulos and Samuel Chandler and Radu Serban and Dan Negrut},
year={2024},
journal={Engineering with Computers},
doi={https://doi.org/10.1007/s00366-023-01921-9}
}
Release files for deme 3.0.19
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| deme-3.0.19-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl | CPython 3.14 | CPython 3.14 | Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64 | Details |
| deme-3.0.19-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl | CPython 3.13 | CPython 3.13 | Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64 | Details |
| deme-3.0.19-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl | CPython 3.12 | CPython 3.12 | Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64 | Details |
| deme-3.0.19-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl | CPython 3.11 | CPython 3.11 | Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64 | Details |
| deme-3.0.19-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl | CPython 3.10 | CPython 3.10 | Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64 | Details |
| deme-3.0.19-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl | CPython 3.9 | CPython 3.9 | Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64 | Details |
Total release size: 264.6 MB
Release files / deme-3.0.19-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | deme-3.0.19-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 44.1 MB |
| Tags | CPython 3.14 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
8b7d03b5890ecc3d30e2cc8556ea53080da45158322a374973998011de2f5d40
|
|
BLAKE2b-256 checksum How to use checksums |
54bfeb6bd012cd6c3c07f93b4afb993e01b1794ddfb53d7098fd06c5eea118a3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.
Transparency logRelease files / deme-3.0.19-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | deme-3.0.19-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 44.1 MB |
| Tags | CPython 3.13 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
078f97a3c10d3d6e4d2ee4888f75b34b4111d545ae16fdb9483f04f3a66a6461
|
|
BLAKE2b-256 checksum How to use checksums |
482d8a9467916e9ac9c5f934927d563bcb3b4b8586cde9fa325dc41320e49201
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.
Transparency logRelease files / deme-3.0.19-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | deme-3.0.19-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 44.1 MB |
| Tags | CPython 3.12 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
390925c15739295e069791bf046ffb4cbdc2815ed8fe8d43b40c5ee63bf9c6bb
|
|
BLAKE2b-256 checksum How to use checksums |
0b69115b357b6f265e552c40d9e1eefe57028e28b72ea1786f961db407c1a4a3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.
Transparency logRelease files / deme-3.0.19-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | deme-3.0.19-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 44.1 MB |
| Tags | CPython 3.11 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
59e3e42e664c31836f4ee0b4037d5b29f4d59927dabc4244ff3f465543eb8647
|
|
BLAKE2b-256 checksum How to use checksums |
ea275e47f40109dda842824870bacd15c60a685981fe27f5b4e662f2ad8676b4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.
Transparency logRelease files / deme-3.0.19-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | deme-3.0.19-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 44.1 MB |
| Tags | CPython 3.10 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
0965fda5b55046eda536ae19eca8da705d3b6ff090a0262b330013f1a9591377
|
|
BLAKE2b-256 checksum How to use checksums |
ee69c431e85d92b8b80752b3ff610523f1e73f66d8e4a0d45f4a47886fdbf04a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.
Transparency logRelease files / deme-3.0.19-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | deme-3.0.19-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 44.1 MB |
| Tags | CPython 3.9 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
6d2dc183548233b311e573a0d9d1a47488a26f9b68797ff19282063b6f1c4d86
|
|
BLAKE2b-256 checksum How to use checksums |
a66cce595eb36085b3bb78d9c566f6b7b1a0e55025a43cc8a5f8e4a4b6044e17
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.
Transparency log
