Building a LAMMPS input file: a tutorial

 For a LAMMPS beginner, creating their first input file could be rather overwhelming. LAMMPS provides a vast array of commands with diverse applications, and it might be difficult to use them without any guidance. Nevertheless, the LAMMPS input file has some general structural requirements that are virtually unchanging for the majority of uses. To build a LAMMPS input file, the first step should be creating a plain text file. It is usually presented in the form in.filename. This document only includes some very common examples of LAMMPS commands. For a full command list, see manual.

Common structure:

1.     Main information about the system

·      Units. Available unit styles are real, metal, si, csg, electron, and micro. For more information about the units command, see manual.

Correct format:

units [unit style]

units real

·      Dimensions. By default, LAMMPS runs 3d simulations, but 2d simulations are also supported. 

For more information about the dimensions command, see manual.

Correct format:

dimension [number of dimensions]

dimension 3

·      Processors. Determines the number of processors used for simulating each dimension. This could be automated by entering “*” as a value for each variable. In that case, LAMMPS will assign the processors automatically. Certain other arguments could also be added. 

For more information about the processors command, see manual.

Correct format:

processors [Px] [Py] [Pz] ([keyword] [arguments] …)

processors * * *

·      Boundary. The boundary command requires information about the type of boundary in each direction of the simulation box. Each variable could be either p (a periodic boundary), f (non-periodic and fixed), s(non-periodic and shrink-wrapped), or m (non-periodic and shrink-wrapped with a minimum value). 

For more information about the boundary command, see manual.

Correct format:

boundary [x boundary] [y boundary] [z boundary]

boundary p p p

·      Atom style. Atom styles determine the type of all atoms in the simulation box. Some common styles are atom (intended for a system that does not contain molecules and its atoms do not possess charges), charge (intended for a system that does not contain molecules but contains charged atoms), molecule(intended for a system that contains molecules but does not have charged atoms), and full (intended for a system that contains both molecules and charged atoms). Some optional arguments could also be added.

For more information about the atom style command, see manual.

Correct format:

atom_style [atom style] ([arguments] …)

atom_style full

·      Pair style. Pair styles determine the type of force field interactions between non-bonded atoms. Most pair styles also require certain arguments, which may differ depending on the chosen style. One common pair style is lj/charmm/coul/long. For more information about the lj/charmm/coul/long pair style, see manual. 

For a full list of available pair styles, see manual.

Correct format:

pair_style [pair style] ([arguments] …)

pair_style lj/charmm/coul/long 5.0 7.5

·      Bond style. Bond styles determine the type of force field interactions between bonded atoms. This command is only required for those atom styles that allow bonding between atoms. Some bond styles may require certain arguments, which could differ depending on the chosen style.  One example of common bond styles is harmonic. For more information about the harmonic bond style, see manual.

For a full list of available bond styles, see manual.

Correct format:

bond_style [bond style] ([arguments] …)

bond_style harmonic

·      Angle style. Angle styles determine the nature of angles between bonds. This command is only used for those atom styles that allow bonding between atoms. Some angle styles may require certain arguments, which could differ depending on the chosen style.  One example of common angle styles is charmm. For more information about the charmm angle style, see manual.

For a full list of available angle styles, see manual.

Correct format:

angle_style [angle style] ([arguments] …)

angle_style charmm

·      Dihedral style. Dihedral styles determine the nature of dihedral bond arrangements. This command is only used for those atom styles that allow bonding between atoms. Some dihedral styles may require certain arguments, which could differ depending on the chosen style.  One example of common dihedral styles is charmm. For more information about the charmm dihedral style, see manual.

For a full list of available dihedral styles, see manual.

Correct format:

dihedral_style [dihedral style] ([arguments] …)

dihedral_style charmm

·      Improper style. Improper styles determine the nature of improper dihedral arrangements. This command is only used for those atom styles that allow bonding between atoms. Some improper styles may require certain arguments, which could differ depending on the chosen style.  One example of common improper styles is harmonic. For more information about the harmonic improper style, see manual.

For a full list of available improper styles, see manual.

 

Correct format:

improper_style [improper style] ([arguments] …)

improper_style harmonic

·      Kspace style. Kspace styles determine the computation type and relative error in energy values used for long-range pair interactions. The most appropriate kspace style depends on the type of chosen pair style. As an example, if the chosen pair style is lj/charmm/coul/long, the suggested kspace styles would ewald or pppm.  

