PostProc User’s Guide (v.7.

0)

Contents
1 Introduction 1

2 People and terms of use 1

3 Compilation 3

4 Usage 3
4.1 Plotting selected quantities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
4.2 About Bader’s analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
4.3 Band structure, Fermi surface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
4.4 Projection over atomic states, DOS, projected band structure . . . . . . . . . . 4
4.5 Color plot of the Fermi velocity and the orbital character on Fermi surfaces . . . 5
4.6 Wannier functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
4.7 Interfaces to/from other code . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
4.8 Other tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

5 Troubleshooting 7

1 Introduction
This guide covers the usage of PostProc, version 7.0: an open-source package for postprocessing
of data produced by PWscf and CP.
This guide assumes that you know the physics that PostProc describes and the methods it
implements. It also assumes that you have already installed, or know how to install, Quantum
ESPRESSO. If not, please read the general User’s Guide for Quantum ESPRESSO, found
in subdirectory Doc/ of the main Quantum ESPRESSO directory, or consult the web site:
http://www.quantum-espresso.org.
Further documentation, beyond what is provided in this guide, can be found in the direc-
tory PP/Doc/, containing a copy of this guide. People who want to contribute to Quantum
ESPRESSO should read the Wiki pages on GitLab: https://gitlab.com/QEF/q-e/-/wikis.

1
2 People and terms of use
The PostProc package was originally developed by Stefano Baroni, Stefano de Gironcoli, An-
drea Dal Corso (SISSA), Paolo Giannozzi (Univ. Udine), and many others. We mention in
particular:

ˆ Dong Yang and Qin Liu (JSG) for calculation of DORI (10.1021/ct500490b) and for
spin-polarized ELF;

ˆ Minsu Ghim (Seoul National U.) for Ji Hoon Ryoo’s spin-current matrix elements (Phys.
Rev. B 99, 235113) for spin Hall conductivity using Wannier interpolation, in pw2wannier.f90;

ˆ Yang Jiao, Elsebeth Schröder, Per Hyldgaard (Chalmers) for the ppacf.x code;

ˆ Alberto Otero-de-la-Roza for the pw2critic.x utility;

ˆ Junfeng Qiao for improvements to plotband.x;

ˆ Olivia Pulci, Adriano Mosca Conte, Davide Grassano (RomaII) for the pw2gw utility;

ˆ Cyrille Barreteau and Alexander Smogunov (CEA) for magnetic anisotropy with the Force
Theorem in projwfc.f90;

ˆ Andrea Benassi (SISSA) for the epsilon utility, Tae Yun Kim and Cheol-Hwan Park
(Seoul National University) for fixes to it;

ˆ Dmitry Korotin (Inst. Met. Phys. Ekaterinburg) for the wannier ham utility;

ˆ Georgy Samsonidze (Bosch Research) for the interface with the Berkeley GW code,
Fangzhou Zhao (Berkeley) for its extension to hybrid and meta-GGA functionals;

ˆ The late Prof. Eyvaz Isaev for the Fermi Surface code;

ˆ Natalie Holzwarth (WFU) for the PAW projection in code projwfc.f90;

ˆ Takashi Koretsune and Florian Thoele (ETHZ) for noncollinear magnetisation support
with USPP and PAW pseudopotentials in code pw2wannier.f90.

ˆ Leopold Talirz (U.York) for extensions and fixes to pp.x.

PostProc is free software, released under the GNU General Public License. See:
http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt, or the file License in the distri-
bution).
We shall greatly appreciate if scientific work done using the Quantum ESPRESSO dis-
tribution will contain an acknowledgment to the following references:

P. Giannozzi, S. Baroni, N. Bonini, M. Calandra, R. Car, C. Cavazzoni, D. Ceresoli,

G. L. Chiarotti, M. Cococcioni, I. Dabo, A. Dal Corso, S. Fabris, G. Fratesi, S. de
Gironcoli, R. Gebauer, U. Gerstmann, C. Gougoussis, A. Kokalj, M. Lazzeri, L.
Martin-Samos, N. Marzari, F. Mauri, R. Mazzarello, S. Paolini, A. Pasquarello, L.
Paulatto, C. Sbraccia, S. Scandolo, G. Sclauzero, A. P. Seitsonen, A. Smogunov, P.
Umari, R. M. Wentzcovitch, J.Phys.: Condens.Matter 21, 395502 (2009)

