Tutorial: working with LAMMPS files

This tutorial explains how to use Atomsk to produce data files for LAMMPS, and read LAMMPS output files. It is recommended to be already familiar with LAMMPS to proceed with this tutorial.

▶ For more information, refer to the corresponding documentation page.

LAMMPS is a code performing simulations on classical particles -including, but not restricted to, molecular dynamics. A LAMMPS calculation is controlled by a script file, often called "in.something" (see input scripts in the LAMMPS documentation). This script file contains informations about the units, the interatomic potential, the type of calculation (minimization, molecular dynamics...), and it can also contain commands to design and construct an atomic system. If you construct your system using the LAMMPS built-in commands, then you do not need another software (like Atomsk).

Alternatively, it is also possible to tell LAMMPS to read atom positions from an external data file, thanks to the "read_data" command. In this case, you can design your system with a tool like Atomsk, and write atom positions into a data file that is suitable for LAMMPS. This tutorial explains how to proceed to manipulate such files.

ⓘ Atomsk only deals with the cell geometry and atom positions. It will not provide any other simulation parameters like interatomic potential, parameters for relaxation or molecular dynamics, and so on. You will have to set up those parameters by yourself.

Moreover, Atomsk supports only atoms (corresponding to atom_style "atomic" and "charge"), but does not support molecules, bonds, dihedral, nor any other information.

1. Generate a data file for LAMMPS

Let us create a unit cell of aluminium, and write it in the format of a LAMMPS data file:

atomsk --create fcc 4.046 Al lammps

With this command, Atomsk will generate a LAMMPS data file named "Al.lmp", that looks like the following:

The three lines "xlo xhi", "ylo yhi" and "zlo zhi" define the box, and the section "Atoms" contains the index, type, and Cartesian coordinate of each atom. Here all atoms are aluminium, therefore they are all of type 1 (second column). Note that there is no standard extension for LAMMPS data files. Atomsk uses the extension ".lmp", but that is not very important -they are just text files anyway.

Such a file can be read from a LAMMPS input script by using the command "read_data":

2. Convert an existing file for LAMMPS

If you already have an existing atomic system, it is easy to convert it for LAMMPS. For instance, consider that we have an atomic system in the file "mysystem.cfg" (i.e. in Atomeye CFG format). Run Atomsk to convert it for LAMMPS:

atomsk mysystem.cfg lammps

Atomsk will produce a file named "mysystem.lmp". Again, this file can be used by LAMMPS with the command "read_data mysystem.lmp".

3. Make the box suitable for LAMMPS

For reasons of computational efficiency, LAMMPS has two major requirements concerning the simulation box, that you should be aware of. They are detailed in this page of the LAMMPS manual. The first requirement, is that the first box vector is aligned with the Cartesian X direction, and that the second vector is contained in the XY plane. The second one, is that the box "skewness" should not be too large, i.e. the box should not be too distorted, and the box angles should be neither too acute nor too obtuse. If your simulation box fails to meet those requirements, then LAMMPS will most probably terminate with an error.

To begin with, let us create a unit cell of aluminium as before, and rotate it by 45° around Y, and then by 45° around X:

atomsk --create fcc 4.046 Al -rotate 45° Y -rotate 45° X Al.xsf

It is important to understand that this system is still a unit cell of aluminium, that was just rotated by arbitrary vectors. If you open the file "Al.xsf", you will notice that the cell vectors have components along both the X, Y and Z directions:

Now, this is the problem: LAMMPS does not accept such vectors. In fact, it is not possible to write such vectors in a LAMMPS data file. So, if you attempt to write such an atomic system in a LAMMPS data file, Atomsk will display a warning:

atomsk Al.xsf lammps

/!\ WARNING: supercell does not form a lower-triangular matrix, which is
required by LAMMPS. Do you want to re-align the system? (y/n)

If you choose no, then some components of the box vectors will be missing in the LAMMPS data file, and the simulation will most likely go wrong. If you choose yes, then Atomsk will rotate the system to comply to LAMMPS requirements, i.e. that the first box vector lies along the Cartesian X axis, and the second box vector is inside the XY plane.

Alternatively, if you wish to always make sure that your simulation box is suitably aligned for LAMMPS, you may use the option "-alignx":

