------------------------------------------------------------------------ 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 are read from standard input or from a file and have 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) ======================================================================== NAMELIST: &INPUTPP +-------------------------------------------------------------------- Variable: prefix Type: CHARATER Description: prefix of files saved by program pw.x +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: outdir Type: CHARACTER Description: temporary directory where pw.x files resides +-------------------------------------------------------------------- +-------------------------------------------------------------------- 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 = charge 1 = total potential V_bare + V_H + V_xc 2 = local ionic potential V_bare 3 = local density of states at e_fermi 4 = local density of electronic entropy 5 = STM images 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 = 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 = 19) 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 = Product of the electron density (charge) and the second eigenvalue of the electron-density Hessian matrix +-------------------------------------------------------------------- ________________________________________________________________________ * 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 +-------------------------------------------------------------------- ________________________________________________________________________ * 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======================================================