3. Commands

This section describes how a LAMMPS input script is formatted and the input script commands used to define a LAMMPS simulation.

3.1. LAMMPS input script

LAMMPS executes by reading commands from a input script (text file), one line at a time. When the input script ends, LAMMPS exits. Each command causes LAMMPS to take some action. It may set an internal variable, read in a file, or run a simulation. Most commands have default settings, which means you only need to use the command if you wish to change the default.

In many cases, the ordering of commands in an input script is not important. However the following rules apply:

(1) LAMMPS does not read your entire input script and then perform a simulation with all the settings. Rather, the input script is read one line at a time and each command takes effect when it is read. Thus this sequence of commands:

timestep 0.5
run      100
run      100

does something different than this sequence:

run      100
timestep 0.5
run      100

In the first case, the specified timestep (0.5 fmsec) is used for two simulations of 100 timesteps each. In the 2nd case, the default timestep (1.0 fmsec) is used for the 1st 100 step simulation and a 0.5 fmsec timestep is used for the 2nd one.

(2) Some commands are only valid when they follow other commands. For example you cannot set the temperature of a group of atoms until atoms have been defined and a group command is used to define which atoms belong to the group.

(3) Sometimes command B will use values that can be set by command A. This means command A must precede command B in the input script if it is to have the desired effect. For example, the read_data command initializes the system by setting up the simulation box and assigning atoms to processors. If default values are not desired, the processors and boundary commands need to be used before read_data to tell LAMMPS how to map processors to the simulation box.

Many input script errors are detected by LAMMPS and an ERROR or WARNING message is printed. This section gives more information on what errors mean. The documentation for each command lists restrictions on how the command can be used.


3.2. Parsing rules

Each non-blank line in the input script is treated as a command. LAMMPS commands are case sensitive. Command names are lower-case, as are specified command arguments. Upper case letters may be used in file names or user-chosen ID strings.

Here is how each line in the input script is parsed by LAMMPS:

(1) If the last printable character on the line is a “&” character, the command is assumed to continue on the next line. The next line is concatenated to the previous line by removing the “&” character and line break. This allows long commands to be continued across two or more lines. See the discussion of triple quotes in (6) for how to continue a command across multiple line without using “&” characters.

(2) All characters from the first “#” character onward are treated as comment and discarded. See an exception in (6). Note that a comment after a trailing “&” character will prevent the command from continuing on the next line. Also note that for multi-line commands a single leading “#” will comment out the entire command.

(3) The line is searched repeatedly for $ characters, which indicate variables that are replaced with a text string. See an exception in (6).

If the $ is followed by curly brackets, then the variable name is the text inside the curly brackets. If no curly brackets follow the $, then the variable name is the single character immediately following the $. Thus ${myTemp} and $x refer to variable names “myTemp” and “x”.

How the variable is converted to a text string depends on what style of variable it is; see the variable doc page for details. It can be a variable that stores multiple text strings, and return one of them. The returned text string can be multiple “words” (space separated) which will then be interpreted as multiple arguments in the input command. The variable can also store a numeric formula which will be evaluated and its numeric result returned as a string.

As a special case, if the $ is followed by parenthesis, then the text inside the parenthesis is treated as an “immediate” variable and evaluated as an equal-style variable. This is a way to use numeric formulas in an input script without having to assign them to variable names. For example, these 3 input script lines:

variable X equal (xlo+xhi)/2+sqrt(v_area)
region 1 block $X 2 INF INF EDGE EDGE
variable X delete

can be replaced by

region 1 block $((xlo+xhi)/2+sqrt(v_area)) 2 INF INF EDGE EDGE

so that you do not have to define (or discard) a temporary variable X.

Additionally, the “immediate” variable expression may be followed by a colon, followed by a C-style format string, e.g. “:%f” or “:%.10g”. The format string must be appropriate for a double-precision floating-point value. The format string is used to output the result of the variable expression evaluation. If a format string is not specified a high-precision “%.20g” is used as the default.

This can be useful for formatting print output to a desired precion:

print "Final energy per atom: $(pe/atoms:%10.3f) eV/atom"