2
and
P. Giannozzi, O. Andreussi, T. Brumme, O. Bunau, M. Buongiorno Nardelli, M.
Calandra, R. Car, C. Cavazzoni, D. Ceresoli, M. Cococcioni, N. Colonna, I. Carn-
imeo, A. Dal Corso, S. de Gironcoli, P. Delugas, R. A. DiStasio Jr, A. Ferretti, A.
Floris, G. Fratesi, G. Fugallo, R. Gebauer, U. Gerstmann, F. Giustino, T. Gorni, J
Jia, M. Kawamura, H.-Y. Ko, A. Kokalj, E. Küçükbenli, M .Lazzeri, M. Marsili, N.
Marzari, F. Mauri, N. L. Nguyen, H.-V. Nguyen, A. Otero-de-la-Roza, L. Paulatto,
S. Poncé, D. Rocca, R. Sabatini, B. Santra, M. Schlipf, A. P. Seitsonen, A. Smo-
gunov, I. Timrov, T. Thonhauser, P. Umari, N. Vast, X. Wu, S. Baroni, J.Phys.:
Condens.Matter 29, 465901 (2017)
Users of the GPU-enabled version should also cite the following paper:
P. Giannozzi, O. Baseggio, P. Bonfà, D. Brunato, R. Car, I. Carnimeo, C. Cavazzoni,
S. de Gironcoli, P. Delugas, F. Ferrari Ruffino, A. Ferretti, N. Marzari, I. Timrov,
A. Urru, S. Baroni, J. Chem. Phys. 152, 154105 (2020)
Note the form Quantum ESPRESSO for textual citations of the code. Please also see
package-specific documentation for further recommended citations. Pseudopotentials should
be cited as (for instance)
[ ] We used the pseudopotentials C.pbe-rrjkus.UPF and O.pbe-vbc.UPF from
http://www.quantum-espresso.org.

3 Compilation
PostProc is part of the Quantum ESPRESSO distribution and depends upon PWscf for com-
pilation. For instruction on how to download and compile Quantum ESPRESSO, please refer
to the general Users’ Guide, available in file Doc/user guide.pdf under the main Quantum
ESPRESSO directory, or in web site http://www.quantum-espresso.org.
Once Quantum ESPRESSO is correctly configured, PostProc can be compiled by just
typing make pp, from the main Quantum ESPRESSO directory; or typing make from the
PP/ subdirectory. Several executable codes are produced in PP/bin and linked to bin/.

4 Usage
All codes for which input documentation is not explicitly mentioned below have some documen-
tation in the header of the fortran sources. In the following, subdirectories containing examples
are found in PP/examples/; “Example N” stands for subdirectory PP/examples/exampleN/.
All quantities whose dimensions are not explicitly specified are in RYDBERG ATOMIC
UNITS. Charge is ”number” charge (i.e. not multiplied by e); potentials are in energy units
(i.e. they are multiplied by e).

4.1 Plotting selected quantities

The main postprocessing code pp.x extracts the specified data from the data files produced by
PWscf (pw.x executable) or CP (cp.x executable); prepares data for plotting by writing them
into formats that can be read by several plotting programs.

3
 Quantities that can be read or calculated are:

charge density
spin polarization
various potentials
local density of states at EF
local density of electronic entropy
STM images
selected squared wavefunction
ELF (electron localization function)
RDG (reduced density gradient)
integrated local density of states

Various types of plotting (along a line, on a plane, three-dimensional, polar) and output formats
(including the popular cube format) can be specified. Moreover data can be saved to an
intermediate (formatted) file so that more data sets can be summed or subracted in a later
run. The output files can be directly read by the free plotting system Gnuplot (1D or 2D
plots), or by code plotrho.x that comes with PostProc and produces PostScript 2D plots, or
by advanced plotting software XCrySDen (3D plots).
See file PP/Doc/INPUT PP.* for a detailed description of the input for code pp.x. See
Example 01 for an example of a charge density plot, Example 03 for an example of STM image
simulation.

Planar averages Code plan avg.x calculates planar averages of Kohn-Sham orbitals. Input
documentation is in the header ofPP/src/plan avg.f90.
Code average.x calculates planar averages of quantities produced by pp.x (e.g. potentials,
charge, magnetization densities). Note that average.x reads the intermediate file produced
by pp.x, not data files produced by pw.x. Examples of usage of average.x can be found in
PP/examples/WorkFct example/ and in PP/examples/dipole example/.

All-electron charge pawplot.x produces plots of the all-electron charge for PAW calcula-
tions. Input documentation in the header of PP/src/pawplot.f90.

4.2 About Bader’s analysis

