TABLE OF CONTENTS
INTRODUCTION
&INPUTPP
prefix  outdir  filplot  plot_num  spin_component  spin_component  emin  emax  delta_e  degauss_ldos  use_gauss_ldos  sample_bias  kpoint  kband  lsign  spin_component  emin  emax  spin_component  spin_component  spin_component  spin_component
&PLOT
nfile  filepp  weight  iflag  output_format  fileout  interpolation  e1  x0  nx  e1  e2  x0  nx  ny  e1  e2  e3  x0  nx  ny  nz  radius  nx  ny
INTRODUCTION
Purpose of pp.x: data analysis and plotting.
The code performs two steps:
(1) reads the output produced by pw.x, extracts and calculates
the desired quantity/quantities (rho, V, ...)
(2) writes the desired quantity to file in a suitable format for
various types of plotting and various plotting programs
The input data of this program is read from standard input
or from file and has the following format:
NAMELIST &INPUTPP
containing the variables for step (1), followed by
NAMELIST &PLOT
containing the variables for step (2)
The two steps can be performed independently. In order to perform
only step (2), leave namelist &INPUTPP blank. In order to perform
only step (1), do not specify namelist &PLOT
Intermediate results from step 1 can be saved to disk (see
variable filplot in &INPUTPP) and later read in step 2.
Since the file with intermediate results is formatted, it
can be safely transferred to a different machine. This
also allows plotting of a linear combination (for instance,
charge differences) by saving two intermediate files and
combining them (see variables weight and filepp in &PLOT)
All output quantities are in ATOMIC (RYDBERG) UNITS unless
otherwise explicitly specified.
All charge densities integrate to the NUMBER of electrons
not to the total charge.
All potentials have the dimension of an energy (e*V, not V).
Namelist: &INPUTPP

prefix 
CHARACTER 
prefix of files saved by program pw.x

outdir 
CHARACTER 
Default: 
value of the ESPRESSO_TMPDIR environment variable if set;
current directory ('./') otherwise

directory containing the input data, i.e. the same as in pw.x

filplot 
CHARACTER 
file "filplot" contains the quantity selected by plot_num
(can be saved for further processing)

plot_num 
INTEGER 
Selects what to save in filplot:
0 = electron (pseudo)charge density
1 = total potential V_bare + V_H + V_xc
2 = local ionic potential V_bare
3 = local density of states at specific energy or grid of energies
(number of states per volume, in bohr^3, per energy unit, in Ry)
4 = local density of electronic entropy
5 = STM images
Tersoff and Hamann, PRB 31, 805 (1985)
6 = spin polarization (rho(up)rho(down))
7 = contribution of selected wavefunction(s) to the
(pseudo)charge density. For normconserving PPs,
psi^2 (psi=selected wavefunction). Noncollinear case:
contribution of the given state to the charge or
to the magnetization along the direction indicated
by spin_component (0 = charge, 1 = x, 2 = y, 3 = z )
8 = electron localization function (ELF)
9 = charge density minus superposition of atomic densities
10 = integrated local density of states (ILDOS)
from emin to emax (emin, emax in eV)
if emax is not specified, emax=E_fermi
11 = the V_bare + V_H potential
12 = the sawtooth electric field potential (if present)
13 = the noncollinear magnetization.
17 = allelectron valence charge density
can be performed for PAW calculations only
requires a very dense realspace grid!
18 = The exchange and correlation magnetic field in the noncollinear case
19 = Reduced density gradient
( J. Chem. Theory Comput. 7, 625 (2011), doi:10.1021/ct100641a )
Set the isosurface between 0.3 and 0.6 to plot the
noncovalent interactions (see also plot_num = 20)
20 = Product of the electron density (charge) and the second
eigenvalue of the electrondensity Hessian matrix;
used to colorize the RDG plot (plot_num = 19)
21 = allelectron charge density (valence+core).
For PAW calculations only; requires a very dense realspace grid.
22 = kinetic energy density (for metaGGA and XDM only)
123 = DORI: density overlap regions indicator
(doi: 10.1021/ct500490b) Implemented by D. Yang & Q.Liu