Note that neither the curly-bracket or immediate form of variables can contain nested $ characters for other variables to substitute for. Thus you cannot do this:

variable        a equal 2
variable        b2 equal 4
print           "B2 = ${b$a}"

Nor can you specify this $($x-1.0) for an immediate variable, but you could use $(v_x-1.0), since the latter is valid syntax for an equal-style variable.

See the variable command for more details of how strings are assigned to variables and evaluated, and how they can be used in input script commands.

(4) The line is broken into “words” separated by whitespace (tabs, spaces). Note that words can thus contain letters, digits, underscores, or punctuation characters.

(5) The first word is the command name. All successive words in the line are arguments.

(6) If you want text with spaces to be treated as a single argument, it can be enclosed in either single or double or triple quotes. A long single argument enclosed in single or double quotes can span multiple lines if the “&” character is used, as described above. When the lines are concatenated together (and the “&” characters and line breaks removed), the text will become a single line. If you want multiple lines of an argument to retain their line breaks, the text can be enclosed in triple quotes, in which case “&” characters are not needed. For example:

print "Volume = $v"
print 'Volume = $v'
if "${steps} > 1000" then quit
variable a string "red green blue &
                   purple orange cyan"
print """
System volume = $v
System temperature = $t
"""

In each case, the single, double, or triple quotes are removed when the single argument they enclose is stored internally.

See the dump modify format, print, if, and python commands for examples.

A “#” or “$” character that is between quotes will not be treated as a comment indicator in (2) or substituted for as a variable in (3).

Note

If the argument is itself a command that requires a quoted argument (e.g. using a print command as part of an if or run every command), then single, double, or triple quotes can be nested in the usual manner. See the doc pages for those commands for examples. Only one of level of nesting is allowed, but that should be sufficient for most use cases.


3.2.1. Input script structure

This section describes the structure of a typical LAMMPS input script. The “examples” directory in the LAMMPS distribution contains many sample input scripts; the corresponding problems are discussed in Section 7, and animated on the LAMMPS WWW Site.

A LAMMPS input script typically has 4 parts:

  1. Initialization
  2. Atom definition
  3. Settings
  4. Run a simulation

The last 2 parts can be repeated as many times as desired. I.e. run a simulation, change some settings, run some more, etc. Each of the 4 parts is now described in more detail. Remember that almost all the commands need only be used if a non-default value is desired.

  1. Initialization

Set parameters that need to be defined before atoms are created or read-in from a file.

The relevant commands are units, dimension, newton, processors, boundary, atom_style, atom_modify.

If force-field parameters appear in the files that will be read, these commands tell LAMMPS what kinds of force fields are being used: pair_style, bond_style, angle_style, dihedral_style, improper_style.

  1. Atom definition

There are 3 ways to define atoms in LAMMPS. Read them in from a data or restart file via the read_data or read_restart commands. These files can contain molecular topology information. Or create atoms on a lattice (with no molecular topology), using these commands: lattice, region, create_box, create_atoms. The entire set of atoms can be duplicated to make a larger simulation using the replicate command.

  1. Settings

Once atoms and molecular topology are defined, a variety of settings can be specified: force field coefficients, simulation parameters, output options, etc.

Force field coefficients are set by these commands (they can also be set in the read-in files): pair_coeff, bond_coeff, angle_coeff, dihedral_coeff, improper_coeff, kspace_style, dielectric, special_bonds.

Various simulation parameters are set by these commands: neighbor, neigh_modify, group, timestep, reset_timestep, run_style, min_style, min_modify.

Fixes impose a variety of boundary conditions, time integration, and diagnostic options. The fix command comes in many flavors.

Various computations can be specified for execution during a simulation using the compute, compute_modify, and variable commands.

Output options are set by the thermo, dump, and restart commands.

  1. Run a simulation

A molecular dynamics simulation is run using the run command. Energy minimization (molecular statics) is performed using the minimize command. A parallel tempering (replica-exchange) simulation can be run using the temper command.


3.3. Commands listed by category