In http://theory.cm.utexas.edu/henkelman/code/bader/ one can find a software that per-
forms Bader’s analysis starting from charge on a regular grid. One should use PAW to compute
the charge density. The required ”cube” format can be produced using pp.x (info by G.
Lapenna who has successfully used this technique, but adds: “Problems occur with polar X-H
bonds or in all cases where the zero-flux of density comes too close to atoms described with
pseudo-potentials”). This code should perform decomposition into Voronoi polyhedra as well,
in place of obsolete code voronoy.x (removed from distribution since v.4.2). Alternatively, you
can use CRITIC2, available at https://github.com/aoterodelaroza/critic2, which can
read directly pw.x output and “XSF” files. CRITIC2 functionaly include Bader’s AIM, ELF,
laplacian of density and potentials, non-covalente interaction (NCI) plots and much more.

4
4.3 Band structure, Fermi surface
The code bands.x reads data file(s), extracts eigenvalues, regroups them into bands (the algo-
rithm used to order bands and to resolve crossings may not work in all circumstances, though).
The output is written to a file in a simple format that can be directly read and converted to
plottable format by auxiliary code plotband.x. Unpredictable plots may results if k-points
are not in sequence along lines, or if two consecutive points are the same. The code bands.x
performs as well a symmetry analysis of the band structure. For a complete input description,
see Doc/INPUT bands.*. See Example 01, Example 04 and Example 06 for simple band plots.
The plotting of Fermi surfaces can be performed using code fs.x. The resulting file in .bxsf
format can be read and plotted using XCrySDen. See Example 02 for an example of Fermi
surface visualization (Ni, including the spin-polarized case).

4.4 Projection over atomic states, DOS, projected band structure

The code projwfc.x calculates projections of wavefunctions over atomic orbitals. The atomic
wavefunctions are those contained in the pseudopotential file(s). The Löwdin population anal-
ysis (similar to Mulliken analysis) is presently implemented. The projected DOS (or PDOS:
the DOS projected onto atomic orbitals) can also be calculated and written to file(s). More de-
tails on the input data are found in file PP/Doc/INPUT PROJWFC.*. The ordering of the various
angular momentum components (defined in routine ylmr2.f90) is as follows: P0,0 (t), P1,0 (t),
P1,1 (t)cosφ, P1,1 (t)sinφ, P2,0 (t), P2,1 (t)cosφ, P2,1 (t)sinφ, P2,2 (t)cos2φ, P2,2 (t)sin2φ and so on,
where Pl,m =Legendre Polynomials, t = cosθ = z/r, φ = atan(y/x).
Data produced by code projwfc.x can be further analysed using auxiliary codes sumpdos.x
(sums selected PDOS by specifying the names of files containing the desired PDOS: type
sumpdos.x -h or look into the source code for more details) and plotproj.x . A more so-
phisticated tools is the script PP/tools/sum states.py, by Julen Larrucea: documentation in
http://larrucea.eu/sum states-py-2/.
The total electronic DOS can also be calculated by code dos.x, whose complete input
documentation is in PP/Doc/INPUT DOS.* See Example 02 for total and projected electronic
DOS calculations, -and for projected band structure; see Example 03 for projected and local
DOS calculations.
The DOS projected over molecular states (e.g. for a molecule on a surface system) can be
computed using code molecularpdos.x (courtesy of Guido Fratesi). See file PP/Doc/INPUT MOLDOS.*
for input documentation and directory PP/examples/MolDos example/ for an example.
The calculation of magnetic anisotropy using the Force Theorem is described in the following
paper: https://journals.aps.org/prb/abstract/10.1103/PhysRevB.90.205409. An example and
a README can be found in PP/examples/ForceTheorem example/

4.5 Color plot of the Fermi velocity and the orbital character on
Fermi surfaces
You can plot any quantity on Fermi surfaces as a color plot by using fermisurfer program1 .
fermi_velocity.x and fermi_proj.x are used to generate an input file for fermisurfer from
the output of pw.xor projwfc.x.
fermi_velocity.x generates a color-plot of Fermi velocity. You use it as follows:
1
http://osdn.jp/projects/fermisurfer/

5
 1. Run pw.xwith K_POINT automatic.
2. Run

$ fermi_velocity.x -in {pw.x input file}

3. vfermi.frmsf is generated
fermi_proj.x generates a color plot of an orbital character. You use it as follows:
1. Run pw.xwith K_POINT automatic.
2. Run projwfc.x just to generate {prefix}.save/atomic_proj.*.
3. Run

$ fermi_proj.x -in {input file}

Input-file format is as follows:

