quantum-espresso/PP/examples/README

These are instructions on how to run the examples for some PostProc
programs included in the Quantum ESPRESSO distribution.
These examples try to exercise all the programs and features
of the PP package.
If you find that any relevant feature isn't being tested,
please contact us (or even better, write and send us a new example).
To run the examples, you should follow this procedure:

1) Edit the "environment_variables" file from the main 
   ESPRESSO directory, setting the following variables as needed:

     BIN_DIR = directory where ESPRESSO executables reside
     PSEUDO_DIR = directory where pseudopotential files reside
     TMP_DIR = directory to be used as temporary storage area

   If you have downloaded the full ESPRESSO distribution, you may set
   BIN_DIR=$TOPDIR/bin and PSEUDO_DIR=$TOPDIR/pseudo, where $TOPDIR is
   the root of the ESPRESSO source tree.

   TMP_DIR must be a directory you have read and write access to, with
   enough available space to host the temporary files produced by the
   example runs, and possibly offering high I/O performance (i.e.,
   don't use an NFS-mounted directory).

2) If you want to test the parallel version of ESPRESSO, you will 
   usually have to specify a driver program (such as "poe" or "mpirun")
   and the number of processors. This can be done by editing PARA_PREFIX
   and PARA_POSTFIX variables (in the "environment_variables" file).
   Parallel executables will be run by a command like this:

     $PARA_PREFIX pp.x $PARA_POSTFIX < file.in > file.out

   For example, if the command line is like this (as for an IBM SP):

     poe pp.x -procs 4 < file.in > file.out

   you should set PARA_PREFIX="poe", PARA_POSTFIX="-procs 4".

   See section "Running on parallel machines" of the user guide for details.
   Furthermore, if your machine does not support interactive use, you
   must run the commands specified below through the batch queueing
   system installed on that machine.  Ask your system administrator
   for instructions.

3) To run a single example, go to the corresponding directory (for
   instance, "example/example01") and execute:

     ./run_example

   This will create a subdirectory "results", containing the input and
   output files generated by the calculation.

   Some examples take only a few seconds to run, while others may
   require several minutes depending on your system.

4) In each example's directory, the "reference" subdirectory contains
   verified output files, that you can check your results against.

   The reference results were generated on a Linux PC with Intel compiler.
   On different architectures the precise numbers could be slightly
   different, in particular if different FFT dimensions are
   automatically selected.  For this reason, a plain "diff" of your
   results against the reference data doesn't work, or at least, it 
   requires human inspection of the results.

-----------------------------------------------------------------------

                   LIST AND CONTENT OF THE EXAMPLES

example01:
    This example shows how to use pw.x and postprocessing codes to
    make a contour plot in the [110] plane of the charge density for
    Si, and to plot the band structure of Si.

example02:
    This example shows how to use pw.x to calculate the DOS of Ni
    and how to plot the Fermi Surface using XCrysDen

example03:
    This example shows a calculation of STM maps.

example04:
    This example shows how to use bands.x to check the band symmetry
    of fcc-Pt with a fully relativistic pseudo-potential including 
    spin-orbit coupling, and to compute the projected DOS.

example05:
    This example shows how to use pmw.x to generate better projectors for
    LDA+U calculation on FeO. Read file README for more details

example06:
    This example calculates the band structure of ferromagnetic bcc-Fe
    in the noncollinear spin-orbit case.

projected_bands_example:
    This example shows how to produce projected ("fat") band plots

dipole_example:
    This example will calculate the water dipole and calculate the work
    function on a Ni slab with a CO molecule adsorbed using the dipole
    correction.

CLS_IS_example, CLS_FS_example
    These examples show how to calculate initial-state (IS) and final-state (FS)
    core-level-shift (CLS) using the core-excited pseudo-potential technique.

WorkFct_example:
    This example shows how to use pw.x, pp.x, and average.x to
    compute the work function of a metal using the slab-supercell
    approximation.  This example is of a 4 layer unrelaxed Al(100) slab
    with 5 equivalent layers of vacuum between the surfaces.

WAN90_example:
    This example shows how to use pw2wannier90.x in conjunction with
    Wannier90 (http://www.wannier.org) to obtain maximally-localised
    Wannier functions (MLWFs) for the valence bands of diamond.

WannierHam_example:
    This example shows how to generate a model Hamiltonian in a
    Wannier functions basis, using pw.x and wannier_ham.x.

MolDos_example:
    This example calculates the projection of the density of states of
    a system, containing a molecule, on the molecular orbitals of the
    molecule (separately computed).

ForceTheorem_example:

    This example shows how to compute the magnetic anisotropy energy (MAE) 
    with the "Force Theorem" method (Phys. Rev. B 90, 205409 (2014), and to
    get its local decomposition over atomic orbitals using projwfc.x.

fermisurf_example:
    This example generate input files for FermiSurfer 
    (http://osdn.jp/projects/fermisurfer/) to display Fermi surfaces with 
    color plots of the magnitude of the Fermi velocity and orbital characters.

BGW_example:
    This example generates output files for BerkeleyGW using the pw2bgw.x
    utility

ACF_example:
    This example tests the ppacf.x utility
    Y. Jiao, E. Schr\"oder, and P. Hyldgaard, Phys. Rev. B 97, 085115 (2018);
    Y. Jiao, E. Schr\"oder, P. Hyldgaard, J. Chem. Phys. 148, 194115 (2018).