Atomsk

The Swiss-army knife of atomic simulations

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.

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 script structure 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.

Note: for the moment, Atomsk does not support bonds and molecules.

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:

Al.lmp

# Fcc Al oriented X=[100], Y=[010], Z=[001].

4 atoms
1 atom types

0.00000000 4.04600000 xlo xhi
0.00000000 4.04600000 ylo yhi
0.00000000 4.04600000 zlo zhi

Atoms

1 1 0.00000000 0.00000000 0.00000000
2 1 2.02300000 2.02300000 0.00000000
3 1 0.00000000 2.02300000 2.02300000
4 1 2.02300000 0.00000000 2.02300000

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":

in.aluminium

...
read_data Al.lmp
...

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:

Al.xsf

# Fcc Al oriented X=[100], Y=[010], Z=[001].
CRYSTAL
PRIMVEC
2.86095404 2.02300000 -2.02300000
0.00000000 2.86095404 2.86095404
2.86095404 -2.02300000 2.02300000
CONVVEC
2.86095404 2.02300000 -2.02300000
0.00000000 2.86095404 2.86095404
2.86095404 -2.02300000 2.02300000
PRIMCOORD
4 1
13 0.00000000 0.00000000 0.00000000
13 1.43047702 2.44197702 0.41897702
13 1.43047702 0.41897702 2.44197702
13 2.86095404 -0.00000000 0.00000000

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 Å3, 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. 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:

NaCl.lmp

# Rocksalt NaCl oriented X=[100], Y=[010], Z=[001].

8 atoms
2 atom types

0.00000000 5.64000000 xlo xhi
0.00000000 5.64000000 ylo yhi
0.00000000 5.64000000 zlo zhi

Atoms

1 1 0.00000000 0.00000000 0.00000000
2 1 2.82000000 2.82000000 0.00000000
3 1 0.00000000 2.82000000 2.82000000
4 1 2.82000000 0.00000000 2.82000000
5 2 2.82000000 0.00000000 0.00000000
6 2 0.00000000 2.82000000 0.00000000
7 2 0.00000000 0.00000000 2.82000000
8 2 2.82000000 2.82000000 2.82000000

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:

NaCl.lmp

# Rocksalt NaCl oriented X=[100], Y=[010], Z=[001].

8 atoms
2 atom types

0.00000000 5.64000000 xlo xhi
0.00000000 5.64000000 ylo yhi
0.00000000 5.64000000 zlo zhi

Atoms

1 1 0.0 0.00000000 0.00000000 0.00000000
2 1 0.0 2.82000000 2.82000000 0.00000000
3 1 0.0 0.00000000 2.82000000 2.82000000
4 1 0.0 2.82000000 0.00000000 2.82000000
5 2 0.0 2.82000000 0.00000000 0.00000000
6 2 0.0 0.00000000 2.82000000 0.00000000
7 2 0.0 0.00000000 0.00000000 2.82000000
8 2 0.0 2.82000000 2.82000000 2.82000000

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:

charges.txt

charge
Na 1
Cl -1

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:

NaCl.lmp

# Rocksalt NaCl oriented X=[100], Y=[010], Z=[001].

8 atoms
2 atom types

0.00000000 5.64000000 xlo xhi
0.00000000 5.64000000 ylo yhi
0.00000000 5.64000000 zlo zhi

Atoms # charge

1 1 1.000 0.00000000 0.00000000 0.00000000
2 1 1.000 2.82000000 2.82000000 0.00000000
3 1 1.000 0.00000000 2.82000000 2.82000000
4 1 1.000 2.82000000 0.00000000 2.82000000
5 2 -1.000 2.82000000 0.00000000 0.00000000
6 2 -1.000 0.00000000 2.82000000 0.00000000
7 2 -1.000 0.00000000 0.00000000 2.82000000
8 2 -1.000 2.82000000 2.82000000 2.82000000

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.

5. 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.aluminium

dump myCFG all cfg 100 dump_*.cfg mass type xs ys zs
dump_modify element Al

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:

in.aluminium

dump mydump all custom 100 dump_*.lmc id mass type element xu yu zu
dump_modify element Al

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

6. 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:

in.NaCl

dump mydump all custom 100 dump_*.lmc mass type element xu yu zu q
dump_modify element Al

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.

7. 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.