Atomsk

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.

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.

Note: Atomsk only handles the simulation box vectors and the positions of atoms -and not 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:

Al.pw

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

&SYSTEM
nat= 4
ntyp= 1
ibrav= 0
ecutwfc= 20.0
/

&ELECTRONS
mixing_beta = 0.7
conv_thr = 1.0d-8
/

&IONS
/

&CELL
/

ATOMIC_SPECIES
Al 26.982 Al.fixme.upf

CELL_PARAMETERS angstrom
4.04600000 0.00000000 0.00000000
0.00000000 4.04600000 0.00000000
0.00000000 0.00000000 4.04600000

ATOMIC_POSITIONS angstrom
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 "qepw_bohr.sh" provided with Atomsk: it just modifies the two aforementionned lines, so that they end with "bohr":

qepw_bohr.sh Al.pw

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 it will display the forces as arrows.