This section lists core LAMMPS commands, grouped by category. The next section lists all commands alphabetically. The next section also includes (long) lists of style options for entries that appear in the following categories as a single command (fix, compute, pair, etc). Commands that are added by user packages are not included in the categories here, but they are in the next section.

Initialization:

newton, package, processors, suffix, units

Setup simulation box:

boundary, box, change_box, create_box, dimension, lattice, region

Setup atoms:

atom_modify, atom_style, balance, create_atoms, create_bonds, delete_atoms, delete_bonds, displace_atoms, group, mass, molecule, read_data, read_dump, read_restart, replicate, set, velocity

Force fields:

angle_coeff, angle_style, bond_coeff, bond_style, bond_write, dielectric, dihedral_coeff, dihedral_style, improper_coeff, improper_style, kspace_modify, kspace_style, pair_coeff, pair_modify, pair_style, pair_write, special_bonds

Settings:

comm_modify, comm_style, info, min_modify, min_style, neigh_modify, neighbor, partition, reset_timestep, run_style, timer, timestep

Operations within timestepping (fixes) and diagnostics (computes):

compute, compute_modify, fix, fix_modify, uncompute, unfix

Output:

dump image, dump movie, dump, dump_modify, restart, thermo, thermo_modify, thermo_style, undump, write_coeff, write_data, write_dump, write_restart

Actions:

minimize, neb, prd, rerun, run, tad, temper

Input script control:

clear, echo, if, include, jump, label, log, next, print, python, quit, shell, variable


3.3.1. Individual commands

This section lists all LAMMPS commands alphabetically, with a separate listing below of styles within certain commands. The previous section lists the same commands, grouped by category. Note that some style options for some commands are part of specific LAMMPS packages, which means they cannot be used unless the package was included when LAMMPS was built. Not all packages are included in a default LAMMPS build. These dependencies are listed as Restrictions in the command’s documentation.

angle_coeff angle_style atom_modify atom_style balance bond_coeff
bond_style bond_write boundary box change_box clear
comm_modify comm_style compute compute_modify create_atoms create_bonds
create_box delete_atoms delete_bonds dielectric dihedral_coeff dihedral_style
dimension displace_atoms dump dump image dump_modify dump movie
echo fix fix_modify group if info
improper_coeff improper_style include jump kspace_modify kspace_style
label lattice log mass minimize min_modify
min_style molecule neb neigh_modify neighbor newton
next package pair_coeff pair_modify pair_style pair_write
partition prd print processors python quit
read_data read_dump read_restart region replicate rerun
reset_ids reset_timestep restart run run_style set
shell special_bonds suffix tad temper thermo
thermo_modify thermo_style timer timestep uncompute undump
unfix units variable velocity write_coeff write_data
write_dump write_restart        

These are additional commands in USER packages, which can be used if LAMMPS is built with the appropriate package.

dump netcdf dump netcdf/mpiio dump vtk
group2ndx ndx2group temper/grem
temper/npt    

3.3.2. Fix styles

See the fix command for one-line descriptions of each style or click on the style itself for a full description. Some of the styles have accelerated versions, which can be used if LAMMPS is built with the appropriate accelerated package. This is indicated by additional letters in parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o = USER-OMP, t = OPT.

adapt addforce append/atoms atom/swap aveforce ave/atom ave/chunk ave/correlate
ave/histo ave/histo/weight ave/time balance bond/break bond/create bond/swap box/relax
cmap controller deform (k) deposit drag dt/reset efield ehex
enforce2d (k) evaporate external freeze gcmc gld gravity (o) halt
heat indent latte langevin (k) langevin/spin lineforce momentum (k) move
mscg msst neb nph (ko) nphug (o) nph/asphere (o) nph/body nph/sphere (o)
npt (kio) npt/asphere (o) npt/body npt/sphere (o) nve (kio) nve/asphere (i) nve/asphere/noforce nve/body
nve/limit nve/line nve/noforce nve/sphere (o) nve/spin nve/tri nvt (iko) nvt/asphere (o)
nvt/body nvt/sllod (io) nvt/sphere (o) oneway orient/bcc orient/fcc planeforce poems
pour precession/spin press/berendsen print property/atom (k) python/invoke python/move qeq/comb (o)
qeq/dynamic qeq/fire qeq/point qeq/shielded qeq/slater rattle reax/bonds recenter
restrain rigid (o) rigid/nph (o) rigid/npt (o) rigid/nve (o) rigid/nvt (o) rigid/small (o) rigid/small/nph
rigid/small/npt rigid/small/nve rigid/small/nvt setforce (k) shake spring spring/chunk spring/rg
spring/self srd store/force store/state temp/berendsen temp/csld temp/csvr temp/rescale
tfmc thermal/conductivity tmd ttm tune/kspace vector viscosity viscous
wall/colloid wall/gran wall/gran/region wall/harmonic wall/lj1043 wall/lj126 wall/lj93 (k) wall/piston
wall/reflect (k) wall/region wall/srd          

