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

    Program: pp.x / PWscf / Quantum Espresso
    ------------------------------------------------------------------------

    Purpose of pp.x: data analysis and plotting.

    The code performs two steps:
    (1) reads the output file produced by pw.x, extract and calculate
        the desired quantity (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

       +--------------------------------------------------------------------
       Variable:       prefix

       Type:           CHARATER
       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 e_fermi
                               (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 a selected wavefunction 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))
                               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)
       +--------------------------------------------------------------------

       ________________________________________________________________________
       * IF plot_num=0 :

          OPTIONS FOR TOTAL CHARGE (PLOT_NUM=0):

          +--------------------------------------------------------------------
          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=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

          Type:           INTEGER
          Description:    Unpolarized and noncollinear case:   k-point to be plotted
                          LSDA:  k-point and spin polarization to be plotted
                          (spin-up and spin-down correspond to different k-points!)
          +--------------------------------------------------------------------

          +--------------------------------------------------------------------
          Variable:       kband

          Type:           INTEGER
          Description:    band to be plotted
          +--------------------------------------------------------------------

          +--------------------------------------------------------------------
          Variable:       lsign

          Type:           LOGICAL
          Description:    if true and k point is Gamma, plot |psi|^2 sign(psi)
          +--------------------------------------------------------------------

          +--------------------------------------------------------------------
          Variable:       spin_component

          Type:           INTEGER
          Description:    Noncollinear case only:
                          plot the contribution of the given state to the charge
                          or to the magnetization along the direction indicated
                          by spin_component:
                             0 = charge (default),
                             1 = x,
                             2 = y,
                             3 = z.

                          Ignored in unpolarized or LSDA case
          +--------------------------------------------------------------------

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

       ENDIF
       ________________________________________________________________________

    ===END OF NAMELIST======================================================

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

       +--------------------------------------------------------------------
       Variable:       nfile

       Type:           INTEGER
       Default:        1
       Status:         OPTIONAL
       Description:    the number of data files
       +--------------------------------------------------------------------

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

       +--------------------------------------------------------------------
       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" or "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
          +--------------------------------------------------------------------

          +--------------------------------------------------------------------
          Variable:       x0(i), i=1,3

          Type:           REAL
          Description:    3D vector, origin of the line
          +--------------------------------------------------------------------

          !!! x0 and e1 are 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
                          (must be orthogonal)
          +--------------------------------------------------------------------

          +--------------------------------------------------------------------
          Variable:       x0(i), i=1,3

          Type:           REAL
          Description:    3D vector, origin of the plane
          +--------------------------------------------------------------------

          !!! x0, e1, e2 are 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)

                          e1, e2, and 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 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, 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)
          +--------------------------------------------------------------------

       * 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======================================================