&PROJWFC
{The same as the input of projwfc.x}
/
{Number of target wavefunctions}
{Index of target WFC1} {Index of target WFC2} {Index of target WFC3} ...
Pntarget
It generates i=1 |hϕatom 2
target(i) |ϕnk i| , where ns and target(i) are the number of the target
wavefunctions and the indices of target wavefunctions, respectively.
4. The above quantity is written into "proj.frmsf", which can be read by FermiSurfer
program.
There is an example of fermi_velocity.x and fermi_proj.x in fermisurf_example/.

4.6 Wannier functions

There are several Wannier-related utilities in PostProc:
1. The ”Poor Man Wannier” code pmw.x, to be used in conjunction with DFT+U calcula-
tions: see Example 05.
2. The interface with Wannier90 code, pw2wannier.x: see the documentation in W90/
(you may install the Wannier90 plug-in via make w90 ). For spin-current matrix el-
ements, implemented in routine compute shc: “it writes .sIu and .sHu files used for
WANNIER-BERRI (https://github.com/stepan-tsirkin/wannier-berri/), and also will be
utilized through postw90.x (https://github.com/manxkim/wannier90/tree/SHC/src) in
Wannier90. In WANNIER-BERRI, .sHu and .sIu files can be used to calculate the quan-
tity ”opt SHCryoo”. In Wannier90, add ”berry task = shc” and ”shc ryoo=.true.”. in
the input parameters of postw90.x. They activate the calculation of SHC using .sHu and
.sIu.”
3. The wannier ham.x code generates a model Hamiltonian in Wannier functions basis: see
PP/examples/WannierHam example/.
Note that the wfdd.x code has been moved to CP.

6
4.7 Interfaces to/from other code
Codes pw2bgw.x convert data files from pw.x to a format suitable for usage by the Berkeley GW
code. See file Doc/INPUT pw2bgw.* for input data documentation. Code bgw2pw.x, performing
the inverse conversion, no longer works: a copy that worked for the old file format is kept for
reference in bgw2pw.f90.orig.
Code pw2gw.x converts data files from pw.x to a format suitable for usage by another
GW code, computes optical properties in single-particle approach (Fermi Golden Rule). See
file Doc/INPUT pw2gw.html for input data documentation, directory pw2gw example/ for an
example of usage.
Code open grid.x writes Kohn-Sham orbitals for the complete k-point grid (not symmetry-
independent points only) in real space. Useful for further processing. It can be used to generate
the Kohn-Sham state data required in pw2wannier.x and Wannier90 from the initial SCF
calculation, bypassing the non-SCF calculation step.
Code pw2critic.x is an interface to the CRITIC2 code by Alberto Otero-de-la-Roza. This
program creates a pwc file containing the Kohn-Sham orbitals from an SCF calculation (or from
the output of open grid.x). These orbitals are used for post-processing in CRITIC2.
Code pw export.f90 no longer works and is no longer present.

4.8 Other tools

Exchange-correlation Code ppacf.x computes the coupling constant dependency of the
exchange correlation potential Exc,λ , λ ∈ [0 : 1] and the spatial distribution of the exchange-
correlation energy density and kinetic correlation energy density according to: Y. Jiao, E.
Schröder, and P. Hyldgaard, Phys. Rev. B 97, 085115 (2018). See PP/Doc/INPUT PPACF.html.

Wavefunction conversion Code wfck2r.x converts Kohn-Sham orbitals from reciprocal

to real space. It is a useful starting point if you need to access wavefunctions and perform
postprocessing operations that are not implemented in Quantum ESPRESSO.

Dielectric function Code epsilon.x calculates RPA frequency-dependent complex dielec-

tric function. Documentation is in file Doc/eps man.tex.

Core-level shifts Code initial state.x calculates the initial state contribution to the
Core-level shift. See CLS IS example/ for an example, and CLS FS example/ for the corre-
sponding final state calculation of Core-level shifts.

5 Troubleshooting
Almost all problems in Quantum ESPRESSO arise from incorrect input data and result in
error stops. Error messages should be self-explanatory, but unfortunately this is not always
true. If the code issues a warning messages and continues, pay attention to it but do not assume
that something is necessarily wrong in your calculation: most warning messages signal harmless
problems.

7
Some postprocessing codes complain that they do not find some files Most likely
you are not reading the correct data files, or you are not following the correct procedure for
postprocessing.
For Linux PC clusters in parallel execution: in at least some versions of MPICH, the current
directory is set to the directory where the executable code resides, instead of being set to the
directory where the code is executed. This MPICH weirdness may cause unexpected failures
in some postprocessing codes that expect a data file in the current directory. Workaround: use
symbolic links, or copy the executable to the current directory.