The Swiss-army knife of atomic simulations

Tutorial: working with Quantum Espresso

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

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

Quantum Espresso is an integrated suite of codes performing density functional theory (DFT) calculations. Initiating a calculation (with PWscf) requires an input file containing the parameters for the DFT calculation, and the atom positions. This is where Atomsk can be useful.

ⓘ Atomsk only handles the simulation box vectors and the positions of atoms. It can not handle the electronic structure, or any other information.

1. Set environment variables

When working with Quantum Espresso, it can be practical that some environment variables are set. If they are defined, Atomsk also uses them when writing a file for Quantum Espresso PWscf.

In particular, the environment variable $ESPRESSO_PSEUDO gives the full path to the folder containing the pseudopotential files. By default it points to the folder "$HOME/espresso/pseudo" (in the user's home directory). If you have set a custom path for this environment variable, then Atomsk will use your custom path.

2. Generate a data file for Quantum Espresso PWscf

For the sake of example, let us create a unit cell of fcc aluminium, and write it in the format of Quantum Espresso PWscf:

atomsk --create fcc 4.046 Al pw

Atomsk will produce a file that looks like the following:

title = '# Fcc Al oriented X=[100], Y=[010], Z=[001].'
pseudo_dir = '/home/user/espresso/pseudo/'
calculation = 'scf'

nat= 4
ntyp= 1
ibrav= 0
ecutwfc= 20.0

mixing_beta = 0.7
conv_thr = 1.0d-8



Al 26.982 Al.fixme.upf

4.04600000 0.00000000 0.00000000
0.00000000 4.04600000 0.00000000
0.00000000 0.00000000 4.04600000

Al 0.00000000 0.00000000 0.00000000
Al 2.02300000 2.02300000 0.00000000
Al 0.00000000 2.02300000 2.02300000
Al 2.02300000 0.00000000 2.02300000

K_POINTS automatic
2 2 2 0 0 0

It is important to understand that this file is far from being complete! Atomsk only produces a draft file that contains the atom positions (in Anströms), and a few "default" parameters. If you just run PWscf with this file, you will probably get a lot of errors. You will need to edit almost everything else according to your needs: the path to pseudopotentials, the type of calculation, the values of cutoff, mixing and so on, the name of pseudopotentials, the k-points grid...

Atomsk can write atom positions, but it cannot guess what you want to do. After producing this draft file, you will need knowledge about DFT calculations and Quantum Espresso to perform an actual calculation.

3. Using Bohrs as unit of length

By default Atomsk always assumes angströms. This is meant to ease the conversion to other formats afterwards, especially for visualization since most softwares work with atom coordinates in angströms.

If you want to define atom positions in Bohr units, then use Atomsk with the option "-unit":

atomsk --create fcc 4.046 Al -unit A Bohr pw

Then, the final file will indeed contain atom positions in Bohrs. However one thing will be wrong: the lines "CELL_PARAMETERS" and "ATOMIC_POSITION" will still be followed by "angstrom"! This is because, when writing a PWscf file, Atomsk has no idea about the actual unit that is used. It just assumes that they are angströms. In this case, it is wrong, so you have to change these lines manually, and replace "angstroms" by "bohr".

Alternatively you may use the script "" provided with Atomsk: it just modifies the two aforementionned lines, so that they end with "bohr":

4. Convert PWscf output files

During a calculation, PWscf writes atom positions into a file with the extension ".out". If you performed a self-consistent calculation, then the atoms do not move -therefore it is not very interesting to look at the "final" positions, since they are just the same as the initial ones.

Things are more interesting when performing a relaxation or molecular dynamics run. Then, the output file contains the information about the successive snaphots. The problem here is that all snapshots are contained within one single file -therefore, if we want to visualize them with Atomeye, we cannot just run "atomsk file.out cfg" for instance.

To read PWscf output files, it is necessary to run Atomsk with the mode "one-in-all". This mode reads a single output file that contains several snapshots, and writes each snapshot into a separate file. For instance, to write each snaphot in a separate VESTA file:

atomsk --one-in-all Al.out vesta

This command will produce files named "Al_0.vesta", "Al_1.vesta", and so on, that you can visualize with VESTA.

Atomsk reads the forces acting on atoms, and also writes them if the output format supports it. The VESTA format does, so when you open those files with VESTA, the forces will be displayed as arrows. Usually forces are very small, so it may be desirable to rescale them to have a good visualization. This can be achieved by calling the option "-unit" on each component of the force (fx, fy, fz), for instance:

atomsk --one-in-all Al.out vesta -unit fx 1000 -unit fy 1000 -unit fz 1000

The rescaling factor (1000 in this example) may be changed according to your need: try different values and choose the one that produces the best results according to your eyes.

If, on the contrary, you wish to get rid of the forces, you may remove them with the option "-remove-property":

atomsk --one-in-all Al.out vesta -remove-property all