atomsk Al.xsf -alignx lammps

Now, the second restriction imposed by LAMMPS is that the box should not be too skewed, or too much sheared. Let us consider a supercell of dimensions 4x4x40 ų, i.e. the original box vectors are as follows:

H1 = [4 0 0]
H2 = [0 4 0]
H3 = [0 0 40]

Now, let us shear this box, by tilting the third vector a little (i.e. modifying the yz component):

H1 = [4 0 0]
H2 = [0 4 0]
H3 = [0 1 40]

This new box is still acceptable for a LAMMPS simulation. But now, if we tilt it further:

H1 = [4 0 0]
H2 = [0 4 0]
H3 = [0 3 40]

Such a box is not acceptable, and LAMMPS will terminate with an error message saying: "box skew yz is too large". This is because the Y component of the last vector has become larger than half of the Y component of the second vector. LAMMPS requires that this component has a value between -0.5 and +0.5 times the Y component of the second box vector. So here, it should be between -2 and +2. This can be obtained, if assuming periodic boundary conditions, by adding or removing this component. In our example, the previous box is equivalent to the following one (keeping all atoms at the same Cartesian positions):

H1 = [4 0 0]
H2 = [0 4 0]
H3 = [0 -1 40]

Now, the yz component is indeed between -2 and +2, which is suitable for LAMMPS.

In order to make sure that your system is not too much skewed, you may use the option "-unskew" of Atomsk. This option checks the box vectors, and adds the appropriate components to them, to ensure that the box is not "skewed":

atomsk Al.xsf -unskew lammps

To summarize, if you want to make sure that your atomic system complies to LAMMPS requirements, then use the two options "-alignx" and "-unskew" when writing a LAMMPS data file:

atomsk Al.xsf -alignx -unskew lammps

4. Initialize velocities

If you wish to perform a molecular dynamics (MD) simulation, you may want to initialize the velocities of atoms. It is possible to do so directly in the LAMMPS input script, thanks to the velocity command. Or, it is also possible to ask Atomsk to initialize atom velocities according to a Maxwell-Boltzmann distribution, thanks to the option "-velocity".

For instance, to generate a random distribution of atom velocities that follow a Maxwell-Boltzmann distribution, for a temperature of 300 K, you may use the following:

atomsk Al.xsf -duplicate 20 20 20 -velocity 300 lammps

ⓘ The option "-velocities" generates new random velocity vectors every time it is invoked. Velocities are corrected so that there is no global drift of the system (sum of velocity vectors is naught).

The LAMMPS data file (Al.lmp) will contain an additional section "Velocities", containing the components of the velocity (v_x,v_y,v_z) for each atom. These velocities will be used by LAMMPS as initial velocities for the simulation (therefore, it is not necessary to use the "velocity" command in your LAMMPS input script).

Atomsk will write the velocity distribution in an additional file named "velocity_dist.dat", which you can visualize with a graphical tool such as Gnuplot, xmgrace or similar softwares.

5. Add electric charges

If you work with ionic systems, you may want to add electric charges to the LAMMPS data file. There are several ways to do that with Atomsk.

First of all, if your initial file already contains electric charges, in most cases Atomsk reads them and keep them in memory during the conversion (and also if you transform the system with options). In this case, no need to worry: electric charges will be present in the LAMMPS data file produced by Atomsk.

Now, how to proceed if electric charges are not defined in your initial system? Let us construct a unit cell of NaCl for the sake of example:

atomsk --create rocksalt 5.64 Na Cl lammps

The LAMMPS data file will look like this:

Note that this time, the second column indicates that there are atoms of type 1 and of type 2 (respectively Na and Cl atoms), however the number of columns is the same as previously. We expect this material to be ionic, however Atomsk cannot guess the electric charges by itself -we have to provide them explicitely, and there are two ways to add them.

A first possibility, if you already constructed your system and just want to add the charges, is to use the script "lmp_atom2charge.sh" that is provided with Atomsk (in the /tools/ folder). Just provide your file name as an argument:

lmp_atom2charge.sh NaCl.lmp

This script adds a new column containing zeros after the second one, as shown below:

