Introduction

Let’s look at the simplest simulation you can run with JaxDEM.

import tempfile
from pathlib import Path
import jaxdem as jdem

Initialize the Simulation State

First, we create a jaxdem.state.State object. It holds all per-particle data in the simulation. Let’s create a single particle at the origin. By default, jaxdem.state.State.create() fills every unspecified attribute with a sensible default value.

state = jdem.State.create(pos=[[0.0, 0.0, 0.0]])

Note that we wrote pos=[[coords]], not pos=[coords]. jaxdem.state.State.create() expects a 2-D array of shape (N, dim), so even a single particle needs a list of lists.

Initialize the Simulation System

Next, we create a jaxdem.system.System. It holds the global configuration of the simulation (domain, force model, integrator, …). Just like the state, jaxdem.system.System.create() fills in defaults for anything we don’t specify. The only requirement is that the system dimension matches the state dimension:

system = jdem.System.create(state.shape)

Run the Simulation

Finally, we advance the simulation by calling jaxdem.system.System.step():

n_steps = 10
state, system = system.step(state, system, n=n_steps)

Saving the Simulation

The last thing left to do is to save the simulation to VTK files so we can visualize it in ParaView. Writes happen asynchronously in background threads, so use the writer as a context manager (or call writer.block_until_ready() before exiting) to guarantee all files are fully written:

tmp_dir = Path(tempfile.gettempdir()) / "data"
with jdem.VTKWriter(directory=tmp_dir) as writer:
    writer.save(state, system)

Where to Go Next

Now that you have seen the simplest simulation, explore the rest of the user guide to learn about each component in depth:

• The Simulation State — particle data, fixed particles, identifiers.

• The Simulation System — system configuration, deactivating modules, batched simulations.

• The Simulation Domain — boundary conditions (free, periodic, reflective).

• Integrators and Minimizers — time integration and energy minimization.

• Materials, Matchmakers, and Material Tables — material definitions and matchmakers.

• Force Models — pairwise force laws and species-wise routing.

• The Force Manager — gravity, external forces, custom functions.

• Colliders — contact detection algorithms.

• Clumps (Rigid Bodies) — rigid bodies from multiple spheres.

• Facets (Triangular & Line Boundaries) — flat boundaries from line segments and triangles.

• Deformable Particles — elastic, deformable bodies from bonded meshes.

• VTK Post-Processing and Visualization — exporting frames for ParaView visualization.

• Checkpoint Save and Load — saving and restoring simulations.

• Custom Module Registration and System Usage — registering your own force models, domains, and integrators.