Atomsk

The Swiss-army knife of atomic simulations

Tutorial: Boundary Conditions

This tutorial explains how Atomsk deals with the box, the atom positions, and the boundary conditions.

For any atomic system, Atomsk works with at least two irreducible types of data:

Some systems may contain additional information, but all systems contain at least the three box vectors and the atom positions. By default, Atomsk works with the Cartesian positions of atoms, which are absolute and independent of the box vectors.

1. The box vectors

Within Atomsk, the origin of the box is always the origin of Cartesian coordinates (0,0,0).

Some softwares (like LAMMPS) may shift the origin of the box (e.g. in LAMMPS, it takes the values xmin, ymin, zmin). When Atomsk reads such a file, the whole system (i.e. box and atom positions) are shifted, so that the origin of the box is placed at (0,0,0).

2. Atoms outside of the box

For the sake of example, let us create a unit cell of aluminium:

atomsk --create fcc 4.046 Al aluminium.xsf

If you open the file "aluminium.xsf" with a text editor, you will see that it contains the three box vectors, as well as the Cartesian positions of atoms (in Å):

aluminium.xsf

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

In this file, all atoms are inside the box. Now, what happens if we apply a large displacement to all atoms, so that they end up out of the box? Let us try it with the option "-shift":

atomsk aluminium.xsf -shift 10 10 10 Al_shift.xsf

Now, the file looks like this:

Al_shift.xsf

# Fcc Al oriented X=[100], Y=[010], Z=[001].
CRYSTAL
PRIMVEC
4.04600000 0.00000000 0.00000000
0.00000000 4.04600000 0.00000000
0.00000000 0.00000000 4.04600000
CONVVEC
4.04600000 0.00000000 0.00000000
0.00000000 4.04600000 0.00000000
0.00000000 0.00000000 4.04600000
PRIMCOORD
4 1
13 10.00000000 10.00000000 10.00000000
13 12.02300000 12.02300000 10.00000000
13 10.00000000 12.02300000 12.02300000
13 12.02300000 10.00000000 12.02300000

Indeed, all coordinates of atoms were shifted by 10 Å.

This behavior is important: Atomsk keeps the Cartesian coordinates of the atoms. It does not automatically apply periodic boundary conditions (PBC), nor bring the atom back into the box. Keep that in mind when you construct your system: when atoms move around and exit the box, do not expect Atomsk to apply PBC automatically!

If you wish to apply PBC, you have to explicitely ask for it, with the option "-wrap" as explained in section 4 below.

3. Visualization

The visualization of systems containing atoms that are out of the box can be tricky. Let us convert the atomic system (the shifted one) into CFG format for visualization:

atomsk Al_shift.xsf cfg

This will produce a file named "Al_shift.cfg". Let us visualize it with OVITO, as exampled below:

OVITO displays the Cartesian base (coloured arrows labeled x, y, z), the simulation box (black lines), and the atoms as spheres. Indeed, the atoms are outside of the box, as expected from the commands that we ran above.

Now, let us visualize the exact same file ("Al_shift.cfg") with Atomeye:

Two things seem to be wrong here. First, Atomeye displays atoms as if they were inside the box. Why is that? This is because Atomeye automatically shifts atoms, so that they appear to be inside the box. It will never display an atom outside of the box, even if the file does contain out-of-the-box atoms. The second thing is that there are only four atoms in our system, but Atomeye displays more atoms than that. This is because Atomeye considers that our system is "too small", so it duplicates it twice in each direction, as explained in the previous tutorial.

This behavior is very important to keep in mind: some visualization softwares do not show the actual coordinates of atoms as they are written in the file. Instead, they automatically (and silently) shift all atoms so that they are displayed inside the box. However this effect does not mean that all atoms are actually inside the box, in your simulation file. Be careful when visualizing your atomic systems: the visualization may trick you into believing that all atoms are inside the box, but in reality (i.e. in the actual file), some coordinates may be out of the box.

4. Wrapping atoms back into the box

As stated earlier, Atomsk does not automatically put atoms back into the box. If you want atoms to be all inside the box, you have to ask for it explicitely with the option "-wrap". For instance, let us read the file "Al_shifted.cfg" constructed earlier, where all atoms are out of the box, and let us wrap them:

atomsk Al_shift.cfg -wrap Al_wrap.cfg

The option "-wrap" will shift all atoms using the box vectors, until their coordinates fall into the box. Visualization with OVITO confirms that atoms are now indeed inside the box:

5. Reduced coordinates

It is possible to tell Atomsk to convert all atom coordinates from Cartesian (the default) into reduced (or fractional) coordinates, thanks to the option "-fractional":

atomsk Al_shift.xsf -fractional Al_frac.xyz

Reduced, or fractional, coordinates are expressed as a fraction of the box vectors. If atoms are inside the box, all of their coordinates have values between 0 and 1. However, if an atom is out of the box, its reduced coordinates can be smaller than 0 or greater than 1.

Remember that the option "-fractional" does not wrap atoms back into the box, it just divides their coordinates by the box vectors.

6. Summary

When you construct a system with Atomsk, you may shift atoms, insert a dislocation, or apply other transformations that may displace some atoms out of the box. You should keep in mind that Atomsk does not automatically put these atoms back into the box.

If you want to make sure that all atoms are inside the box, simply use the option "-wrap".