For more information about kspace styles, see manual.

Correct format:

kspace_style [kspace style] [accuracy value]

kspace_style pppm 0.0001

·      Read data. The read data command directs LAMMPS to read a data file that provides information about the contents of the initial simulation box. It is also possible to modify how the data is read by providing certain arguments. Using this command requires the presence of the specified data file in the same folder. 

For more information about the read data command, see manual.

Correct format:

read_data [file name] ([keyword] [arguments] …)

read_data data.filename

·      Lattice. This command allows generating a lattice that determines some dedicated points in space used by other commands. Lattice styles include none (defines a lattice spacing but does not define a unit cell and basis set. Cannot be used alongside create atoms command), sc (defines a simple cubic lattice), bcc(defines a body-centred cubic lattice), fcc (defines a face-centred cubic lattice), hcp (defines a hexagonal close-packed lattice), diamond (defines a diamond type face-centred cubic lattice with 8 basis atoms), sq (defines a 2-d square lattice with a single basis atom), sq2 (defines a 2-d square lattice with two basis atoms), hex (defines a 2-d hexagonal lattice), and custom (allows to create a customized lattice type). The scale argument determines the size of the unit cell. Certain lattice styles also allow some optional keywords. 

For more information about the lattice command, see manual.

Correct format:

lattice [lattice style] [scale] ([keyword] [arguments] …)

lattice fcc 2.57

·      Create atoms. This command generates atoms in the simulation box. It has the most prominent purpose if no data file has been provided. The create atoms command is formulated with the specified atom type (integers 1 through N), styles, their arguments, keywords, and their arguments. Styles include box (the entire simulation box is filled with particles), region (a specific geometric volume is filled with particles), single (a single particle is generated with specific coordinates), and random (particles are generated with random coordinates). Arguments may vary depending on the selected style. For instance, random style requires three arguments: number of particles to create, a random seed (positive integer), and a region ID (NULL for the entire box). Keywords include mol (used for molecules), basis (used when atoms and not molecules are created), ratio (could be used with the box and region styles and limits the number of generated particles to a certain fraction of the initial amount), subset (works similar to the fraction command, but instead of generating a fraction, it generates a subset of N atoms), remap (only applies to the single style and it regulates the atom’s ability to generate outside of the simulation box), var (provides a criterion for generating a single atom), set (provides a criterion for generating a single atom and could be used with var), rotate (allows the user to specify the orientation at which molecules are inserted), and units (determines the meaning of distance units for a single style particle). Multiple keywords could be used at once.

For more information about the create atoms command, see manual.

Correct format:

create_atoms [type] [style] [arguments] … ([keyword] [value] …)

create_atoms 1 random 30 34 NULL

·      Create bonds. This command is used to create bonds between atoms, and it is useful when the data file is not provided. Create bonds styles include many (creates bonds between groups of atoms that are at a specified distance from one another), single/bond (creates a bond between two specified atoms), single/angle (creates bonds and an angle between three specified atoms), single/dihedral (creates bonds and a dihedral between four specified atoms), and single/improper (creates bonds and an improper between four specified atoms). Arguments vary between different create bonds styles. For instance, the single/bond style requires the bond type ID, atom ID1, and atom ID2. An optional keyword special could also be added to any situation. Its value could be either yes, or no. 

For more information about the create bonds command, see manual.

Correct format:

create_bonds [style] [arguments] … ([keyword] [value])

create_bonds single/bond 1 45 67

·      Mass.  This command allows to determine the mass of an atom type and it is useful in situations where a data file is not provided.

For more information about the mass command, see manual.

Correct format:

mass [atom type] [atom mass]

mass 2 12.01

·      Neighbor. The neighbor command allows LAMMPS to increase the efficiency of the simulation while trading in some accuracy. With this command, interactions outside a specified additional cut-off are ignored and fewer calculations have to be computed as a result. Neighbor styles include bin (most common choice), nsq (faster for some unsolvated molecules in a non-periodic box), or multi (useful for systems with a wide range of cut-off distances). 

For more information about the neighbor command, see manual.

Correct format:

neighbor [extra distance beyond force field cutoff] [style]

neighbor 1.0 bin

·      Timestep. This command sets the length of each timestep in time units.

For more information about the timestep command, see manual.

Correct format:

timestep [timestep length]