Obviously, this approach does not add the correct electric charges to the file. Therefore, the electric charges must defined within the LAMMPS input script, with the keyword set charge. However, this approach makes sure that the data file "NaCl.lmp" has the correct number of columns for the "atom_style charge" -otherwise LAMMPS would complain that the data file has a wrong format.

A second possibility is to use the option "-properties" to read the electric charges from a file. Let us write this property ("charge") into a text file:

Then, when constructing the system, tell Atomsk to read this property from this file:

atomsk --create rocksalt 5.64 Na Cl -properties charges.txt lammps

In this case, Atomsk will produce a LAMMPS data file with an additional column, containing the electric charges that we provided:

This time, the file contains the electric charges of all ions, therefore it is not necessary to re-define them with the keyword "set charge" in the LAMMPS input script. Also, note that Atomsk adds the keyword "# charge" after the keyword "Atoms". This keyword is optional, but helps the user understand that this data file is suitable for the "atom_style charge" in LAMMPS.

6. Read and convert LAMMPS dump files

Now, let us assume that you ran a calculation with LAMMPS. You should know that LAMMPS can produce dump files containing the atom positions. This can be achieved with the "dump" command in the LAMMPS input script. For instance, to generate atomic data files in Atomeye CFG format, the "dump" command can be paired with the "dump_modify" command so that atom elements are properly written:

In this format it is possible to output reduced wrapped coordinates (xs, ys, zs) or reduced unwrapped coordinates (xsu, ysu, zsu). It is also possible to write any quantity computed by LAMMPS, such as atom velocities, forces, stresses, etc. They are written as "auxiliary properties" in the Atomeye CFG file. The star in the file name ("dump_*.cfg") will be replaced by the step of the simulation. Here we ask for a dump file every 100 steps, therefore LAMMPS will produce files named "dump_0.cfg", "dump_100.cfg", "dump_200.cfg", and so on.

A second possibility is to use the custom output format of LAMMPS:

Using the "id" attribute ensures that the index of atoms is conserved (i.e. they will always be listed in the same order). Note again, that there is no standard extension for LAMMPS custom dump files, therefore we use the extension ".lmc" in this tutorial (short for "LAMMPS custom" format). As before, with such a command LAMMPS will produce files named "dump_0.lmc", "dump_100.lmc", "dump_200.lmc", and so on.

Atomsk can read files in both formats, i.e. Atomeye CFG format or LAMMPS custom format. For instance, to convert the dump file "dump_100.lmc" for visualization with XCrySDen or VESTA, you can use:

atomsk dump_100.lmc xsf

If you perform a long simulation that produces a lot of output files, you can use Atomsk with the mode "--list" to convert all these files. First, create a list of all these files (for instance with "ls") and save it into a text file (for instance "myfiles.lst"). Then, run Atomsk in the mode "--list", as follows:

ls dump*.lmc > myfiles.lst

atomsk --list myfiles.lst xsf

If you already converted some files while the simulation was still running, and wish to only convert the remaining files, then use the option "-ignore". Atomsk will just ignore files that were already converted:

atomsk --list myfiles.lst xsf -ignore

7. Ionic systems: keep electric charges

If you work with ionic systems, you may want to keep the information about electric charges after the LAMMPS simulation. To do so, tell LAMMPS to write electric charges when dumping files, by adding "q" to the dump command as follows:

This way, the dump files will contain the electric charge of ions. When Atomsk reads these files, it will store the charges as auxiliary properties. This is useful to keep the electric charge if you want to convert these dump files into new LAMMPS data files, or if you want to visualize electric charges (e.g. in Atomeye), or if you want to compute a property based on these charges.

8. Deformation simulations: make the box triclinic

By default, if your box is orthogonal, the LAMMPS data file does not contain information about the tilt factors (since they are all equal to zero). However, performing a simulation where you shear the box (i.e. modify the tilt factors) requires that the tilt factors exist in the LAMMPS data file. This can be easily achieved with the bash script "lmp_ortho2tri.sh" provided in the /tools/ folder of Atomsk:

lmp_ortho2tri.sh myfile.lmp

This script simply adds a line containing "0.0000000 0.00000000 0.00000000 xy xz yz" to the LAMMPS data file.

Copyright © Pierre Hirel 2010-2024

This Web site is hosted by the University of Lille