These are additional fix styles in USER packages, which can be used if LAMMPS is built with the appropriate package.

adapt/fep addtorque atc ave/correlate/long bond/react colvars
dpd/energy (k) drude drude/transform/direct drude/transform/reverse edpd/source eos/cv
eos/table eos/table/rx (k) filter/corotate flow/gauss gle grem
imd ipi langevin/drude langevin/eff lb/fluid lb/momentum
lb/pc lb/rigid/pc/sphere lb/viscous meso manifoldforce meso/stationary
mvv/dpd mvv/edpd mvv/tdpd nph/eff npt/eff npt/uef
nve/dot nve/dotc/langevin nve/eff nve/manifold/rattle nvk nvt/eff
nvt/manifold/rattle nvt/sllod/eff nvt/uef phonon pimd qbmsst
qeq/reax (ko) qmmm qtb reax/c/bonds (k) reax/c/species (k) rhok
rx (k) saed/vtk shardlow (k) smd smd/adjust/dt smd/integrate/tlsph
smd/integrate/ulsph smd/move/triangulated/surface smd/setvel smd/wall/surface tdpd/source temp/rescale/eff
ti/spring ttm/mod wall/ees wall/region/ees    

3.3.3. Compute styles

See the compute command for one-line descriptions of each style or click on the style itself for a full description. Some of the styles have accelerated versions, which can be used if LAMMPS is built with the appropriate accelerated package. This is indicated by additional letters in parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o = USER-OMP, t = OPT.

aggregate/atom angle angle/local angmom/chunk body/local bond
bond/local centro/atom chunk/atom cluster/atom cna/atom com
com/chunk contact/atom coord/atom damage/atom dihedral dihedral/local
dilatation/atom dipole/chunk displace/atom erotate/asphere erotate/rigid erotate/sphere
erotate/sphere/atom event/displace fragment/atom global/atom group/group gyration
gyration/chunk heat/flux hexorder/atom improper improper/local inertia/chunk
ke ke/atom ke/rigid msd msd/chunk msd/nongauss
omega/chunk orientorder/atom pair pair/local pe pe/atom
plasticity/atom pressure property/atom property/local property/chunk rdf
reduce reduce/region rigid/local slice sna/atom snad/atom
snav/atom spin stress/atom temp (k) temp/asphere temp/body
temp/chunk temp/com temp/deform temp/partial temp/profile temp/ramp
temp/region temp/sphere ti torque/chunk vacf vcm/chunk
voronoi/atom          

These are additional compute styles in USER packages, which can be used if LAMMPS is built with the appropriate package.

ackland/atom basal/atom cnp/atom dpd dpd/atom edpd/temp/atom
entropy/atom fep force/tally heat/flux/tally ke/eff ke/atom/eff
meso/e/atom meso/rho/atom meso/t/atom pe/tally pe/mol/tally pressure/uef
saed smd/contact/radius smd/damage smd/hourglass/error smd/internal/energy smd/plastic/strain
smd/plastic/strain/rate smd/rho smd/tlsph/defgrad smd/tlsph/dt smd/tlsph/num/neighs smd/tlsph/shape
smd/tlsph/strain smd/tlsph/strain/rate smd/tlsph/stress smd/triangle/mesh/vertices smd/ulsph/num/neighs smd/ulsph/strain
smd/ulsph/strain/rate smd/ulsph/stress smd/vol stress/tally tdpd/cc/atom temp/drude
temp/eff temp/deform/eff temp/region/eff temp/rotate temp/uef xrd