IF plot_num = 0 or 9 :
Options for total charge (plot_num=0)
or for total minus atomic charge (plot_num=9):
spin_component 
INTEGER 
Default: 
0

0 = total charge (default value),
1 = spin up charge,
2 = spin down charge.


ELSEIF plot_num=1 :
Options for total potential (plot_num=1):
spin_component 
INTEGER 
Default: 
0

0 = spin averaged potential (default value),
1 = spin up potential,
2 = spin down potential.


ELSEIF plot_num=3 :
Options for LDOS (plot_num=3):
LDOS is plotted on grid [emin, emax] with spacing delta_e.
emin 
REAL 
Default: 
e_fermi

lower boundary of energy grid (in eV).
Defaults to Fermi energy.

emax 
REAL 
Status: 
OPTIONAL

upper boundary of energy grid (in eV).
Defaults to Fermi energy.

delta_e 
REAL 
Default: 
0.1

Status: 
OPTIONAL

spacing of energy grid (in eV).

degauss_ldos 
REAL 
Default: 
degauss (converted to eV)

Status: 
OPTIONAL

broadening of energy levels for LDOS (in eV).
Defaults to broadening degauss specified for electronic smearing
in pw.x calculation.

use_gauss_ldos 
LOGICAL 
Default: 
.false.

Status: 
OPTIONAL

If .true., gaussian broadening (ngauss=0) is used for LDOS calculation.
Defaults .false., in which case the broadening scheme
of the pw.x calculation will be used.


ELSEIF plot_num=5 :
Options for STM images (plot_num=5):
sample_bias 
REAL 
the bias of the sample (Ry) in stm images


ELSEIF plot_num=7 :
Options for psi^2 (plot_num=7):
kpoint(i), i=1,2 
INTEGER 
Unpolarized and noncollinear case:
kpoint(s) to be plotted
LSDA:
kpoint(s) and spin polarization to be plotted
(spinup and spindown correspond to different kpoints!)
To plot a single kpoint ikpt, specify kpoint=ikpt or kpoint(1)=ikpt
To plot a range of kpoints [imin, imax], specify kpoint(1)=imin and kpoint(2)=imax

kband(i), i=1,2 
INTEGER 
Band(s) to be plotted.
To plot a single band ibnd, specify kband=ibnd or kband(1)=ibnd
To plot a range of bands [imin, imax], specify kband(1)=imin and kband(2)=imax

lsign 
LOGICAL 
if true and k point is Gamma, plot psi^2 sign(psi)

spin_component(i), i=1,2 
INTEGER 
Default: 
0

Status: 
OPTIONAL

Noncollinear case only:
plot the contribution of the given state(s) to the charge
or to the magnetization along the direction(s) indicated
by spin_component:
0 = charge (default),
1 = x,
2 = y,
3 = z.
Ignored in unpolarized or LSDA case
To plot a single component ispin, specify spin_component=ispin or spin_component(1)=ispin
To plot a range of components [imin, imax], specify spin_component(1)=imin and spin_component(2)=imax


ELSEIF plot_num=10 :
Options for ILDOS (plot_num=10):
emin 
REAL 
lower energy boundary (in eV)

emax 
REAL 
upper energy boundary (in eV),
i.e. compute ILDOS from emin to emax

spin_component 
INTEGER 
Default: 
0

for LSDA case only: plot the contribution to ILDOS of
0 = spinup + spindown (default)
1 = spinup only
2 = spindown only


ELSEIF plot_num=13 :
Options for noncollinear magnetization (plot_num=13):
spin_component 
INTEGER 
Default: 
0

0 = absolute value (default value)
1 = x component of the magnetization
2 = y component of the magnetization
3 = z component of the magnetization


ELSEIF plot_num=17 :
Options for reconstructed charge density (plot_num=17):
spin_component 
INTEGER 
Default: 
0

0 = total charge (default value),
1 = spin up charge,
2 = spin down charge.


ELSEIF plot_num=22 :
Options for kinetic energy density (plot_num=22),
LSDA case only:
spin_component 
INTEGER 
Default: 
0

0 = total density (default value),
1 = spin up density,
2 = spin down density.





Namelist: &PLOT

nfile 
INTEGER 
Default: 
1

