Python wrapper for LIGGGHTS library via ctypes

Created on March 30, 2016

Author: Andrew Abi-Mansour

This is the:

██████╗ ██╗   ██╗ ██████╗ ██████╗  █████╗ ███╗   ██╗
██╔══██╗╚██╗ ██╔╝██╔════╝ ██╔══██╗██╔══██╗████╗  ██║
██████╔╝ ╚████╔╝ ██║  ███╗██████╔╝███████║██╔██╗ ██║
██╔═══╝   ╚██╔╝  ██║   ██║██╔══██╗██╔══██║██║╚██╗██║
██║        ██║   ╚██████╔╝██║  ██║██║  ██║██║ ╚████║
╚═╝        ╚═╝    ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝

DEM simulation and analysis toolkit,

Core developer and main author: Andrew Abi-Mansour,

PyGran is open-source, distributed under the terms of the GNU Public License, version 2 or later. It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. You should have received a copy of the GNU General Public License along with PyGran. If not, see . See also top-level README and LICENSE files.

This file was modified from the LAMMPS source code.

LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator, Sandia National Laboratories Steve Plimpton,

Copyright (2003) Sandia Corporation. Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains certain rights in this software. This software is distributed under the GNU General Public License.

See the README file in the top-level LAMMPS directory.


DEMPy(split, library, style, **pargs)

A class that implements a python interface for DEM computations


class simulation.PyGranSim.engine_liggghts.RandPrime[source]

Bases: object

Random prime number generator with memory. The idea is to generate a unique prime number for LIGGGHTS.


Hackish ~ silly way of LIGGGHTS using prime numbers > 10000 for unfounded reasons

class simulation.PyGranSim.engine_liggghts.Liggghts(library=None, style='spherical', dim=3, units='si', path=None, cmdargs=[], comm=None, ptr=None)[source]

Bases: object

A class that provides API-like access to LIGGGHTS-PUBLIC

  • library (str) – full path to the LIGGGHTS-PUBLIC module (.so file)

  • style (str) – particle type (‘spherical’ by default)

  • dim (int) – simulation box dimension (default 3)

  • units (str) – unit system (default ‘si’). See here for available options.


Function for loading LIGGGHTS input file scripts.


file (str) – input filename


For python 3, “file” is encoded as an 8 character utf


Function for executing a LIGGGHTS command


cmd (str) – input LIGGGHTS command


For python 3, “cmd” is encoded as an 8 character utf

MPI = <module 'mpi4py.MPI' from '/usr/lib/python3/dist-packages/mpi4py/'>
class simulation.PyGranSim.engine_liggghts.DEMPy(split, library, style, **pargs)[source]

Bases: object

A class that implements a python interface for DEM computations

  • units (str) – unit system (default ‘si’). See ref.

  • style (str) – particle type (‘spherical’ by default)

  • split – MPI communicator

  • species (tuple) – defines the number and properties of all species

  • output (str) – output dir name

  • print (tuple) – specify which variables to print to stdout: (freq, ‘varName1’, ‘varName2’, …). Default is (10**4, ‘time’, ‘dt’, ‘atoms’).

  • library (str) – full path to the LIGGGHTS-PUBLIC module (.so file)

  • dim (int) – simulation box dimension (2 or 3)

  • restart (tuple) – specify restart options via (freq=int, dirname=str, filename=str, restart=bool, frame=int)

  • boundary (tuple) –

    setup boundary conditions (see ref), e.g. (‘p’, ‘p’, ‘p’) -> periodic boundaries in 3D.


This class should be generic (not specific to liggghts), must handle all I/O, garbage collection, etc. and then moved to

Initialize some settings and specifications


Define the domain of the simulation


Setup particle for insertion if requested by the user

insert(species, value, **args)[source]

This function inserts particles, and assigns particle velocities if requested by the user. If species is ‘all’, all components specified in SS are inserted. Otherwise, species must be the id of the component to be inserted. For available region shapes, see ref. The default region is the whole system.

  • species – species id (‘all’, or 1, 2, … )

  • value (float) – number of particles, or volume fraction, or mass fraction, or etc.

  • region (tuple) – define region via (‘shape’, (xmin, xmax, ymin, ymax, zmin, zmax)) or (‘shape’, xmin, xmax, ymin, ymax, zmin, zmax)


Support insertion of all or multiple species at the same time for multiple regions.

run(nsteps, dt=None, itype=None)[source]

Runs a simulation for number of steps specified by the user

  • nsteps (int) – number of steps the integrator should take

  • itype (str) – specifies integrator type: ‘sphere’ (rotational motion on) or ‘rigid_sphere’ (rotational motion off)

  • dt (float) – timestep

moveMesh(name, **args)[source]

Control how a mesh (specified by name) moves in time

@name: string specifying mesh ID/name @args: keywords specific to LIGGGHTS’s move/mesh command:


Imports all meshes and sets them up as walls. Can import only one mesh specified by the ‘name’ keyword. @file: mesh filename @mtype: mesh type @args: additional args

importMesh(name, file, mtype, material, **args)[source]

Imports a specific surface mesh requested by the user

setupWall(wtype, species=None, plane=None, peq=None)[source]

Creates a wall @ wtype: type of the wall (primitive or mesh) @ plane: x, y, or z plane for primitive walls @ peq: plane equation for primitive walls

This function can be called only ONCE for setting up all mesh walls (restriction from LIGGGHTS)


Support additional keywords (shear, etc.) for primitive walls


Deletes a specified fix. If the fix is for a mesh, we must unfix it and re-import all meshes again and setup them up as walls. Very tedious!


Create groups of atoms. If group is empty, groups{i} are created for every i species.

createParticles(type, style, *args)[source]

Creates particles of type ‘type’ (1,2, …) using style ‘style’ (box or region or single or random) @[args]: ‘basis’ or ‘remap’ or ‘units’ or ‘all_in’


Set group/atom attributes


Sets up NNS list parameters

createProperty(name, *args)[source]

Material and interaction properties required


Specify the interation forces


Assigns velocity to selected particles. :param args: group-ID style args keyword value :type args: tuple


See link for info on keywords and their associated values.


Specify in which direction the gravitational force acts

setupIntegrate(itype=None, group=None)[source]

Specify how Newton’s eqs are integrated in time. MUST BE EXECUTED ONLY ONCE. .. todo:: Extend this to super-quadric particles

integrate(steps, dt=None)[source]

Run simulation in time


Specify which variables to write to file, and their format

writeSetup(only_mesh=False, name=None)[source]

This creates dumps for particles and meshes in the system. In LIGGGHTS, all meshes must be declared once, so if a mesh is removed during the simulation, this function has to be called again, usually with only_mesh=True to keep the particle dump intact.


Extracts atomic positions from a certian frame and adds it to coords


Computes time-averaged quantities of a global vector. @species: @name: @var: @[nevery: 1 @[nrepeat: 1 @[nfreq]: 1

returns the mean variable as a scalar


Adds a viscous damping force F proportional to each particle’s velocity v:

F = - \gamma v

  • species (int) – species index (0, 1, …)

  • gamma (positive float) – viscosity coefficient (\gamma)

  • scale (tuple) – (species, ratio) tuple to scale gamma with

plot(fname, xlabel, ylabel, output=None, xscale=None)[source]
saveas(name, fname)[source]

Passes a specific command to LIGGGHTS