3.3.4. Pair_style potentials

See the pair_style command for an overview of pair potentials. Click on the style itself for a full description. Many of the styles have accelerated versions, which can be used if LAMMPS is built with the appropriate accelerated package. This is indicated by additional letters in parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o = USER-OMP, t = OPT.

none zero hybrid hybrid/overlay (k)
adp (o) airebo (oi) airebo/morse (oi) beck (go)
body bop born (go) born/coul/dsf
born/coul/dsf/cs born/coul/long (go) born/coul/long/cs born/coul/msm (o)
born/coul/wolf (go) born/coul/wolf/cs brownian (o) brownian/poly (o)
buck (giko) buck/coul/cut (giko) buck/coul/long (giko) buck/coul/long/cs
buck/coul/msm (o) buck/long/coul/long (o) colloid (go) comb (o)
comb3 coul/cut (gko) coul/debye (gko) coul/dsf (gko)
coul/long (gko) coul/long/cs coul/msm coul/streitz
coul/wolf (ko) coul/wolf/cs dpd (gio) dpd/tstat (go)
dsmc eam (gikot) eam/alloy (gikot) eam/fs (gikot)
eim (o) gauss (go) gayberne (gio) gran/hertz/history (o)
gran/hooke (o) gran/hooke/history (o) gw gw/zbl
hbond/dreiding/lj (o) hbond/dreiding/morse (o) kim lcbop
line/lj lj/charmm/coul/charmm (iko) lj/charmm/coul/charmm/implicit (ko) lj/charmm/coul/long (giko)
lj/charmm/coul/msm lj/charmmfsw/coul/charmmfsh lj/charmmfsw/coul/long lj/class2 (gko)
lj/class2/coul/cut (ko) lj/class2/coul/long (gko) lj/cubic (go) lj/cut (gikot)
lj/cut/coul/cut (gko) lj/cut/coul/debye (gko) lj/cut/coul/dsf (gko) lj/cut/coul/long (gikot)
lj/cut/coul/long/cs lj/cut/coul/msm (go) lj/cut/coul/wolf (o) lj/cut/dipole/cut (go)
lj/cut/dipole/long lj/cut/tip4p/cut (o) lj/cut/tip4p/long (ot) lj/expand (gko)
lj/gromacs (gko) lj/gromacs/coul/gromacs (ko) lj/long/coul/long (io) lj/long/dipole/long
lj/long/tip4p/long lj/smooth (o) lj/smooth/linear (o) lj96/cut (go)
lubricate (o) lubricate/poly (o) lubricateU lubricateU/poly
meam mie/cut (o) morse (gkot) nb3b/harmonic (o)
nm/cut (o) nm/cut/coul/cut (o) nm/cut/coul/long (o) peri/eps
peri/lps (o) peri/pmb (o) peri/ves polymorphic
python reax rebo (oi) resquared (go)
snap (k) soft (go) sw (giko) spin/dmi
spin/exchange spin/magelec spin/neel table (gko)
tersoff (giko) tersoff/mod (gko) tersoff/mod/c (o) tersoff/zbl (gko)
tip4p/cut (o) tip4p/long (o) tri/lj ufm (got)
vashishta (ko) vashishta/table (o) yukawa (gok) yukawa/colloid (go)
zbl (gok)      

These are additional pair styles in USER packages, which can be used if LAMMPS is built with the appropriate package.