Status: 
OPTIONAL

the number of data files to read

filepp(i), i=1,nfile 
CHARACTER 
Default: 
filepp(1)=filplot

nfile = 1 : file containing the quantity to be plotted
nfile > 1 : see weight

weight(i), i=1,nfile 
REAL 
Default: 
weight(1)=1.0

weighing factors: assuming that rho(i) is the quantity
read from filepp(i), the quantity that will be plotted is:
weight(1)*rho(1) + weight(2)*rho(2) + weight(3)*rho(3) + ...

BEWARE: atomic coordinates are read from the first file;
if their number is different for different files,
the first file must have the largest number of atoms

iflag 
INTEGER 
0 = 1D plot of the spherical average
1 = 1D plot
2 = 2D plot
3 = 3D plot
4 = 2D polar plot on a sphere

output_format 
INTEGER 
(ignored on 1D plot)
0 = format suitable for gnuplot (1D)
1 = obsolete format no longer supported
2 = format suitable for plotrho (2D)
3 = format suitable for XCRYSDEN (2D or usersupplied 3D region)
4 = obsolete format no longer supported
5 = format suitable for XCRYSDEN (3D, using entire FFT grid)
6 = format as gaussian cube file (3D)
(can be read by many programs)
7 = format suitable for gnuplot (2D) x, y, f(x,y)

fileout 
CHARACTER 
Default: 
standard output

name of the file to which the plot is written

interpolation 
CHARACTER 
Default: 
'fourier'

Type of interpolation:
 'fourier'
 'bspline' :
(EXPERIMENTAL)

IF iflag = 0 or 1 :
the following variables are REQUIRED:
e1(i), i=1,3 
REAL 
3D vector which determines the plotting line (in alat units)

x0(i), i=1,3 
REAL 
3D vector, origin of the line (in alat units)

nx 
INTEGER 
number of points in the line:
rho(i) = rho( x0 + e1 * (i1)/(nx1) ), i=1, nx


ELSEIF iflag = 2 :
the following variables are REQUIRED:
e1(i),
e2(i),
i=1,3 
REAL 
3D vectors which determine the plotting plane (in alat units)
BEWARE: e1 and e2 must be orthogonal

x0(i), i=1,3 
REAL 
3D vector, origin of the plane (in alat units)

nx, ny 
INTEGER 
Number of points in the plane:
rho(i,j) = rho( x0 + e1 * (i1)/(nx1)
+ e2 * (j1)/(ny1) ), i=1,nx ; j=1,ny


ELSEIF iflag = 3 :
the following variables are OPTIONAL:
e1(i),
e2(i),
e3(i),
i=1,3 
REAL 
3D vectors which determine the plotting parallelepiped
(if present, must be orthogonal)
e1, e2, and e3 are in alat units !

x0(i), i=1,3 
REAL 
3D vector, origin of the parallelepiped
x0 is in alat units !

nx, ny, nz 
INTEGER 
Number of points in the parallelepiped:
rho(i,j,k) = rho( x0 + e1 * (i1)/nx
+ e2 * (j1)/ny
+ e3 * (k1)/nz ),
i = 1, nx ; j = 1, ny ; k = 1, nz
 If output_format = 3 (XCRYSDEN), the above variables
are used to determine the grid to plot.
 If output_format = 5 (XCRYSDEN), the above variables
are ignored, the entire FFT grid is written in the
XCRYSDEN format  works for any crystal axis (VERY FAST)
 If e1, e2, e3, x0 are present,
and e1, e2, e3 are parallel to xyz
and parallel to crystal axis, a subset of the FFT
grid that approximately covers the parallelepiped
defined by e1, e2, e3, x0, is
written  untested, might be obsolete
 Otherwise, the required 3D grid is generated from the
Fourier components (may be VERY slow)


ELSEIF iflag = 4 :
the following variables are REQUIRED:
radius 
REAL 
Radius of the sphere (alat units), centered at (0,0,0)

nx, ny 
INTEGER 
Number of points in the polar plane:
phi(i) = 2 pi * (i  1)/(nx1), i=1, nx
theta(j) = pi * (j  1)/(ny1), j=1, ny





