lammps package¶

Submodules¶

lammps.core module¶

LAMMPS Python interface (the GOOD parts)

This interface is inspired by HOOMD and tries its best to look similar. I try to include only orthogonal functions (e.g. make there only be ONE way to do something).

class lammps.core.Atom¶

Bases: object

Represents a single atom in the LAMMPS simulation

Since LAMMPS is a distributed system each atom is unique among all the processors.

lammps : lammps.core.Lammps: Lammps object
tag : int: tag id number of particle
lindex : int: lindex: the local index of the atom

charge¶: Charge of local atom

force¶: Force on local atom

position¶: Position of local Atom

tag¶: Unique tag of atom within LAMMPS simulation

type¶: AtomType of local Atom

velocity¶: Velocity of local atom

class lammps.core.AtomType¶

Bases: object

Represents an atom type (denoted by int) in LAMMPS

Provides a wrapper over atom types that is more user friendly

lammps : lammps.Lammps: Lammps object
index : int: the index of the atom

index¶: Index of atom type

mass¶: Mass of the AtomType

class lammps.core.Box¶

Bases: object

Represents the shape of the simulation cell

lammps : lammps.core.Lammps: LAMMPS Object

angles¶: Calculates lengths from lammps box. See lengths_angles()

bounds¶

LAMMPS box description of boxhi and boxlo bounds

Additional documentation can be found at lammps. For example return numpy array would be

lohi = np.array([
    [0.0, 10.0],
    [0.0, 10.0],
    [0.0, 10.0],
])

dimension¶: The dimension of the lammps run either 2D or 3D

from_lattice_const(self, atom_types, lengths, angles=None, origin=(0, 0, 0), region_id='lammps-box')¶

Create Unit cell (can only be run once)

atom_types : int

number of atom types for simulation (I know weird place to require)

lengths : vector

lengths length 3 (a, b, c) lattice constants

angles : vector

angles length 3 (alpha, beta, gamma) lattice constants default (pi/2, pi/2, pi/2)

region_id : str

name of region for lammps simulation. default ‘lammps-box’

rotation_matrix, origin: tuple

necissary matricies to be used with transform_cartesian_vector_to_lammps_vector to transform all atom positions, velocities appropriately. If unit cell is orthogonal then you may only need to apply the origin shift.

Essentially runs: region region-id prism xlo xhi ylo yhi zlo zhi xy xz yz create_box N region-ID keyword value …

lengths¶: Calculates lengths from lammps box. See lengths_angles()

lengths_angles¶

Calculates the lengths and angles from lammps box

Additional documentation can be found at lammps. See implementation lammps_box_to_lattice_const().

origin¶

tilts¶

LAMMPS box description of xy xz yz

Additional documentation can be found at lammps. For example a return dictionary would be

tilts = np.array([0.0, 0.0, 0.0])

update_lattice_const(self, lengths, angles=None, origin=(0, 0, 0))¶

Update Unit cell

lengths : vector

lengths length 3 (a, b, c) lattice constants

angles : vector

angles length 3 (alpha, beta, gamma) lattice constants default (pi/2, pi/2, pi/2)

Does not adjust the atom coordinates. However it does set the global box, set processor grid, and set local box correctly.

Warning

This does not update the atom coordinates. This means that they can easily be lost!

rotation_matrix, origin: tuple: necissary matricies to be used with transform_cartesian_vector_to_lammps_vector to transform all atom positions, velocities appropriately. If unit cell is orthogonal then you may only need to apply the origin shift.

volume¶: Volume of box given in lammps units

class lammps.core.Compute¶

Bases: object

Extract compute object property from LAMMPS system

See compute for more information on available computes. This is how properties of systems can be exctracted without I/O. See list of available computes <http://lammps.sandia.gov/doc/Section_commands.html#cmd-5>

lammps : lammps.Lammps: Lammps object
id : str: name id for lammps compute must be unique
style : str: compute style to use see LAMMPS documentation Compute styles
group : str: group to apply compute on. default “all” must create group if using other group. See group command if creating own group
args : list[str]: list of additional arguments to supply.

modify(self, args)¶

Modify a predefined LAMMPS compute

args : list[str]: args to modify lammps compute

See compute_modify for more information on args etc.

name¶: Name of compute id

scalar¶

Scalar value of compute

float: scalar value of compute

NotImplementedError: no scalar function for this compute defined

