------------------------------------------------------------------------
INPUT FILE DESCRIPTION

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


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

   +--------------------------------------------------------------------
   Variable:       prefix
   
   Type:           CHARACTER
   Description:    prefix of files saved by program pw.x
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       outdir
   
   Type:           CHARACTER
   Description:    directory containing the input data, i.e. the same as in pw.x
   Default:        value of the ESPRESSO_TMPDIR environment variable if set;
                   current directory ('./') otherwise
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       filplot
   
   Type:           CHARACTER
   Description:    file "filplot" contains the quantity selected by plot_num
                   (can be saved for further processing)
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       plot_num
   
   Type:           INTEGER
   Description:    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
   +--------------------------------------------------------------------
   
   ________________________________________________________________________
   * IF plot_num = 0 or 9 : 
   
      OPTIONS FOR TOTAL CHARGE (PLOT_NUM=0)
      OR FOR TOTAL MINUS ATOMIC CHARGE (PLOT_NUM=9):
      
      +--------------------------------------------------------------------
      Variable:       spin_component
      
      Type:           INTEGER
      Default:        0
      Description:    0 = total charge (default value),
                      1 = spin up charge,
                      2 = spin down charge.
      +--------------------------------------------------------------------
      
       
   * ELSE IF plot_num=1 : 
   
      OPTIONS FOR TOTAL POTENTIAL (PLOT_NUM=1):
      
      +--------------------------------------------------------------------
      Variable:       spin_component
      
      Type:           INTEGER
      Default:        0
      Description:    0 = spin averaged potential (default value),
                      1 = spin up potential,
                      2 = spin down potential.
      +--------------------------------------------------------------------
      
       
   * ELSE IF plot_num=3 : 
   
      OPTIONS FOR LDOS (PLOT_NUM=3):
      LDOS IS PLOTTED ON GRID [EMIN, EMAX] WITH SPACING DELTA_E.
      
      +--------------------------------------------------------------------
      Variable:       emin
      
      Type:           REAL
      Default:        e_fermi
      Description:    lower boundary of energy grid (in eV).
                      
                      Defaults to Fermi energy.
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       emax
      
      Type:           REAL
      Status:         OPTIONAL
      Description:    upper boundary of energy grid (in eV).
                      
                      Defaults to Fermi energy.
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       delta_e
      
      Type:           REAL
      Default:        0.1
      Status:         OPTIONAL
      Description:    spacing of energy grid (in eV).
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       degauss_ldos
      
      Type:           REAL
      Default:        degauss (converted to eV)
      Status:         OPTIONAL
      Description:    broadening of energy levels for LDOS (in eV).
                      
                      Defaults to broadening degauss specified for electronic smearing
                      in pw.x calculation.
      +--------------------------------------------------------------------
      
       
   * ELSE IF plot_num=5 : 
   
      OPTIONS FOR STM IMAGES (PLOT_NUM=5):
      
      +--------------------------------------------------------------------
      Variable:       sample_bias
      
      Type:           REAL
      Description:    the bias of the sample (Ry) in stm images
      +--------------------------------------------------------------------
      
       
   * ELSE IF plot_num=7 : 
   
      OPTIONS FOR |PSI|^2 (PLOT_NUM=7):
      
      +--------------------------------------------------------------------
      Variable:       kpoint(i), i=1,2
      
      Type:           INTEGER
      Description:    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
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       kband(i), i=1,2
      
      Type:           INTEGER
      Description:    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
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       lsign
      
      Type:           LOGICAL
      Description:    if true and k point is Gamma, plot |psi|^2 sign(psi)
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       spin_component(i), i=1,2
      
      Type:           INTEGER
      Default:        0
      Status:         OPTIONAL
      Description:    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
      +--------------------------------------------------------------------
      
       
   * ELSE IF plot_num=10 : 
   
      OPTIONS FOR ILDOS (PLOT_NUM=10):
      
      +--------------------------------------------------------------------
      Variable:       emin
      
      Type:           REAL
      Description:    lower energy boundary (in eV)
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       emax
      
      Type:           REAL
      Description:    upper energy boundary (in eV),
                      i.e. compute ILDOS from "emin" to "emax"
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       spin_component
      
      Type:           INTEGER
      Default:        0
      Description:    for LSDA case only: plot the contribution to ILDOS of
                      0 = spin-up + spin-down (default)
                      1 = spin-up   only
                      2 = spin-down only
      +--------------------------------------------------------------------
      
       
   * ELSE IF plot_num=13 : 
   
      OPTIONS FOR NONCOLLINEAR MAGNETIZATION (PLOT_NUM=13):
      
      +--------------------------------------------------------------------
      Variable:       spin_component
      
      Type:           INTEGER
      Default:        0
      Description:    0 = absolute value (default value)
                      1 = x component of the magnetization
                      2 = y component of the magnetization
                      3 = z component of the magnetization
      +--------------------------------------------------------------------
      
       
   * ELSE IF plot_num=17 : 
   
      OPTIONS FOR RECONSTRUCTED CHARGE DENSITY (PLOT_NUM=17):
      
      +--------------------------------------------------------------------
      Variable:       spin_component
      
      Type:           INTEGER
      Default:        0
      Description:    0 = total charge (default value),
                      1 = spin up charge,
                      2 = spin down charge.
      +--------------------------------------------------------------------
      
       
   * ELSE IF plot_num=22 : 
   
      OPTIONS FOR KINETIC ENERGY DENSITY (PLOT_NUM=22),
      LSDA CASE ONLY:
      
      +--------------------------------------------------------------------
      Variable:       spin_component
      
      Type:           INTEGER
      Default:        0
      Description:    0 = total density (default value),
                      1 = spin up density,
                      2 = spin down density.
      +--------------------------------------------------------------------
      
       
   ENDIF
   ________________________________________________________________________
   
