Python toolkit for DEM simulation & analysis

View project on GitHub

Welcome to the PyGran webpage!

PyGran is an open-source toolkit primarily designed for analyzing DEM simulation data. In addition to performing basic and custom post-processing, PyGran enables running DEM simulation with LIGGGHTS in Python. It’s recommended to use PyGran with Python 3.7 or higher versions. If you wish to use PyGran’s mesh capabilities via VTK, Python<=3.8 is recommended.

The main features of PyGran:

  • Interactive DEM simulation and/or analysis using Python
  • Parallel “multiple parameter, single script” simulation for parametrization and sensitivity analysis
  • Intuitive syntax for particle manipulation and analysis (e.g. slicing, concatenating, etc.)
  • Post-processing coupled particle-mesh DEM simulation with VTK
  • Quick and easy plotting of DEM data with matplotlib
  • Support for high-performance computing with MPI

The core modules in PyGran are:

  • simulation: provides APIs for running DEM simulation
  • analysis: provides methods and algorithms for post-processing DEM data
  • params: defines material properties

If you find PyGran useful in your research, please consider citing the following paper:

DOI for Citing PyGran

  title={PyGran: An object-oriented library for DEM simulation and analysis},
  author={Abi-Mansour, Andrew},

Quick Installation

Installing PyGran is quite straight forward on a Unix/Unix-like machine. Just fire up a terminal and then use pip (or pip3) to install PyGran:

pip install PyGran

For more options and information on setting up PyGran on Ubuntu 18.04 (LTS), see the installation page.

Basic Usage

Running DEM simulation with LIGGGHTS

PyGran also provides an interface for running DEM simulation with LIGGGHTS. This is achieved by importing the simulation module as shown in the script below for simulating granular flow in a hopper.

from PyGran import simulation
from PyGran import params

# Create a DEM object for simulation
sim = simulation.DEM(
    boundary=("f", "f", "f"),
    box=(-1e-3, 1e-3, -1e-3, 1e-3, 0, 4e-3),
            "material": params.stearicAcid, 
            "radius": ("constant", 5e-5)},
    gravity=(9.81, 0, 0, -1),
        "hopper": {
            "file": "silo.stl",
            "mtype": "mesh/surface",
            "material": params.steel,

# Insert 1000 particles for species 1 (stearic acid)
insert = sim.insert(species=1, value=1000)

# Evolve the system in time, dt=1e-7)

Post-processing DEM output data

Using PyGran for doing post-analysis is also quite straight forward. Computing particle overlaps shown below for instance can be done in few lines of code:

from PyGran import analysis

# Instantiate a System class from a dump file
sys = analysis.System(Particles='granular.dump')

# Instantiate a nearest-neighbors class
NNS = analysis.Neighbors(Particles=sys.Particles)
overlaps = NNS.overlaps

For more examples on using PyGran for running DEM simulation, check out the examples page.

Questions or suggestions?

If you’d like to chat with us, we are available on slack:


For reporting bugs or suggesting new features/improvements to the code, please open an issue.