These are instructions on how to run some or all of the examples
contained within the "examples" directory of the ESPRESSO
distribution (the one where this file should be).  Those examples try
to exercise all the programs and features of the ESPRESSO package: for
details, see the "README" file in each example's directory.
If you find that any relevant feature isn't being tested, please
contact us (or even better, write and send us a new example
yourself!).

If you haven't downloaded the full ESPRESSO distribution and don't
have the examples, you can get them from the Test and Examples Page of
the ESPRESSO web site (http://www.pwscf.org/tests.htm).  The necessary
pseudopotentials are included.

To run the examples, you should follow this procedure:

1) Go to the "examples" directory and edit the "environment_variables"
   file, 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.

   The PSEUDO_DIR directory must contain the following files:

     Al.vbc.UPF, As.gon.UPF, C.pz-rrkjus.UPF, Cu.pz-d-rrkjus.UPF,
     Fe.pz-nd-rrkjus.UPF, H.fpmd.UPF, H.vbc.UPF, N.BLYP.UPF,
     Ni.pbe-nd-rrkjus.UPF, NiUS.RRKJ3.UPF, O.BLYP.UPF,
     O.LDA.US.RRKJ3.UPF, O.pbe-rrkjus.UPF, O.vdb.UPF, OPBE_nc.UPF,
     Pb.vdb.UPF, Ptrel.RRKJ3.UPF, Si.vbc.UPF, SiPBE_nc.UPF, Ti.vdb.UPF

   If any of these are missing, you may not be able to run some of the
   examples.  You can download them from the Pseudopotentials Page of
   the ESPRESSO web site (http://www.pwscf.org/pseudo.htm).

   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 have compiled the parallel version of ESPRESSO (that is the
   default), you'll usually have to specify a driver program (such as
   "poe" or "mpiexec") and the number of processors: see the section
   ``Running on parallel machines'' of the ESPRESSO manual for
   details.

   In order to do that, edit again the "environment_variables" file
   and set the PARA_PREFIX and PARA_POSTFIX variables as needed.
   Parallel executables will be run by a command like this:

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

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

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

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

   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

   (for examples 21 and 26, see their description below)
   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.

   To run all the examples in one go, execute:

     ./run_all_examples

   from the "examples" directory.  On a single-processor machine, this
   typically takes one to three hours.

   The "make_clean" script cleans the examples tree, by removing all
   the "results" subdirectories.  However, if additional
   subdirectories have been created, they aren't deleted.

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.

   Instead, you can run the "check_example" script in the "examples"
   directory:

     ./check_example example_dir

   where "example_dir" is the directory of the example that you want
   to check (e.g., "./check_example example01").  You can specify
   multiple directories.

   Note: at the moment "check_example" is in early development and
   (should be) guaranteed to work only on examples 01 to 04.

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

                   LIST AND CONTENT OF THE EXAMPLES

example01:
    This example shows how to use pw.x to calculate the total energy
    and the band structure of four simple systems: Si, Al, Cu, Ni.

example02:
    This example shows how to use pw.x and ph.x to calculate phonon
    frequencies at Gamma and X for Si and C in the diamond structure and 
    for fcc-Ni.

example03:
    This example shows how to use pw.x to compute the equilibrium
    geometry of a simple molecule, CO, and of an Al (001) slab.
    In the latter case the relaxation is performed in two ways:
    1) using the quasi-Newton BFGS algorithm
    2) using a damped dynamics algorithm.

example04:
    This example shows how to use pw.x to perform molecular dynamics
    for 2- and 8-atom cells of Si starting with compressed bonds along
    (111).

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

example06:
    This example shows how to calculate interatomic force constants in
    real space for AlAs in zincblende structure.

example07:
    This example shows how to calculate electron-phonon interaction
    coefficients at X for fcc Al.

example08:
    This example shows how to use pw.x to calculate the DOS of Ni.

example09:
    This example shows how to use pw.x and phcg.x to calculate the
    normal modes of a molecule (SiH4) at Gamma.

example10:
    This example shows how to calculate the polarization via Berry
    Phase in PBTiO3 (contributed by the Vanderbilt Group in Rutgers
    University).

example11:
    This example shows how to calculate the total energy of an
    isolated atom in a supercell with fixed occupations.
    Two examples: LDA energy of Al and sigma-GGA energy of O.

example12:
    This example shows how to use pw.x and pwcond.x to calculate the
    complex bands and the transmission coefficient of an open quantum
    system.

example13:
    This example shows how to use pw.x to calculate the total energy
    and the band structure of four simple systems in the non-collinear
    case: Fe, Cu, Ni, O.

example14:
    This example shows how to use pw.x, ph.x and d3.x to calculate the
    third-order expansion coefficients of the total energy of Si.

example15:
    This example shows how to use pw.x, ph.x, and ram.x to calculate
    the Raman tensor for AlAs.

example16:
    This example shows a calculation of STM maps.

example17:
    This example shows how to use pw.x to calculate the minimum energy
    path (MEP) in the collinear proton transfer reaction H2+H => H+H2.

example18:
    This example shows how to use cp.x to perform molecular dynamics
    simulation of SiO2.

example19:
    This example shows how to use fpmd.x to perform molecular dynamics
    simulation of H2O.

example20:
    This example shows how to use fpmd.x to perform molecular dynamics
    simulation of NH3.

example21:
    This example shows how to use fpmd.x to perform molecular dynamics
    simulation of medium to large systems.
    This example consists in calculations with 32, 64, 128, 256 water
    molecules and takes a long time to execute. To run a calculation
    with up to N molecules, use:
       ./run_example N
    Note that "./run_example" alone does nothing.

example22:
    This example shows how to use pw.x to calculate the total energy
    and the band structure of fcc-Pt with a fully relativistic US-PP
    which includes spin-orbit effects.

example23:
    This example shows how to use cp.x to calculate Wannier functions
    and to perform dynamics with an external electric field.
    (contributed by Manu Sharma)

example24:
    This example shows how to use efg.x to calculate the electric field 
    gradient, and to obtain the quadrupolar parameters of an NMR experiment.
    The solid in example is quartz. 

example25:
    This example shows how to use pw.x to perform LDA+U calculations.

example26:
    This example shows how to use cp.x to do String method (SMD) to find
    the minimum energy path (MEP) (contributed by Yosuke Kanai).
    This example consists in 7 calculations and takes a long time.
    In order to run calculations up to the N-th, use:
       ./run_example N
    Note that "./run_example" alone does nothing.