LAMMPS Calculators¶

LAMMPS (Large-scale Atomic/Molecular Massively Parallel Simulator) is a classical molecular dynamics code.

There are two calculators that interface to the LAMMPS molecular dynamics code that can be used to solve an atoms model for energy, atom forces and cell stresses. They are:

1. ase.calculators.LAMMPSrun which interfaces to LAMMPS via writing a controlling input file that is then run automatically through LAMMPS and the results read back in. These results are currently limited to total energy, atomic forces and cell stress.

2. LAMMPSlib which uses the python interface that comes with LAMMPS, loads the LAMMPS program as a python library. The LAMMPSlib calculator then creates a ‘.lmp’ object which is a running LAMMPS subroutine, so further commands can be sent to this object and executed until it is explicitly closed. Any additional variables calculated by LAMMPS can also be extracted. Note however, any mistakes in the code sent to the LAMMPS routine will cause python to terminate. Further information on the python interface of LAMMPS can be found at lammpspy_link. Note that it can be very beneficial to compile lammps with C++ exceptions. Otherwise there will be no error messages upon crashes.

It should not matter which code you use, but if you want access to more of LAMMPS internal variables or to perform a more complicated simulation then use LAMMPSlib. It is important to know which code you are using because when you make an error in the LAMMPS code, debugging the is difficult and different for both calculators.

Both of these interfaces are still experimental code and any problems should be reported to the ASE developers mailing list.

class ase.calculators.lammpsrun.LAMMPS(label='lammps', **kwargs)[source]¶

The LAMMPS calculators object

files: list
List of files typically containing relevant potentials for the calculation

parameters: dict
Dictionary of settings to be passed into the input file for calculation.

specorder: list
Within LAAMPS, atoms are identified by an integer value starting from 1. This variable allows the user to define the order of the indices assigned to the atoms in the calculation, with the default if not given being alphabetical

keep_tmp_files: bool
Retain any temporary files created. Mostly useful for debugging.

tmp_dir: str
path/dirname (default None -> create automatically). Explicitly control where the calculator object should create its files. Using this option implies ‘keep_tmp_files’

no_data_file: bool
Controls whether an explicit data file will be used for feeding atom coordinates into lammps. Enable it to lessen the pressure on the (tmp) file system. THIS OPTION MIGHT BE UNRELIABLE FOR CERTAIN CORNER CASES (however, if it fails, you will notice…).

keep_alive: bool
When using LAMMPS as a spawned subprocess, keep the subprocess alive (but idling when unused) along with the calculator object.

always_triclinic: bool
Force use of a triclinic cell in LAMMPS, even if the cell is a perfect parallelepiped.

Example

Provided that the respective potential file is in the working directory, one can simply run (note that LAMMPS needs to be compiled to work with EAM potentials)

from ase import Atom, Atoms
from ase.build import bulk
from ase.calculators.lammpsrun import LAMMPS

parameters = {'pair_style': 'eam/alloy',
              'pair_coeff': ['* * NiAlH_jea.eam.alloy H Ni']}

files = ['NiAlH_jea.eam.alloy']

Ni = bulk('Ni', cubic=True)
H = Atom('H', position=Ni.cell.diagonal()/2)
NiH = Ni + H

lammps = LAMMPS(parameters=parameters, files=files)

NiH.calc = lammps
print("Energy ", NiH.get_potential_energy())

(Remember you also need to set the environment variable $ASE_LAMMPSRUN_COMMAND)

Basic calculator implementation.

restart: str: Prefix for restart file. May contain a directory. Default is None: don’t restart.
ignore_bad_restart_file: bool: Deprecated, please do not use. Passing more than one positional argument to Calculator() is deprecated and will stop working in the future. Ignore broken or missing restart file. By default, it is an error if the restart file is missing or broken.
directory: str or PurePath: Working directory in which to read and write files and perform calculations.
label: str: Name used for all files. Not supported by all calculators. May contain a directory, but please use the directory parameter for that instead.
atoms: Atoms object: Optional Atoms object to which the calculator will be attached. When restarting, atoms will get its positions and unit-cell updated from file.

class ase.calculators.lammpslib.LAMMPSlib(*args, **kwargs)[source]¶

Introduction

LAMMPSlib is an interface and calculator for LAMMPS. LAMMPSlib uses the python interface that comes with LAMMPS to solve an atoms model for energy, atom forces and cell stress. This calculator creates a ‘.lmp’ object which is a running lammps program, so further commands can be sent to this object executed until it is explicitly closed. Any additional variables calculated by lammps can also be extracted. This is still experimental code.

Arguments

