# Input File Description

## Program: pp.x / PWscf / Quantum ESPRESSO (version: 7.2)

> ### 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

[Back to Top]

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

[Back to Top]

filplot | CHARACTER

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

[Back to Top]

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.

>        22 = kinetic energy density (for meta-GGA and XDM only)

>       123 = DORI: density overlap regions indicator
>             (doi: 10.1021/ct500490b) Implemented by D. Yang & Q.Liu

[Back to Top]

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.

> [Back to Top]

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.

> [Back to Top]

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.

> [Back to Top]

> emax | REAL
> Status: | OPTIONAL

> >     upper boundary of energy grid (in eV).

> >     Defaults to Fermi energy.

> [Back to Top]

> delta_e | REAL
> Default: | 0.1
> Status: | OPTIONAL

> >     spacing of energy grid (in eV).

> [Back to Top]

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

> [Back to Top]

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

> [Back to Top]

ELSEIF `plot_num=5 :`

> Options for STM images (plot_num=5):

> sample_bias | REAL

> >     the bias of the sample (Ry) in stm images

> [Back to Top]

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

> [Back to Top]

> 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

> [Back to Top]

> lsign | LOGICAL

> >     if true and k point is Gamma, plot |psi|^2 sign(psi)

> [Back to Top]

> 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

> [Back to Top]

ELSEIF `plot_num=10 :`

> Options for ILDOS (plot_num=10):

> emin | REAL

> >     lower energy boundary (in eV)

> [Back to Top]

> emax | REAL

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

> [Back to Top]

> 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

> [Back to Top]

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

> [Back to Top]

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.

> [Back to Top]

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.

> [Back to Top]

## Namelist: &PLOT

nfile | INTEGER
Default: | 1
Status: | OPTIONAL

>     the number of data files to read

[Back to Top]

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

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

[Back to Top]

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

[Back to Top]

    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

[Back to Top]

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 user-supplied 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)

[Back to Top]

fileout | CHARACTER
Default: | standard output

>     name of the file to which the plot is written

[Back to Top]

interpolation | CHARACTER
Default: | 'fourier'

>     Type of interpolation:

> `'fourier'`

> `'bspline' :`

>        (EXPERIMENTAL)

[Back to Top]

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)

> [Back to Top]

> x0(i), i=1,3 | REAL

> >     3D vector, origin of the line (in alat units)

> [Back to Top]

> nx | INTEGER

> >     number of points in the line:

> >     rho(i) = rho( x0 + e1 * (i-1)/(nx-1) ), i=1, nx

> [Back to Top]

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

> [Back to Top]

> x0(i), i=1,3 | REAL

> >     3D vector, origin of the plane (in alat units)

> [Back to Top]

> 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

> [Back to Top]

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 !

> [Back to Top]

> x0(i), i=1,3 | REAL

> >     3D vector, origin of the parallelepiped

> >     x0 is in alat units !

> [Back to Top]

> 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 - untested, might be obsolete

> >     - Otherwise, the required 3D grid is generated from the
> >       Fourier components (may be VERY slow)

> [Back to Top]

ELSEIF `iflag = 4 :`

> the following variables are REQUIRED:

> radius | REAL

> >     Radius of the sphere (alat units), centered at (0,0,0)

> [Back to Top]

> 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

> [Back to Top]

This file has been created by helpdoc utility on Sat Mar 18 15:50:16 CET 2023.