A tiny introduction to Q-E

Gabriele Sclauzero (SISSA)

(gently stolen from P.Giannozzi, S. de Gironcoli, and others...)

Introducing Q-E

The fundamental questions (and answers)!

Q. What is Quantum ESPRESSO (Q-E)?

R. Quantum ESPRESSO is an integrated suite of computer codes for electronic-structure calculations and materials modeling at the nanoscale. It is based on density-functional theory, plane waves, and pseudopotentials (both norm-conserving, ultrasoft, and PAW).

Q. What does Quantum ESPRESSO stand for?

R. Quantum ESPRESSO stands for opEn Source Package for Research in Electronic Structure, Simulation, and Optimization. It is freely available to researchers around the world under the terms of the GNU General Public License.

Q. Who are the developers?

R. Quantum ESPRESSO is an initiative of the DEMOCRITOS National Simulation Center (Udine - Trieste) and of its partners, in collaboration with the CINECA National Supercomputing Center in Bologna, the Ecole Polytechnique Federale de Lausanne, Princeton University, and the Massachusetts Institute of Technology.

Since end 2008 the Q-E project is hosted on a new development platform called QEforge, with a feature-rich web portal (http://qe-forge.org) based on the Gforge engine. The website is also currently hosting other projects, more or less bounded to the Q-E project:

TDDFPT (Time-Dependent Density-Functional Perturbation Theory, to be integrated in Q-E in the next future)
GWW (GW method with Wannier functions)
SAX (self energies and excitonic effects within GW)
...

Q. What can QE do?

Check out http://www.quantum-espresso.org/whatcanqedo.php for the full list!

Ground-state calculations (within density-functional theory):

Self-consistent total energies, forces, stresses;
Separable norm-conserving and ultrasoft (Vanderbilt) pseudo-potentials, PAW (Projector Augmented Waves);
Several exchange-correlation functionals (including exact exchange and hybrid functionals);
Hubbard U (LDA+U);
Berry's phase polarization;
Spin-orbit coupling and noncollinear magnetism;
Maximally-localized Wannier functions;
...

Response properties (density-functional perturbation theory):

Phonon frequencies and eigenvectors at any wavevector;
Full phonon dispersions; inter-atomic force constants in real space;
Effective charges and dielectric tensors;
Electron-phonon interactions;
Third-order anharmonic phonon lifetimes;
Infrared and (non-resonant) Raman cross-sections;
EPR and NMR chemical shifts;
...

Ab-initio molecular dynamics:

Car-Parrinello Molecular Dynamics;
Microcanonical (Verlet) dynamics;
Isothermal (canonical) dynamics - Nose-Hoover thermostats and chains;
Born-Oppenheimer Molecular Dynamics;
...

Structural Optimization:

GDIIS with quasi-Newton BFGS preconditioning;
Damped dynamics;
Transition states and minimum energy paths:
Born-Oppenheimer nudged elastic band (NEB);
...

...on many different hardware and software configurations.

Main structure of the Q-E suite

The Q-E suite is made up of a number of distinct, interoperating programs, each of them with a specific task. The source tree of Q-E is organized in a set of directories which contain:

shared subroutines, data structures, I/O methods:

clib,flib

C and Fortran general purpose libraries and functions

Modules

F90 modules (data structures plus initialization and manipulation subroutines, interfaces, wrappers, ...)

iotk

input/output XML based library
The two principal electronic-structure packages:

PW

electronic-structure DFT plane-waves code, pw.x

CPV

Car-Parrinello molecular dynamics code, cp.x
Programs which need data (such as self-consistent electronic charge density or KS states) produced by pw.x or cp.x to compute basic and advanced properties:

PH

code for linear response properties (within DFPT), ph.x

PP

many programs for post-processing and visualization (charge density and KS eigenstates, pp.x; bands, bands.x; DOS, dos.x and projwfc.x; ...)

PWCOND

code for the (Landauer-Büttiker) ballistic conductance, pwcond.x

W90

code for Maximally-localized Wannier functions, wannier90.x

...

Every single executable file will be automatically linked in the bin/ directory.

What should I do in order to start using Q-E?

First, get the executables

Possibilities:

Compile from source (preferred solution when good performance is a must)
QE-live CD (available from QEforge): gadget of this school
Precompiled versions (not yet available, maybe coming soon)

To compile the source files you need at least: a Unix-like working environment (Linux, OS-X, AIX, Cygwin on MS Windows, ...), a good (non-buggy) F90 compiler and a working C compiler; some free space on your hard-disk. To get fast executables you need: a well performing compiler (e.g. ifort on Intel machines, xlf on IBM, ...), libraries optimized for your machine (e.g. MKL on Intel, ACML on AMD, ESSL on IBM,...), good hardware (of course ...) and properly set up OS and system libraries.

Download the latest version (presently 4.1, just released) from http://www.quantum-espresso.org/download.php. If you need to use advanced features which are available only in the develompment version:
- anonymous access to the CVS tree on QEforge (see https://qe-forge.org/scm/?group_id=10)
- download the latest CVS tree snapshot from https://qe-forge.org/snapshots.php?group_id=10
Unpack the gzipped tar archive (e.g. tar zxvf espresso-x.x.x.tar.gz). Use a partition with enough space, since after compilation the size of the whole can reach several hundreds of MBytes.
Run the configure script (cd espresso-x.x.x; ./configure): lots and lots of output on the screen...
If everything goes smoothly, type make to get a list of the targets (subsets of executables) that can be built and then build them with make [target1] [target2] ... (be prepared to see tons of output from the compiler ...)
If something fails, try to figure out why by looking at the troubleshooting section of the Q-E manual, the FAQs on the Q-E Wikipage, or by asking to the PWscf Forum (see below for reference links).

How to learn usage/features of Q-E?

There are several places where you can get helpful information:

This tutorial (of course!)
Past tutorials (which may have been covering different topics/features): many are linked on the Q-E website at http://www.quantum-espresso.org/wiki/index.php/Tutorials_and_Examples
Main Q-E website www.quantum-espresso.org (features Wikipage, online manuals, FAQ, and much more)
Plenty of examples in the espresso-x.x.x/examples/ directory in the Q-E source tree

Input file description, both in text format, under espresso-x.x.x/Doc/

[gabriele@macgurlo:~/SW/espresso-4.1/Doc]$ ls *.txt
INPUT_BANDS.txt     INPUT_DOS.txt       INPUT_PH.txt        INPUT_PW.txt
INPUT_CPPP.txt      INPUT_GIPAW.txt     INPUT_PP.txt        INPUT_PWCOND.txt
INPUT_D3.txt        INPUT_LD1.txt       INPUT_PROJWFC.txt   INPUT_pw_export.txt

and in html format, online at http://www.quantum-espresso.org/input-syntax/INPUT_PW.html

PWscf Users Forum: you can subscribe at http://www.democritos.it/mailman/listinfo/pw_forum. Before asking a question, please first check out FAQ at http://www.quantum-espresso.org/wiki/index.php/FAQ and Forum Archives ( Tip: try searching something like whatIwanttoknow pw_forum site:democritos.it on Google)
The forthcoming Q-E paper: submitted to J.Phys.: Condens. Matter, preliminary version available on arXiv at http://arxiv.org/abs/0906.2569

Basics to start the tutorials of this School

Brief input description for PWscf

It uses namelists (aka list-directed I/O, a standard F90 construct) and input cards (Q-E-specific construct).

Namelists allow to access only those variables which need to be changed, while leaving the others to the default value.
All variables included in a namelist can be accessed by their name after addressing the namelist with an ampersand before its name. After listing all variables to be changed, ``close'' the namelist using &end or /. For instance, if you want to change only variables aaa (integer) and zzz (double precision) in a namelist called nnn, while leaving all the others to the default value, write:
```
&nnn
  aaa=1,
  zzz=333.d-3
/
```
Inside a namelist, variables can be specified in any order, but namelists are read in a prefixed order.
In Q-E there are three mandatory namelists
- &CONTROL : controls the type of calculation and its I/O flux
- &SYSTEM : specifies some details of the system and the convergence cut-offs
- &ELECTRONS : controls the algorithms used to reach self-consistency
The other namelists are required for specific kinds of calculation, and are ignored in not needed:
- &IONS : controls ionic movement in MD runs or structural relaxations
- &CELL : controls changes in the cell parameters in variable cell runs
- &PHONON : used only when preparing data for phonon calculations
Input cards are read after namelists and start with the input card name plus some optional arguments (usually to choose units, axis,...)
Input cards which do not have a logical dependence upon others can be specified in any order, otherwise a logical ordering applies.
Input cards are used to specify data always needed on input (e.g. 3D vectors representing atomic positions), which cannot not be specified in a comfortable way through the usage of namelists. There are three mandatory input cards
- ATOMIC_SPECIES : name, mass and pseudopotential for each of the atomic species in the system
- ATOMIC_POSITIONS : name of the species and components of the position vector for each atom
- K_POINTS : k-point sampling of the BZ
Additional input cards are
- CELL PARAMETERS : user supplied unit cell axis
- OCCUPATIONS : user supplied occupations of KS states
- CLIMBING_IMAGES : used only for NEB calculations

How to feed (your input to) pw.x

Assuming that the bin/ directory of Q-E is in your path, if you execute PWscf it will wait for input:

[gabriele@macgurlo:~/myworkdir]$ pw.x

     Program PWSCF     v.4.0.5  starts ...
     Today is 16Jul2009 at 17:12: 8 

     Parallel version (MPI)

     Number of processors in use:       1

     For Norm-Conserving or Ultrasoft (Vanderbilt) Pseudopotentials or PAW

     Current dimensions of program pwscf are:
     Max number of different atomic species (ntypx) = 10
     Max number of k-points (npk) =  40000
     Max angular momentum in pseudopotentials (lmaxx) =  3
     Waiting for input...

You could write down row by row directly on the terminal: not much practical...

Usually it is preferable to edit an input file (filling it with the namelists and input cards described above) and then feed it to the program using input redirection (a standard feature of all BASH-like shells).
```
[gabriele@macgurlo:~/myworkdir]$ vi myinput
[gabriele@macgurlo:~/myworkdir]$ pw.x < myinput
```
You can also redirect output to a file (instead of watching it on the screen in real-time), since it contains many important information (i.e. physics) of your system!
```
[gabriele@macgurlo:~/myworkdir]$ pw.x < myinput > myoutput
```
Alternatively, if you want to follow the steps of a calculation on your screen, you can duplicate the standard output and send one copy to a file, the other to the screen:
```
[gabriele@macgurlo:~/myworkdir]$ pw.x < myinput | tee myoutput
```

In this way you can store the information and later process textually the file to search for some computed quantity (for instance if you search for the string ! at the beginning of the line, you'll find...

[gabriele@macgurlo:~/myworkdir]$ grep '^!' myoutput
!    total energy              =      -4.18281107 Ry

This allows to check your input file with XCrysDEn (www.xcrysden.org),

[gabriele@macgurlo:~/myworkdir]$ xcrysden --pwi myinput

(especially useful for complicated structures). You can also check the final output structure of a relaxation run or the single steps of a MD run with:

[gabriele@macgurlo:~/myworkdir]$ xcrysden --pwo myoutput

Finally, a full example of a simple input file (you will recognize it in few minutes...):

 &control
    calculation = 'scf',
    prefix = 'Si_exc1',
 /
 &system
    ibrav =  2, 
    celldm(1) = 10.26, 
    nat =  2, 
    ntyp = 1,
    ecutwfc = 20
 /
 &electrons
    mixing_beta = 0.7
 /

ATOMIC_SPECIES
 Si 28.086  Si.pbe-rrkj.UPF

ATOMIC_POSITIONS (alat)
 Si 0.0 0.0 0.0
 Si 0.25 0.25 0.25

K_POINTS (automatic)
  6 6 6 1 1 1

Instructions for these tutorials

Unpack the archive with all the stuff (there is a copy of it in each PC under the /tmp directory):

[myname@esbtl-xx:~]$ tar zxvf /tmp/QE-school.tgz

Enter the directory and source the setup script

[myname@esbtl-xx:~]$ cd QE-school
[myname@esbtl-xx:~/QE-school]$ source qe-setup.sh

You're done! If everything went fine, you should now be able to run pw.x and the other Q-E executables from the command line.

[myname@esbtl-xx:~]$ pw.x

     Program PWSCF     v.4.1CVS  starts ...
     Today is 20Jul2009 at 15:12: 8 

     Parallel version (MPI)

     Number of processors in use:       1

     For Norm-Conserving or Ultrasoft (Vanderbilt) Pseudopotentials or PAW

     Current dimensions of program pwscf are:
     Max number of different atomic species (ntypx) = 10
     Max number of k-points (npk) =  40000
     Max angular momentum in pseudopotentials (lmaxx) =  3
     Waiting for input...

All you need for the first day exercises (input files or scripts plus instructions) is already in week1/day1/. For each of the next days an archive with input files and instructions will be uploaded to the Q-E wiki page (reference will be given time after time). For the next days, you will download the archive Wxdx.tgz, put it in your QE-school folder and unpack it with tar zxvf Wxdx.tgz (all files will go in their place).

You also have the source tree of Q-E in QE-school/espresso-4.1.tar.gz, packed as you can find it on the Q-E website. We have not the time to go through the compilation steps right now, but we will assist you if you would like to dedicate to it some of your spare time in the next days. Or you can even unpack it simply because you want to have a look at the source code, when you are curious ...

Have fun with Q-E!!!

Gabriele Sclauzero 2009-07-20