agni (o) awpmd/cut buck/mdf coul/cut/soft (o)
coul/diel (o) coul/long/soft (o) coul/shield dpd/fdt
dpd/fdt/energy (k) eam/cd (o) edip (o) edip/multi
edpd eff/cut exp6/rx (k) extep
gauss/cut ilp/graphene/hbn kolmogorov/crespi/full kolmogorov/crespi/z
lennard/mdf list lj/charmm/coul/long/soft (o) lj/cut/coul/cut/soft (o)
lj/cut/coul/long/soft (o) lj/cut/dipole/sf (go) lj/cut/soft (o) lj/cut/thole/long (o)
lj/cut/tip4p/long/soft (o) lj/mdf lj/sdk (gko) lj/sdk/coul/long (go)
lj/sdk/coul/msm (o) mdpd mdpd/rhosum meam/c
meam/spline (o) meam/sw/spline mgpt momb
morse/smooth/linear morse/soft multi/lucy multi/lucy/rx (k)
oxdna/coaxstk oxdna/excv oxdna/hbond oxdna/stk
oxdna/xstk oxdna2/coaxstk oxdna2/dh oxdna2/excv
oxdna2/stk quip reax/c (ko) smd/hertz
smd/tlsph smd/triangulated/surface smd/ulsph smtbq
snap (k) sph/heatconduction sph/idealgas sph/lj
sph/rhosum sph/taitwater sph/taitwater/morris srp
table/rx (k) tdpd tersoff/table (o) thole
tip4p/long/soft (o)      

3.3.5. Bond_style potentials

See the bond_style command for an overview of bond potentials. Click on the style itself for a full description. Some of the styles have accelerated versions, which can be used if LAMMPS is built with the appropriate accelerated package. This is indicated by additional letters in parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o = USER-OMP, t = OPT.

none zero hybrid class2 (ko)
fene (iko) fene/expand (o) gromos (o) harmonic (ko)
morse (o) nonlinear (o) quartic (o) table (o)

These are additional bond styles in USER packages, which can be used if LAMMPS is built with the appropriate package.

harmonic/shift (o) harmonic/shift/cut (o) oxdna/fene oxdna2/fene

3.3.6. Angle_style potentials

See the angle_style command for an overview of angle potentials. Click on the style itself for a full description. Some of the styles have accelerated versions, which can be used if LAMMPS is built with the appropriate accelerated package. This is indicated by additional letters in parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o = USER-OMP, t = OPT.

none zero hybrid charmm (ko)
class2 (ko) cosine (o) cosine/delta (o) cosine/periodic (o)
cosine/squared (o) harmonic (iko) table (o)  

These are additional angle styles in USER packages, which can be used if LAMMPS is built with the appropriate package.

cosine/shift (o) cosine/shift/exp (o) dipole (o) fourier (o)
fourier/simple (o) quartic (o) sdk  

3.3.7. Dihedral_style potentials

See the dihedral_style command for an overview of dihedral potentials. Click on the style itself for a full description. Some of the styles have accelerated versions, which can be used if LAMMPS is built with the appropriate accelerated package. This is indicated by additional letters in parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o = USER-OMP, t = OPT.

none zero hybrid charmm (iko)
charmmfsw class2 (ko) harmonic (io) helix (o)
multi/harmonic (o) opls (iko)    

These are additional dihedral styles in USER packages, which can be used if LAMMPS is built with the appropriate package.

cosine/shift/exp (o) fourier (io) nharmonic (o) quadratic (o)
spherical (o) table (o) table/cut  

3.3.8. Improper_style potentials

See the improper_style command for an overview of improper potentials. Click on the style itself for a full description. Some of the styles have accelerated versions, which can be used if LAMMPS is built with the appropriate accelerated package. This is indicated by additional letters in parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o = USER-OMP, t = OPT.

none zero hybrid class2 (ko)
cvff (io) harmonic (iko) umbrella (o)  

These are additional improper styles in USER packages, which can be used if LAMMPS is built with the appropriate package.

cossq (o) distance fourier (o) ring (o)

3.3.9. Kspace solvers

See the kspace_style command for an overview of Kspace solvers. Click on the style itself for a full description. Some of the styles have accelerated versions, which can be used if LAMMPS is built with the appropriate accelerated package. This is indicated by additional letters in parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o = USER-OMP, t = OPT.

ewald (o) ewald/disp msm (o) msm/cg (o)
pppm (gok) pppm/cg (o) pppm/disp (i) pppm/disp/tip4p
pppm/stagger pppm/tip4p (o)