timestep 2.0

·      Thermo style. This command allows the user to set the style and content of thermodynamic quantities that are calculated and printed on the screen. Thermo styles include one (prints a single-line listing of thermodynamic quantities), multi (prints the thermodynamic quantities in multiple lines), and custom(allows custom arguments to be added).

For more information about the thermo style command, see manual. Correct format:

thermo_style [thermo style] ([arguments] …)

thermo_style multi

·      Min style. Specifies a particular algorithm that will be used when performing a minimization. Min styles include cg (applies a version of the conjugate gradient algorithm), hftn (applies a Hessian-free truncated Newton algorithm), sd (applies the steepest descent algorithm), quickmin (applies damped dynamics, where the damping parameter depends on the projection of the velocity vector), fire (similar to quickmin, but a variable timestep is added and the projection operation is altered to maintain velocity vector components parallel to the current force vector), fire/old (the original version of fire in LAMMPS), spin (applies damped spin dynamics with an adaptive timestep), spin/cg (a combination of cg and orthogonal spin optimization algorithms), and spin/lbfgs (a combination of a limited-memory Broyden-Fletcher-Goldfarb-Shanno approach and an orthogonal spin optimization).

For more information about the min style command, see manual.

Correct format:

min_style [min style]

min_style cg

·      Group. This command allows to define a group of atoms or change some group qualities. Group styles include delete (removes the group and unassigns included atoms), clear (unassigns all atoms belonging to that particular group), empty (creates an empty group), region (assigns atoms that reside in a particular region), type (assigns atoms that belong to a particular atom type), id (assigns atoms that have certain IDs), molecule (assigns atoms that are a part of a certain molecule), variable (evaluates a variable that determines which atoms would be included in the group), include (adds an extra molecule to the group), subtract (from a series of two or more specified groups, this style groups the atoms that belong to the first group but not the other groups), union (groups together all the atoms that belong to two or more specified groups), intersect (groups together the atoms that belong to two or more specified groups), dynamic (periodically reassigns atoms to the group as the simulation runs), and static (removes the dynamic flag). Arguments vary between different group styles. For instance, type, id and molecule styles require arguments that specify the desired atom types, atom IDs or molecule IDs. Logical arguments and recurrent sequences are also allowed.

For more information about the group command, see manual.

Correct format:

group [group ID] [group style] [arguments]

group 1 molecule 3

 

·      Region. This command creates a geometric region of a specified shape. Region styles include delete(deletes a region), block (creates a block-shaped region), cone (creates a cone-shaped region), cylinder(creates a cylinder-shaped region), plane (creates a plane), prism (creates a prism-shaped region), sphere (creates a sphere-shaped region), union (adds up the volumes of two or more regions), and intersect (specifies a region at an intersection between two or more regions). Each style requires different arguments. For example, the block style requires xlo, ylo, zlo, xhi, yhi, and zhi. Certain keywords could also be added. These keywords include side (specifies if the region is inside or outside the selected geometry), units (determines if the region is specified using lattice or box units), move(commands the region to change its position over time), rotate (commands the region to rotate over time), and open (opens a certain side of the region).

For more information about the region command, see manual.

Correct format:

region [ID] [region style] [arguments] ([keyword] [arguments] …)

region 1 block 0.1 0.1 0.1 0.5 0.5 0.5

2.     Action-based commands

·      Neigh modify. This command allows the user to provide additional features to the way neighbour lists are made. It requires a certain keyword for modified attributes and certain numeric values that specify their action. Keywords include delay (commands the system to delay building until a certain amount of timesteps passes since the last build), every (builds neighbour lists every certain number of timesteps), check (determines whether the build is executed based on how much an atom has moved), once (determines whether the neighbour list is built only once), cluster (checks if atoms belonging to bonds, angles, dihedrals, and impropers are within a reasonable amount of distance from one another), include (limits building the neighbour lists to a particular group of atoms), exclude (excludes a particular group of atoms from the neighbour lists), page (stores indices of neighbouring atoms in pages. Useful for large simulations), one (only a certain number of neighbours is allowed for a single atom. Useful in large simulations), and binsize (provides the ability to determine the size of bins used in neighbour list construction).

For more information about the neigh modify command, see manual. Correct format:

neigh_modify [keyword] [values] …

neigh_modify delay 5

·      Thermo. This command tells LAMMPS to output thermodynamic quantities every N number of timesteps.