style¶: style of compute id

vector¶

vector value of compute

np.ndarray: vector value of compute

NotImplementedError: no vector function for this compute defined

class lammps.core.Lammps¶

Bases: object

LAMMPS base class represents the entire library.

units : str

units to use for simulation default lj

style : str

atomic style to use for simulation. default atomic

comm : mpi4py.Comm

default value is MPI_COMM_WORLD

args : list[str]

command line args that would be supplied to normal lammps executable

Possible values for the following arguments:

AVAILABLE_UNITS = {'cgs', 'electron', 'lj', 'metal', 'micro', 'nano', 'real', 'si'}¶

box¶: box: lammps.core.Box

check_error(self)¶: Check for error from lammps

command(self, str cmd)¶

Run a LAMMPS command

command : str: command for lammps to execute

str: output from running command

See lammps documentation for available commands.

dt¶: Timestep size for run step in simulation time units

file(self, str filename)¶

Read in a file as sequential list of commands

filename : str: filename of input file for LAMMPS

Can be invoked more than once

reset(self)¶

Resets (clear) the lammps simulation

Deletes all atoms, restores all settings to their default values, and frees all memory allocated by LAMMPS. Equivalent to the LAMMPS clear command. Some settings are not affected. These include: working directory, log file status, echo status, and input script variables.

run(self, long steps, bool pre=True, bool post=True)¶

Runs the lammps simulation for N steps

steps : int: number of steps to run simulation equivalent to “run <steps>” command
pre : bool: before run create neighbor lists, compute forces, and imposes fix contraints. default True
post : bool: print full timing summary

See lammps documentation for description of run command

system¶: system: lammps.core.System

thermo¶: thermo: lammps.core.Thermo

time¶: total time that has elapsed from lammps runs time units

time_step¶: current number of timesteps that have been run

units¶

Unit style used in lammps simulation

See units for more information.

exception lammps.core.LammpsAbortError¶: Bases: lammps.core.LammpsError

class lammps.core.LammpsDataTypes¶

Bases: object

BIG_INT¶: alias of numpy.int64

DOUBLE¶: alias of numpy.float64

IMAGE_INT¶: alias of numpy.int32

INT¶: alias of numpy.int32

SMALL_INT¶: alias of numpy.int32

TAG_INT¶: alias of numpy.int32

exception lammps.core.LammpsError¶: Bases: Exception

exception lammps.core.LammpsNormalError¶: Bases: lammps.core.LammpsError

class lammps.core.System¶

Bases: object

Represents all the atoms and respective properties in the LAMMPS simulation

Since LAMMPS is a distributed system each processor has a local view of its Atoms. This class hopes to provide both and local and global view of the properties.

lammps : lammps.core.Lammps: LAMMPS Object
style : str: one the atom_styles

ATOM_STYLE_PROPERTIES = {'angmom': (<class 'numpy.float64'>, 3), 'contact_radius': (<class 'numpy.float64'>, 1), 'cs': (<class 'numpy.float64'>, 1), 'csforce': (<class 'numpy.float64'>, 1), 'cv': (<class 'numpy.float64'>, 1), 'damage': (<class 'numpy.float64'>, 1), 'de': (<class 'numpy.float64'>, 1), 'dpdTheta': (<class 'numpy.float64'>, 1), 'drho': (<class 'numpy.float64'>, 1), 'e': (<class 'numpy.float64'>, 1), 'edpd_temp': (<class 'numpy.float64'>, 1), 'eff_plastic_strain': (<class 'numpy.float64'>, 1), 'eff_plastic_strain_rate': (<class 'numpy.float64'>, 1), 'ellipsoid': (<class 'numpy.float64'>, 1), 'eradius': (<class 'numpy.float64'>, 1), 'erforce': (<class 'numpy.float64'>, 1), 'ervel': (<class 'numpy.float64'>, 1), 'ervelforce': (<class 'numpy.float64'>, 1), 'etag': <class 'numpy.int32'>, 'f': (<class 'numpy.float64'>, 3), 'id': (<class 'numpy.int32'>, 1), 'image': (<class 'numpy.int32'>, 1), 'line': (<class 'numpy.float64'>, 1), 'mask': (<class 'numpy.int32'>, 1), 'mass': (<class 'numpy.float64'>, 1), 'molecule': (<class 'numpy.int32'>, 1), 'mu': (<class 'numpy.float64'>, 3), 'omega': (<class 'numpy.float64'>, 3), 'q': (<class 'numpy.float64'>, 1), 'radius': (<class 'numpy.float64'>, 1), 'rho': (<class 'numpy.float64'>, 1), 'rmass': (<class 'numpy.float64'>, 1), 's0': (<class 'numpy.float64'>, 1), 'smd_data_9': (<class 'numpy.float64'>, 3), 'smd_stress': (<class 'numpy.float64'>, 3), 'spin': (<class 'numpy.int32'>, 1), 'torque': (<class 'numpy.float64'>, 3), 'tri': (<class 'numpy.float64'>, 1), 'type': (<class 'numpy.int32'>, 1), 'v': (<class 'numpy.float64'>, 3), 'vest': (<class 'numpy.float64'>, 3), 'vforce': (<class 'numpy.float64'>, 1), 'vfrac': (<class 'numpy.float64'>, 3), 'x': (<class 'numpy.float64'>, 3), 'x0': (<class 'numpy.float64'>, 3)}¶

