Input File Description

Program: pp.x / PWscf / Quantum Espresso (version: 6.2)

TABLE OF CONTENTS

INTRODUCTION

&INPUTPP

prefix | outdir | filplot | plot_num | spin_component | spin_component | emin | emax | delta_e | degauss_ldos | sample_bias | kpoint | kband | lsign | spin_component | emin | emax | 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.
   

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 norm-conserving 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 = all-electron valence charge density
        can be performed for PAW calculations only
        requires a very dense real-space 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
        non-covalent interactions (see also plot_num = 20)

   20 = Product of the electron density (charge) and the second
        eigenvalue of the electron-density Hessian matrix;
        used to colorize the RDG plot (plot_num = 19)

   21 = all-electron charge density (valence+core).
        For PAW calculations only; requires a very dense real-space grid.
         
IF plot_num=0 :

Options for total charge (plot_num=0):

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).

If not specified, LDOS is computed just for energy emin
               
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.
               
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:
        k-point(s) to be plotted
LSDA:
        k-point(s) and spin polarization to be plotted
        (spin-up and spin-down correspond to different k-points!)

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 = spin-up + spin-down (default)
1 = spin-up   only
2 = spin-down 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.
               

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  = format suitable for contour.x (2D)

2  = format suitable for plotrho   (2D)

3  = format suitable for XCRYSDEN  (2D or user-supplied 3D region)

4  = format suitable for gOpenMol  (3D)
     (formatted: convert to unformatted *.plt)

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 * (i-1)/(nx-1) ), 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 * (i-1)/(nx-1)
                + e2 * (j-1)/(ny-1) ), 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 * (i-1)/nx
                  + e2 * (j-1)/ny
                  + e3 * (k-1)/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 (presently only
  if output_format = 4, i.e. gopenmol format) - works only
  if the crystal axis are parallel to xyz

- 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)/(nx-1), i=1, nx
theta(j) =   pi * (j - 1)/(ny-1), j=1, ny
               
This file has been created by helpdoc utility on Mon Oct 23 19:37:11 CEST 2017.