For more information about the thermo command, see manual.

Correct format:

thermo [N]

thermo 50

·      Thermo modify. Modifies the way thermodynamic quantities are computed and shown. Keywords include lost (determines what LAMMPS does with lost atoms outside the box boundary), lost/bond (determines what LAMMPS does if a bonded atom is not found in neighbour lists), norm (determines if thermodynamic quantities are normalised by the number of atoms), flush (determines whether a flush operation is carried out after thermodynamic quantities are written to a log file), line (determines if thermodynamic quantities will be written in a single line, or multiple lines), format (could change the way numeric values are formatted), temp (determines how temperature is calculated), and press(determines how pressure is calculated). Specified IDs must be previously identified timesteps. Multiple keywords could be included.

For more information about the thermo modify command, see manual.

Correct format:

thermo_modify [keyword] [arguments] … 

thermo_modify lost warn

·      Minimize. This command allows LAMMPS to minimize the system energy and force parameters by performing small atom movements in random directions. It requires to specify energy and force tolerance boundaries, a maximum number of iterations, and the maximum number of energy and force evaluations. The command stops running when either the tolerance numbers are reached, or when the iteration and evaluation numbers are exceeded.

For more information about the minimize command, see manual.

Correct format:

minimize [E tolerance] [F tolerance] [N of iterations] [N of evaluation]

minimize 1.0e-7 1.0e-7 10000 10000

·      Set. This command could be used to specify properties of some atoms or atom groups. Set styles include atom (selects a single atom), type (selects an atom type), mol (selects the atoms of a single molecule), group (selects the atoms in an atom group), and region (selects all atoms in a geometric region). ID could be the atom ID, type ID, molecule ID, group ID, or region ID, depending on the selected style. The function and application of keywords highly vary. For instance, diameter sets the diameter of atoms, while spin applies a magnetic spin vector.

For more information about the set command, see manual.

Correct format:

set [set style] [ID] [keyword] [arguments] …

set type 1 diameter 1.06

·      Velocity. Allows to set or change the velocity of a group of atoms. Velocity styles include create(defines new velocities based on the specified temperature and a random seed), set (defines new velocities as specified velocity values for all atoms), scale (computes the current temperature and then rescales to a specified temperature range), ramp (sets uniformly distributed velocities in a certain range and applied to a certain dimension), and zero (adjusts the velocities of a group of atoms in a way that the net linear or angular momentum is equal to zero). Each style has different arguments. For instance, the create style requires a temperature value and a random positive seed. Certain keywords could also be added. Keywords include dist (determines if the distribution is uniform or gaussian), sum(determines if new velocities are added to old ones, or if the values are replaced), mom (determines whether the linear momentum is zeroed), rot (determines whether the angular momentum is zeroed), temp (changes the way temperature is calculated, Used with create and scale styles), bias (determines whether a calculated velocity bias is subtracted from the velocities before create and scale operations are performed), loop (created velocities are looped in various ways), and units (determines whether box or lattice units are used).

For more information about the velocity command, see manual.

Correct format:

velocity [gr ID] [velocity style] [arguments] ([keyword] [values] …)

velocity 1 create 298 54

·      Fix. This command applies an operation that is carried out throughout a range of timesteps or during minimization. There is a large amount of different fix styles, but some common examples include nve(performs integration with constant volume and energy to update atom velocity and position), nvt (performs integration with constant volume and temperature to update atom velocity and position), npt (performs integration with constant pressure and temperature to update atom velocity and position), nvk (performs integration using a Gaussian thermostat with constant volume and kinetic energy to update atom velocity and position), spring (applies harmonic spring forces to a group of atoms), bond/break (breaks bonds), bond/create (creates bonds), drag (drags atoms to a certain coordinate), move (moves atoms in a specific way), shake (carries out a SHAKE algorithm that applies certain constraints and resets bond lengths and angles to their equilibrium values), rattle (similar to a SHAKE algorithm, but it constrains coordinates and applies velocity constraints that could be solved analytically), and heat (adds or subtracts kinetic energy over time to a group of atoms while conserving their total momentum). Arguments vary between different fix styles. For example, the nvt and npt styles require certain keywords (e.g. temp) and certain values (e.g. initial external temperature, final external temperature, and time). For more information about nvt and npt styles, see manual. Fix shake and fix rattle are common commands for molecular simulations. For more information about shake and rattle styles, see manual.