Keyword	Description
`lmpcmds`	list of strings of LAMMPS commands. You need to supply enough to define the potential to be used e.g. [“pair_style eam/alloy”, “pair_coeff * * potentials/NiAlH_jea.eam.alloy Ni Al”]
`atom_types`	dictionary of `atomic_symbol :lammps_atom_type` pairs, e.g. `{'Cu':1}` to bind copper to lammps atom type 1. If <None>, autocreated by assigning lammps atom types in order that they appear in the first used atoms object.
`atom_type_masses`	dictionary of `atomic_symbol :mass` pairs, e.g. `{'Cu':63.546}` to optionally assign masses that override default ase.data.atomic_masses. Note that since unit conversion is done automatically in this module, these quantities must be given in the standard ase mass units (g/mol)
`log_file`	string path to the desired LAMMPS log file
`lammps_header`	string to use for lammps setup. Default is to use metal units and simple atom simulation. lammps_header=[‘units metal’, ‘atom_style atomic’, ‘atom_modify map array sort 0 0’])
`amendments`	extra list of strings of LAMMPS commands to be run post post initialization. (Use: Initialization amendments) e.g. [“mass 1 58.6934”]
`keep_alive`	Boolean whether to keep the lammps routine alive for more commands

Requirements

To run this calculator you must have LAMMPS installed and compiled to enable the python interface. See the LAMMPS manual.

If the following code runs then lammps is installed correctly.

>>> from lammps import lammps
>>> lmp = lammps()

The version of LAMMPS is also important. LAMMPSlib is suitable for versions after approximately 2011. Prior to this the python interface is slightly different from that used by LAMMPSlib. It is not difficult to change to the earlier format.

LAMMPS and LAMMPSlib

The LAMMPS calculator is another calculator that uses LAMMPS (the program) to calculate the energy by generating input files and running a separate LAMMPS job to perform the analysis. The output data is then read back into python. LAMMPSlib makes direct use of the LAMMPS (the program) python interface. As well as directly running any LAMMPS command line it allows the values of any of LAMMPS variables to be extracted and returned to python.

Example

Provided that the respective potential file is in the working directory, one can simply run (note that LAMMPS needs to be compiled to work with EAM potentials)

from ase import Atom, Atoms
from ase.build import bulk
from ase.calculators.lammpslib import LAMMPSlib

cmds = ["pair_style eam/alloy",
        "pair_coeff * * NiAlH_jea.eam.alloy Ni H"]

Ni = bulk('Ni', cubic=True)
H = Atom('H', position=Ni.cell.diagonal()/2)
NiH = Ni + H

lammps = LAMMPSlib(lmpcmds=cmds, log_file='test.log')

NiH.calc = lammps
print("Energy ", NiH.get_potential_energy())

Implementation

LAMMPS provides a set of python functions to allow execution of the underlying C++ LAMMPS code. The functions used by the LAMMPSlib interface are:

from lammps import lammps

lmp = lammps(cmd_args) # initiate LAMMPS object with command line args

lmp.scatter_atoms('x',1,3,positions) # atom coords to LAMMPS C array
lmp.command(cmd) # executes a one line cmd string
lmp.extract_variable(...) # extracts a per atom variable
lmp.extract_global(...) # extracts a global variable
lmp.close() # close the lammps object

For a single Ni atom model the following lammps file commands would be run by invoking the get_potential_energy() method:

units metal
atom_style atomic
atom_modify map array sort 0 0

region cell prism 0 xhi 0 yhi 0 zhi xy xz yz units box
create_box 1 cell
create_atoms 1 single 0 0 0 units box
mass * 1.0

## user lmpcmds get executed here
pair_style eam/alloy
pair_coeff * * NiAlH_jea.eam.alloy Ni
## end of user lmmpcmds

run 0

where xhi, yhi and zhi are the lattice vector lengths and xy, xz and yz are the tilt of the lattice vectors, all to be edited.

Notes

Units: The default lammps_header sets the units to Angstrom and eV and for compatibility with ASE Stress is in GPa.
The global energy is currently extracted from LAMMPS using extract_variable since lammps.lammps currently extract_global only accepts the following [‘dt’, ‘boxxlo’, ‘boxxhi’, ‘boxylo’, ‘boxyhi’, ‘boxzlo’, ‘boxzhi’, ‘natoms’, ‘nlocal’].
If an error occurs while lammps is in control it will crash Python. Check the output of the log file to find the lammps error.
If the are commands directly sent to the LAMMPS object this may change the energy value of the model. However the calculator will not know of it and still return the original energy value.

Basic calculator implementation.

restart: str: Prefix for restart file. May contain a directory. Default is None: don’t restart.
ignore_bad_restart_file: bool: Deprecated, please do not use. Passing more than one positional argument to Calculator() is deprecated and will stop working in the future. Ignore broken or missing restart file. By default, it is an error if the restart file is missing or broken.
directory: str or PurePath: Working directory in which to read and write files and perform calculations.
label: str: Name used for all files. Not supported by all calculators. May contain a directory, but please use the directory parameter for that instead.
atoms: Atoms object: Optional Atoms object to which the calculator will be attached. When restarting, atoms will get its positions and unit-cell updated from file.