Examples and co-simulation¶
Run a C++ demo¶
From the repository root, after configuring as described in Installation:
cmake --build build --target DEMdemo_SingleSphereCollide --config Release
cd build
./bin/DEMdemo_SingleSphereCollide
On Windows, use bin/Release/DEMdemo_SingleSphereCollide.exe for a
multi-configuration Release build. Demos can create output files in the working
directory. Read each source file’s introductory comments for inputs, output,
and any prerequisite terrain preparation.
SingleSphereCollide, MeshCollide, and MeshFalling use the interactive
viewer when it is enabled. See Interactive visualization for responsive loop patterns,
the recommended PoC/small-scale scope, and simulation-throughput tradeoffs.
Python demos¶
After installing deme, run a first demo from the repository root:
python python/demos/single_sphere_collide.py --smoke-test
The three physics demos run headlessly and accept --device, --duration,
--output-dir, and --smoke-test. Use --help to inspect their options
without loading CUDA. Cold-cache initialization can take much longer than the
short simulated duration. They write output files for visualization; see
the Python demos guide for commands,
porting scope, and output instructions.
Script (under |
What it does |
|---|---|
Collides two spheres over meshes with cohesive contact; inserts the second sphere after initialization and writes contact and geometry output. |
|
Settles a polydisperse spherical bed, releases a meshed projectile, and measures penetration at the requested final time. Runs one impact rather than the C++ parameter sweep. |
|
Rotates an analytical drum containing ellipsoids and equal-mass spheres at three densities; reports contact torque. Uses larger particles than the C++ case by default to reduce the particle count. |
|
Times initialization of a one-sphere setup and reports the persistent
Jitify header-cache file size. Requires |
For smaller API-specific examples, Python quickstart runs a sphere drop,
while Retrieving simulation data demonstrates CuPy and Warp device buffers.
The docs/python/examples/ directory also includes explicit GPU selection.
Use these examples with a matching version of the installed extension.
C++ demo catalog¶
The following catalog covers every demo target in src/demo/CMakeLists.txt.
Target names have the prefix DEMdemo_; links below download the corresponding
source under src/demo/. Choose SingleSphereCollide for a first run,
MeshCollide for mesh contacts, or Mixer for a larger application.
First simulations and contact inspection¶
Demo (without |
What it does |
|---|---|
A small sphere-collision setup with mesh boundaries, cohesive material properties, runtime insertion, and contact-force inspection. A starting point for the API and interactive viewer. |
|
Collides two cube meshes above an analytical plane, demonstrating mesh universal contact, tracking, and contact-force retrieval. |
|
Drops a mixture of meshed boxes, spheres, cones, and cylinders onto a plane to exercise mesh–mesh and mesh–plane contacts. |
|
Applies an external load to the topmost particle of a granular arrangement to examine contact-chain propagation. |
|
Contains rolling-up-an-incline, falling-ellipsoid, and stacked-sphere validation cases. The current main function runs the incline case; the other calls are commented out. |
|
Loads example contact pairs and contact wildcards from CSV, attaches them to a sphere batch, and duplicates batches to exercise contact-history initialization. |
Flow, mixing, and particle generation¶
Demo (without |
What it does |
|---|---|
Releases particles through a mesh funnel to form a pile for an angle-of-repose experiment. |
|
An angle-of-repose variant using ForceModel2D.cu and particle centers sampled in the X–Z plane. |
|
Moves a bowl-shaped plow through granular material using prescribed motion. |
|
Prescribes back-and-forth motion of a clump-built sieve so sufficiently small particles can fall through. |
|
Rotates a drum represented by clumped spheres with ellipsoidal grains inside to study the granular free-surface slope. |
|
Rotates an analytical container containing grains of different shapes and densities; family labels distinguish the populations. |
|
Rotates an analytical cylindrical drum and lids containing cube mesh particles, demonstrating repeated mesh templates and mesh contacts. |
|
A smaller cube-particle setup using 10 mm cubes. The current code uses rotating planar side walls rather than the cylindrical wall described in its introductory comment. |
|
Loads mesh-particle templates from STL and rotates a meshed drum with analytical end caps to study the surface response angle. |
|
Prescribes rotation of a meshed bladed mixer through three-sphere clump particles inside a cylindrical chamber. |
|
Replaces the mixer demo’s clumps with cube mesh particles, enabling contacts with the mixer, chamber, and other cubes. |
|
Settles and discharges a mixture of spheres and cylinder-shaped clumps through a mesh funnel after opening its gate. |
|
Discharges spheres mixed with low-poly mesh cylinders by disabling a mesh plug’s contacts. Includes a small self-checking –smoke-test mode. |
|
Settles a spherical bed, inspects its height, and writes a clump checkpoint. The proposed runtime particle-enlargement loop is currently commented out. |
|
Shakes a jar of particles to explore changes in packing and bulk density. |
Impact and soil characterization¶
Demo (without |
What it does |
|---|---|
Drops a meshed ball into a loose granular bed over a sweep of projectile densities and drop heights. |
|
A ball-impact variant using ForceModel2D.cu, with a settling stage followed by release of a tracked mesh projectile. |
|
Prepares and saves a cohesionless bed, reloads its positions and orientations with a cohesive model, then presses a circular plate into it to record pressure versus sinkage. |
|
Compresses a bed of clumped particles before performing a cone-penetration test; demonstrates stepwise control of the compressor. |
|
Compresses a granular sample and uses contact-neighbor information and custom properties to examine its strain distribution. |
Terrain preparation and wheel mobility¶
Demo (without |
What it does |
|---|---|
Generates and settles batches of GRC simulant particles with a distribution of sizes and shapes; writes the initial bed for Part 2. |
|
Reads Part 1 output and replicates the settled particles to create a thicker bed. This is a large, potentially multimillion-particle case. |
|
Reads Part 2 particle positions and orientations, builds the terrain, compresses it with a plane, and saves the final bed. |
|
Drives a sphere-clump wheel with prescribed angular velocity over a bed of ellipsoidal clumps; demonstrates wheel principal-frame setup. |
|
Runs a drawbar-pull test with a meshed Curiosity wheel and prepared GRC terrain. Requires GRC_3e6.csv from the GRC preparation sequence in the working directory. |
|
Builds its own three-sphere-clump terrain and prescribes wheel translation and rotation for one slip case, measuring terrain forces without a GRC checkpoint prerequisite. |
|
Studies slip versus slope using a sphere-clump representation of a Viper-style wheel. Requires the prepared GRC_3e6.csv terrain checkpoint. |
Custom physics and coupling building blocks¶
Demo (without |
What it does |
|---|---|
Uses rigid combined groups for charged particles and a segmented mesh rod. Owner charge wildcards and a custom force model demonstrate spatially varying electrostatic interactions. |
|
Breaks a concrete bar using a custom force model with interparticle bonds and contact-history variables. |
|
Retrieves mesh-node data and prescribes deformation while interacting with grains. Illustrates the data exchange needed for flexible-body coupling; it does not include a structural solver. |
|
Uses a custom nonlocal gravitational force to model the Sun and planets. Demonstrates interactions without physical overlap; broadly expanded interaction ranges can create many candidate pairs. |
|
Implements cellular-automaton evolution with DEME’s APIs to illustrate uses beyond granular mechanics. |
Run the GRC preparation stages in order from the same working directory so
later stages can find earlier output directories. Before running WheelDP
or WheelSlopeSlip, place the final terrain checkpoint where the source
expects GRC_3e6.csv. These large terrain cases are not installation smoke
tests. Modular regression tests live separately under src/demo/ModularTests.
Co-simulation¶
DEME handles granular dynamics and exposes forces and body state to external solvers, including direct CUDA-buffer exchange with other GPU packages. Coupled applications can use another solver for joints, motors, controllers, or deformable-body mechanics. See Retrieving simulation data for host and CUDA-array exchange and Installation for installing the C++ library.
The historical feature/DEME branch of projectchrono/chrono-projects
contains Chrono coupling examples. Those examples target their corresponding
Chrono/DEME revisions and may need porting to this branch. Their CMake setup
uses Chrono_DIR, ENABLE_PROJECTS=ON, ENABLE_DEME_TESTS=ON, and
DEME_DIR after both libraries are installed.