For more information about the fix command, see manual.

Correct format:

fix [fix ID] [group ID] [group style] [arguments]

fix 4 all nvt temp 298.0 298.0 10

·      Unfix. Deletes a previously defined fix.

For more information about the unfix command, see manual.

Correct format:

unfix [fix ID]

unfix 4

·      Compute. Performs a certain computation on a group of atoms. Some common compute styles include bond (calculates the energy of each bond), temp (calculates the temperature of a group of atoms), press (calculates the pressure and the pressure tensor), and ke (calculates the kinetic energy).

For more information about the compute command, see manual.

Correct format:

compute [compute ID] [group ID] [compute style] [arguments] …

compute 2 all press

·      Uncompute. Deletes a previously defined compute.

For more information about the uncompute command, see manual.

Correct format:

uncompute [compute ID]

uncompute 3

·      Run. This command tells LAMMPS to run or continue current dynamics for a certain number of timesteps (N). Certain keywords could also be added. Available keywords are upto (runs up to the N-th timestep), start (sets a timestep that marks the start of a run), stop (sets a timestep that marks the end of a run. When used together with start, could be useful for taking multiple measurements when running a certain action), pre (regulates the execution of pre-run actions), post (regulates the execution of post-run actions), and every (breaks a run into a series of shorter runs and computes certain specified actions).

For more information about the run command, see manual.

Correct format:

run [N] ([keyword] [values] …)

run 50000 every 20 NULL

·      Dump. Outputs a snapshot of certain atom quantities to one or more files every N timesteps. Dump styles include atom (writes a dump with atom coordinates, IDs and atom types), atom/gz (atom style dump written in a .gz format), atom/mpiio (atom style dump written with an MPI-IO library), cfg(writes a CFG dump file), cfg/gz (cfg style dump written in a .gz format), cfg/mpiio (cfg style dump written with an MPI-IO library), custom (allows to list certain specified atom attributes in the dump file), custom/gz (custom style dump written in a .gz format), custom/mpiio (custom style dump written with an MPI-IO library), custom/adios (custom style dump written in an ADIOS based BP file), dcd (writes a DCD file that contains standard atomic trajectories for CHARMM, NAMD and XPlor), h5md (writes a HDF5 based H5MD file), image (dumps an image of the simulation box at a certain timestep), local (dumps local output generated by each processor based on how many atoms and other entities it owns), local/gz (local style dump written in a .gz format), molfile (using a molfile plugin, the system dumps a file containing atom coordinates and certain specified properties), movie(dumps a video of the simulation box throughout a certain timeframe), netcdf (dumps a snapshot of atom coordinates in an Amber-style NetCDF format), netcdf/mpiio (netcdf style dump written with an MPI-IO library), vtk (dumps atom quantities in a certain format that is readable by a VTK toolkit), xtc(writes an XTC file that contains standard atomic trajectories for GROMACS), xyz (writes an XYZ file, a simple text-based file containing atom coordinates and types), xyz/gz (xyz style dump written in a .gz format), and xyz/mpiio (xyz style dump written with an MPI-IO library). After specifying the dump style, the frequency of dumps must be set. N represents how many timesteps must pass until the next snapshot is taken. The file is usually written in the form dump.filename. Some dump styles also require certain unique arguments.

For more information about the dump command, see manual.

Correct format:

dump [dump ID] [group ID] [dump style] [N] [file name] [arguments]

dump 1 all atom 10 dump.filename

 

·      Undump. Closes a previously defined dump.

For more information about the undump command, see manual.

Correct format:

undump [dump ID]

undump 2

·      Write data. The write data command directs LAMMPS to write a data file that reflects the final state of the simulation box. It is also possible to save the force field information by providing certain arguments. For more information about the write data command, see manual.

Correct format:

write_data [file name] ([keyword] [arguments] …)

write_data data.filename

·      Write restart. The write restart command directs LAMMPS to write a restart file. It is also possible to write a varying number of restart files for each processor by adding some arguments. For more information about the write restart command, see manual.

Correct format:

write_restart [file name] ([keyword] [arguments] …)

write_restart restart.filename

Disclaimer: if certain coefficients are not provided in the data file, they must be added with the appropriate coefficient commands. For instance, pair coefficients must be added to the input file via the pair_coeff command (see manual).

        Author: Lukas Supragonas