simulation.PyGranSim.engine_liggghts

Python wrapper for LIGGGHTS library via ctypes

Created on March 30, 2016

Author: Andrew Abi-Mansour

This is the:

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

DEM simulation and analysis toolkit http://www.pygran.org, support@pygran.org

Core developer and main author: Andrew Abi-Mansour, andrew.abi.mansour@pygran.org

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 http://www.gnu.org/licenses . 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 http://lammps.sandia.gov, Sandia National Laboratories Steve Plimpton, sjplimp@sandia.gov

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.

Classes

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

A class that implements a python interface for DEM computations

liggghts

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.

gen()[source]

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

Parameters
  • 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.

file(file)[source]

Function for loading LIGGGHTS input file scripts.

Parameters

file (str) – input filename

Note

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

command(cmd)[source]

Function for executing a LIGGGHTS command

Parameters

cmd (str) – input LIGGGHTS command

Note

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

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

Bases: object

A class that implements a python interface for DEM computations

Parameters
  • 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.

Todo

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

Initialize some settings and specifications

createDomain()[source]

Define the domain of the simulation

setupParticles()[source]

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.

Parameters
  • 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)

Todo

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

Parameters
  • 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: https://www.cfdem.com/media/DEM/docu/fix_move_mesh.html

importMeshes(name=None)[source]

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)

Todo

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

remove(name)[source]

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!

createGroup(*group)[source]

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(*args)[source]

Set group/atom attributes

setupNeighbor(**params)[source]

Sets up NNS list parameters

createProperty(name, *args)[source]

Material and interaction properties required

setupPhysics()[source]

Specify the interation forces

velocity(*args)[source]

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

Note

See link for info on keywords and their associated values.

setupGravity()[source]

Specify in which direction the gravitational force acts

initialize(**params)[source]
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

printSetup()[source]

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.

extractCoords()[source]

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

monitor(**args)[source]

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

returns the mean variable as a scalar

addViscous(**args)[source]

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

F = - \gamma v

Parameters
  • 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]
command(cmd)[source]

Passes a specific command to LIGGGHTS

resume()[source]
readData()[source]