What is PyGran?¶
PyGran is an object-oriented library written primarily in Python for Discrete Element Method (DEM) simulation and analysis. The main purpose of PyGran is to provide an easy and intuitive way for performing technical computing in DEM, enabling flexibility in how users interact with data from the onset of a simulation and until the post-processing stage. In addition to providing a brief tutorial on installing PyGran for Unix systems, this manual focuses on 2 core modules (Fig. 1) in PyGran :
simulation which provides
engines for running DEM simulation and enables analysis of contact mechanical models, and
analysis which contains methods and submodules for processing DEM data. PyGran is released under the GNU General Public License (GPL v2.0), and its code base is available from github.
Brief summary of DEM¶
The Discrete Element Method (DEM) is the application of Newtonian mechanics to a set of interacting particles that are usually assumed to be spherical in shape. For a spherical particle that undergoes translation and rotation and of moment of inertia and volume , its dynamical equations are
The true mass density of the particles is , is the surface contact force between particle and its neighbors (summed over ), is a body force acting on particle (such as gravity, i.e. ), and is the torque between particle and its neighbors that is limited by the static friction coefficient .
DEM simulation involves the numerical solution of Eqs. (1) by decomposing the space the particles occupy into a grid of connected nearest-neighbor lists that enable fast and efficient computation of inter-particle surface forces. For every discrete timestep, all forces acting on each particle are computed, and the particle positions are updated based on the discretized form of Eqs. (1).
The form of the surface contact forces depends on the type of the bodies interacting with each other. Visco-elastic particles for instance can be modeled as two connected spring-dashpots. More sophisticated models assume particles behave as elasto-plastic spheres that undergo plastic deformation when the pressure exceeds a yield stress characteristic of the material the particles are composed of. Irrespective of the method energy dissipation is modeled, DEM usually assumes the two spherical particles in contact experience an elastic repulsive force that follows Hertz’ law. In addition to dissipation, the particles can experience an attractive cohesive force depending on their size. The contact models implemented in PyGran are discussed in the Simulation pat. For a comprehensive review of DEM and contact mechanics, see [PoschelS05].
As of version 1.1, PyGran supports non-spherical particle simulation with the multisphere method (MS-DEM) [KERWS08]. In this method, non-spherical particles are approximated by a series of spheres glued together as shown in Fig. 3.
In the current version, PyGran is configured to run on Unix or Unix-like operating systems. While PyGran can be run on a Windows platform, it has not yet been fully tested. PyGran supports Python 3.X and is fully backwards compatible with Python 2.7 (and later verions). The table in PyGran’s documentation summarizes some of the technical details of the PyGran source code.
PyGran is designed to work in conjunction with NumPy, SciPy, and other Python libraries. The following packages must be installed before PyGran is configured to run:
If PyGran is installed via the Python Package Index (PyPi), then all of the core dependencies will be installed as well. However, for optimal performance, it is recommended that cython is installed on the system. How to setup and install PyGran is explained in the next section.
Quick installation with PyPi¶
The easiest way to install the latest stable version of PyGran is with PyPi:
pip install pygran --user
Similarly one could use pip3 to install PyGran for Python 3.X. For optimal and full performance, gcc and OpenMPI/MPICH2 must be installed (on Linux):
pip install cython pygran --user
Stable source code¶
Even though git is not required to install or run PyGran, its availability makes it easier and convenient to download the latest version of the source code via:
git clone https://github.com/Andrew-AbiMansour/PyGran
This clones the repository to a directory called PyGran:
For updating an existing repository, git can be used to sync the source code with the online repository via:
git pull origin master
Alternatively, one can download the source code as a tar ball (or zip file) from github, and then manually extract the files. PyGran uses Python’s setuptools to check for and/or download dependencies. As of version 1.2.0, PyGran uses a submodular design. In order to clone all the core submodules, you must run:
git submodule init git submodule update
You can now use pip to install PyGran or for strictly building the package, run from the
python setup.py build
For a local installation, run from the
python setup.py install --user
For a comprehensive list of options on running setup.py, see the doc strings in setuptools.
Development source code¶
An experimental version of the code can be downloaded from github and then installed using the method described in the Stable source code subsection, except the branch to pull the source code from is
git checkout develop
PyGran can then be installed following the steps outlined previously.
Configuration with LIGGGHTS¶
PyGran has been tested with LIGGGHTS-PUBLIC versions 3.4, 3.7, and 3.8. For running DEM simulation with LIGGGHTS, the latter must be compiled as a shared library (shared object on Unix/Linux systems), which PyGran will attempt to find. By default, PyGran searches for any available installation of
libliggghts.so and writes its path name to the 1st line in
~/.config/PyGran/liggghts.ini. PyGran will also attempt to find the LIGGGHTS version and source path, and write each to the 2nd and 3rd lines, respectively, in the .ini file. Alternatively, in case multiple versions are installed on the system or if the library filename is not
libliggghts.so, users can specify the name of the shared object and optionally its source code path and version via:
import PyGran PyGran.configure( path='/home/user/.local/lib/custom_libliggghts.so', version='3.8.0', src='/path/to/LIGGGHTS-3.8.0/src' )
This produces a
~/.config/PyGran/liggghts.ini file for LIGGGHTS v3.8 shown below:
library=/home/user/.local/lib/custom_libliggghts.so src=/path/to/LIGGGHTS-3.8.0/src version=3.8.0
config.ini file is not found, PyGran will create one.
PyGran’s setup enables the compilation of LIGGGHTS-PUBLIC from its source code available on the CFDEM github repository via:
python setup.py build_liggghts
The command above will clone the LIGGGHTS-PUBLIC repository and compile the code as a shared library (
LIGGGHTS-PUBLIC/src. This requires git, gcc, and an MPI installation available on the system.
Installation example: ubuntu 18.04 (LTS)¶
The section below covers a fresh local installation of PyGran & LIGGGHTS form source code. They have been tested with python 3, gcc v7.x, and LIGGGHTS v3.8. For global installs, remove
--user from the commands and use
First, fire up a terminal in order to update the system and install all dependencies via:
sudo apt-get update && sudo apt-get install gcc libopenmpi-dev python3-setuptools python3-pip ipython3 git python3-matplotlib libvtk6-dev -y
Let’s now clone the PyGran source code:
git clone https://github.com/Andrew-AbiMansour/PyGran.git cd PyGran git submodule init git submodule update
Let’s locally install PyGran dependencies with pip:
pip3 install -e .[extra] --user
If LIGGGHTS is not available as a shared library, run:
python3 setup.py build_liggghts
This will clone the LIGGGHTS-PUBLIC repository and compile the code as a shared object. The process takes a few minutes to finish. Once this is done, we can finally install PyGran:
pip3 install . --user
Let’s run a simple flow problem in order to make sure everything works fine. Open a terminal and run from the source dir:
python3 -m tests DEM flow
The process should take about 1-5 mins to finish, depending on the core clock cycle. If successful, this command should create an output directory (‘DEM_flow’) which contains the trajectory and restart files stored in ‘traj’ and ‘restart’ directories, respectively.
In order to test the analysis module, run from the source dir:
python3 tests/scripts/Particle-Analysis/basics/basics.py "DEM_flow/traj/particles*.dump"
The process should take few seconds to execute.