===END OF NAMELIST======================================================


========================================================================
NAMELIST: &PLOT

   +--------------------------------------------------------------------
   Variable:       nfile
   
   Type:           INTEGER
   Default:        1
   Status:         OPTIONAL
   Description:    the number of data files to read
   +--------------------------------------------------------------------
   
   ///---
      +--------------------------------------------------------------------
      Variable:       filepp(i), i=1,nfile
      
      Type:           CHARACTER
      Default:        filepp(1)=filplot
      Description:    nfile = 1 : file containing the quantity to be plotted
                      nfile > 1 : see "weight"
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       weight(i), i=1,nfile
      
      Type:           REAL
      Default:        weight(1)=1.0
      Description:    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
      
   \\\---
   
   +--------------------------------------------------------------------
   Variable:       iflag
   
   Type:           INTEGER
   Description:    0 = 1D plot of the spherical average
                   1 = 1D plot
                   2 = 2D plot
                   3 = 3D plot
                   4 = 2D polar plot on a sphere
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       output_format
   
   Type:           INTEGER
   Description:    (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)
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       fileout
   
   Type:           CHARACTER
   Default:        standard output
   Description:    name of the file to which the plot is written
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       interpolation
   
   Type:           CHARACTER
   Default:        'fourier'
   Description:   
                   Type of interpolation:
                        'fourier'
    
                   'bspline' :
                        (EXPERIMENTAL)
   +--------------------------------------------------------------------
   
   ________________________________________________________________________
   * IF iflag = 0 or 1 : 
   
      THE FOLLOWING VARIABLES ARE REQUIRED:
      
      +--------------------------------------------------------------------
      Variable:       e1(i), i=1,3
      
      Type:           REAL
      Description:    3D vector which determines the plotting line (in alat units)
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       x0(i), i=1,3
      
      Type:           REAL
      Description:    3D vector, origin of the line (in alat units)
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       nx
      
      Type:           INTEGER
      Description:    number of points in the line:
                      
                      rho(i) = rho( x0 + e1 * (i-1)/(nx-1) ), i=1, nx
      +--------------------------------------------------------------------
      
       
   * ELSE IF iflag = 2 : 
   
      THE FOLLOWING VARIABLES ARE REQUIRED:
      
      +--------------------------------------------------------------------
      Variables:      e1(i), e2(i), i=1,3
      
      Type:           REAL
      Description:    3D vectors which determine the plotting plane (in alat units)
                      
                      BEWARE: @b e1 and @b e2 must be orthogonal
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       x0(i), i=1,3
      
      Type:           REAL
      Description:    3D vector, origin of the plane (in alat units)
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variables:      nx, ny
      
      Type:           INTEGER
      Description:    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
      +--------------------------------------------------------------------
      
       
   * ELSE IF iflag = 3 : 
   
      THE FOLLOWING VARIABLES ARE OPTIONAL:
      
      +--------------------------------------------------------------------
      Variables:      e1(i), e2(i), e3(i), i=1,3
      
      Type:           REAL
      Description:    3D vectors which determine the plotting parallelepiped
                      (if present, must be orthogonal)
                      
                      @ref e1, @ref e2, and @ref e3 are in alat units !
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       x0(i), i=1,3
      
      Type:           REAL
      Description:    3D vector, origin of the parallelepiped
                      
                      "x0" is in alat units !
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variables:      nx, ny, nz
      
      Type:           INTEGER
      Description:    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 @ref output_format = 3 (XCRYSDEN), the above variables
                        are used to determine the grid to plot.
                      
                      - If @ref 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 @ref e1, @ref e2, @ref e3, @ref x0 are present,
                        and @ref e1, @ref e2, @ref e3 are parallel to xyz
                        and parallel to crystal axis, a subset of the FFT
                        grid that approximately covers the parallelepiped
                        defined by @ref e1, @ref e2, @ref e3, @ref x0, is
                        written - untested, might be obsolete
                      
                      - Otherwise, the required 3D grid is generated from the
                        Fourier components (may be VERY slow)
      +--------------------------------------------------------------------
      
       
   * ELSE IF iflag = 4 : 
   
      THE FOLLOWING VARIABLES ARE REQUIRED:
      
      +--------------------------------------------------------------------
      Variable:       radius
      
      Type:           REAL
      Description:    Radius of the sphere (alat units), centered at (0,0,0)
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variables:      nx, ny
      
      Type:           INTEGER
      Description:    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
      +--------------------------------------------------------------------
      
       
   ENDIF
   ________________________________________________________________________
   
===END OF NAMELIST======================================================


This file has been created by helpdoc utility on Sat Dec 18 20:08:46 CET 2021