AVAILABLE_ATOM_STYLES = ['angle', 'atomic', 'body', 'bond', 'chargedipole', 'electron', 'ellipsoid', 'full', 'line', 'meso', 'molecular', 'peri', 'smd', 'sphere', 'template', 'tri', 'wavepacket']¶

add_ase_structure(self, structure, elements=None)¶

Initialize lammps system from ase Atoms (sets lattice, positions, velocities)

structure: pymatgen.core.structure.Structure: pymatgen structure where lattice, atom positions, and if velocities are present they will be set.
elements: list of tuple representing the symbol, mass: list of tuples that determine the index of each atom type. If not specified it is determined from structure

elements: list of pymatgen.core.Atom: list of elements that specifies the repective index of each element assigned by lammps.

add_pymatgen_structure(self, structure, elements=None)¶

Initialize lammps system from pymatgen structure (sets lattice, positions, velocities)

structure: pymatgen.core.structure.Structure: pymatgen structure where lattice, atom positions, and if velocities are present they will be set.
elements: list of pymatgen.core.Species: list of pymatgen.core.Species that determine the index of each atom type. If not specified it is determined from structure

elements: list of pymatgen.core.Species: list of elements that specifies the repective index of each element assigned by lammps.

atom_types¶: AtomTypes in lammps system return list of AtomTypes

charges¶: Charges associated with global atoms sorted by tag id

create_atoms(self, int[:] atom_types, double[:, :] positions, double[:, :] velocities=None, start_index=None, bool wrap_atoms=True)¶

Create atoms for LAMMPS calculation.

If atoms already exist on the system you will need to change the atom “start_id_index” to greater than the max value.

atom_types : list[int], np.array[int]: vector of atom types
positions : np.array[Nx3]: array of atom positions
velocities : np.array[Nx3]: array of atom velocities. default set all velocities to 0
start_index : int: index to start atom ids

forces¶: Forces associated with global atoms sorted by atom tag id

global_gather_property_ordered(self, str name)¶

Gather globally system property to single processor. Sorted by atom id.

Available properties are in :var:`System.ATOM_STYLE_PROPERTIES`

name : str: atom property name to gather

global_gather_property_subset(self, str name, int[:] atom_ids)¶

Gather subset of atom properties in the system.

Available properties are in :var:`System.ATOM_STYLE_PROPERTIES`

name : str: atom property name to gather
atom_ids : list[int], np.ndarray: atom ids to get properties from

global_gather_property_unordered(self, str name)¶

Gather globally system property to single processor. Data is not sorted.

You can gather atom id beforehand to get order of atoms.

Available properties are in :var:`System.ATOM_STYLE_PROPERTIES`

name : str: atom property name to gather

global_scatter_property_ordered(self, str name, data)¶

Scatter globally system property to all processors. Sorted by atom id.

Available properties are in :var:`System.ATOM_STYLE_PROPERTIES`

I HIGHLY recommend to not set atom positions with this method. It will result in lost atoms instead use create_atoms if not used properly - https://sourceforge.net/p/lammps/mailman/message/35842978/

global_scatter_property_subset(self, str name, int[:] atom_ids, data)¶

Scatter globally system property for subset of atoms to all processors.

Available properties are in :var:`System.ATOM_STYLE_PROPERTIES`

