The Swiss-army knife of atomic simulations

Tutorial: Average Configurations

This tutorial explains how to average atom positions and/or properties over several configurations.

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

Sometimes it can be useful to average atom positions over several configurations. For example, during molecular dynamics (MD) simulations at high temperature, atoms are randomly displaced out of their lattice positions, which complicates their analysis. Averaging atom positions over a few snapshots allows to eliminate thermal noise, and facilitates the analysis.

1. Average a list of files

In the mode "--average", Atomsk requires a list of files. Such a file list has to be constructed before running Atomsk. In GNU/Linux systems, this is easily achieved with the command-line tool "ls".

Assume that you have a series of snapshots from a MD simulation, named "snap_0.cfg", "snap_10.cfg", "snap_20.cfg", and so on up to "snap_10000.cfg". You can write all these file names in a file using:

ls snap*.cfg > list.txt

You can verify that the file "list.txt" contains the name of all the MD snapshots. To average them, run Atomsk in mode "--average":

atomsk --average list.txt averaged.cfg

The averaged positions will be saved in "averaged.cfg", which you can visualize with Atomeye or OVITO.

ⓘ If per-atom properties ("auxiliary" properties) are defined in the input files, then their values are also averaged. If an auxiliary property appears only in some files but not all, then that property will be ignored (it will not appear in the final file).

If you do not wish to average all files, but only some of them, then you can use a loop to write file names to the file "list.txt". In GNU/Linux (bash), such a loop would look like the following:

for (( i=0 ; i<=100 ; i+=10 )) ; do
  echo "snap_$i.cfg" >> list.txt

Starting from i=0 up to i=100, in increments of 10, this loop will add the text "snap_$i.cfg" (replacing "$i" with the actual value of i) to the text file "list.txt". The double redirection (>>) means that each file name will be added at the end of the file (a single redirection would overwrite the file at every iteration).

If you wish to average files from 100 to 200, then modify the loop as follows:

for (( i=100 ; i<=200 ; i+=10 )) ; do
  echo "snap_$i.cfg" >> list.txt

Hopefully these few examples illustrate how to easily create a list of files. Of course, while bash is given here as an example, you may use any language you like to write the text file (Python, C, C++, etc.). After that, just run Atomsk as it is shown above in order to average the configurations corresponding to the list.

2. Average over a sliding window

Atomsk has no built-in capability to perform the averaging over a sliding time window. As explained above, you have to provide the list of files to be averaged.

As before, assume that we have files named from "snap_0.cfg" up to "snap_10000.cfg" by increments of 10. We want to average five configurations at a time: average five configurations from step 0 to step 40, then average from 10 to 50, then from 20 to 60, and so on up to the last configuration, which will average the last five configurations from step 9960 to 10000.

For each time window, we need to write the file "list.txt", and run Atomsk. To achieve that we need two nested loops, the first one looping over all configurations from 0 to 9960, the second one to write the five file names in the file "list.txt". Once the list is written, run Atomsk to average the five configurations, and then iterate the outer loop.

Here is an example (bash):

for (( i=0 ; i<=9960 ; i+=10 )) ; do
  rm -f list.txt
  for (( j=i ; j<$i+50 ; j+=10 )) ; do
    echo "snap_$j.cfg" >> list.txt
  atomsk --average list.txt step_$i.cfg

Using nested loops eases the generation of the file list.

3. Apply options to averaged configurations

If you run Atomsk with options, then these options will be applied to the final averaged system. For example, assume that you want to average configurations and then duplicate the averaged system, then you can use:

atomsk --average list.txt averaged.cfg -duplicate 2 2 2

Similarly, if you wish to delete all auxiliary properties you may use:

atomsk --average list.txt averaged.cfg -remove-property all

Any option can be added to the Atomsk commands above, including those inside loops. This allows for an automatic treatment of all averaged configurations.