I HIGHLY recommend to not set atom positions with this method. It will result in lost atoms instead use create_atoms if not used properly - https://sourceforge.net/p/lammps/mailman/message/35842978/

local_total¶

Local number of atoms stored on processor

An important concept in LAMMPS parallal calculations is that the atoms are distributed between all the processors.

positions¶: Positions associated with global atoms sorted by atom tag id

Note

Reseting the atom positions is dangerous since it remaps the atoms to processors. I HIGHLY recommend create_atoms instead.

snapshot(self, elements, atom_properties=None, format='pymatgen')¶

Get python structure representation of LAMMPS simulation (pymatgen only for now)

Assumes origin at (0, 0, 0)!

elements: list of elements: ordered list of elements associated with lammps atom id
atom_properties: set: set of ATOM_STYLE_PROPERTIES that you want included with structure
format: str: for now only “pymatgen” structure and “hoomd” gsd snapshot format is supported

snapshot: pmg.Structure or gsd.hoomd.Snapshot: pymatgen structure

style¶: The LAMMPS atom_style used in simulation

tags¶: Tags associated with local atoms stored on processor

total¶: Total number of atoms in LAMMPS simulation

types¶: Atom type ids associated with global atoms

velocities¶: Velocities associated with global atoms sorted by atom tag id

class lammps.core.Thermo¶

Bases: object

Computes thermodynamic properties of a group of particles

You must first define a compute before you can extract thermodynamics properties of the current time step. Three computes are always created, named “thermo_temp”, “thermo_press”, and “thermo_pe” these are initialized in the output.cpp in LAMMPS. These computes are made easy to access. All computes can be accessed via the comptutes dictionary.

lammps : Lammps: lammps object

add(self, str id, str style, str group='all', args=None)¶

Add a compute to LAMMPS

id : str: name of new LAMMPS compute must be unique
style : str: name of compute to add
group : str: name of compute group. default ‘all’.
args : list[str]: additional args to supply to compute

Equivalent lammps command: compute ID group-ID style args

See compute for more information on creating computes.

computes¶: Dictionary of available computes

potential_energy¶: potential_energy: lammps.core.Compute

pressure¶: pressure: lammps.core.Compute

temperature¶: temperature: lammps.core.Compute

lammps.core.abs_cap(val, max_abs_val=1)¶

Returns the value with its absolute value capped at max_abs_val. Particularly useful in passing values to trignometric functions where numerical errors may result in an argument > 1 being passed in.

Args:: val (float): Input value. max_abs_val (float): The maximum absolute value for val. Defaults to 1.
Returns:: val if abs(val) < 1 else sign of val * max_abs_val.

lammps.core.lammps_box_to_lattice_const(bounds, tilts)¶

Converts lammps box coordinates to lattice constants and origin

\[a &= lx \ b &= \sqrt{ly^2 + xy^2} \ c &= \sqrt{lz^2 + xz^2 + yz^2} \ \cos{lpha} &= \]

rac{xy xz + ly yz}{b c}: cos{eta} &=
rac{xz}{c}: cos{gamma} &=

rac{xy}{b}

lammps.core.lattice_const_to_lammps_box(lengths, angles, origin=(0, 0, 0))¶

Converts lattice constants to lammps box coorinates(angles in radians)

\[lx &= boxhi[0] - boxlo[0] = a \ ly &= boxhi[1] - boxlo[1] = \sqrt{b^2 - xy^2} \ lz &= boxhi[2] - boxlo[2] = \sqrt{c^2 - xz^2 - yz^2} xy &= b \cos{\gamma} \ xz &= c \cos{eta} \ yz &= \]

rac{b c cos{lpha} - xy xz}{ly}

lammps.core.lengths_angles_to_matrix(a, b, c, alpha_r, beta_r, gamma_r)¶

Create a Lattice using unit cell lengths and angles (in radians).

Args:: a (float): a lattice parameter. b (float): b lattice parameter. c (float): c lattice parameter. alpha (float): alpha angle in radians. beta (float): beta angle in radians. gamma (float): gamma angle in radians.

lammps.core.transform_cartesian_vector_to_lammps_vector(points, rotation_matrix=((1, 0, 0), (0, 1, 0), (0, 0, 1)), origin=(0, 0, 0))¶

lammps package¶

Submodules¶

lammps.core module¶

Module contents¶