These are instructions on how to run the examples for PW package.
These examples try to exercise all the programs and features
of the PW 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 pw.x $PARA_POSTFIX < file.in > file.out

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

     poe pw.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

For each example, more detailed information is provided by the README file
contained in the corresponding directory.

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

example03:
    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).

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

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

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

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

example08:
    This example shows how to use pw.x to calculate the total energy of FeO
    using LDA+U approximation.

example09:
    This example shows how to use pw.x to perform TPSS metaGGA calculations
    for C4H6

example10:
    This example shows how to use pw.x to perform electronic structure
    calculations in the presence of a finite electric field described
    through the modern theory of the polarization. The example shows how to
    calculate the dielectric constant of Si and the effective charges of AlAs.

example11:
    This example tests pw.x with PAW in the noncollinear, spin-orbit case.
    It calculates the band structure of ferromagnetic bcc-Fe.

example12:
    This example tests pw.x for the noncollinear/spin-orbit case with
    DFT+U and Ultrasoft pseudopotentials.

example13:
   This example shows how to use pw.x to calculate the total energy
   of LiCoO2 using DFT+U+V with ultrasoft pseudopotentials.

Additional feature-specific examples:


EXX_example:
    Use experimental implementation of Hybrid Functional to compute
    total energy of Silicon using different values for nq and for
    calculation of binding energy of o2,co,n2 from calculations in a
    12 au cubic box and gamma sampling.

ESM_example:
    This example shows how to use the Effective Screening Medium Method (ESM)
    in pw.x to calculate the total energy, charge density, force, and
    potential of a polarized or charged medium. Calculations are for a water
    molecule and an Al(111) electrode.

VCSexample:
    This example shows how to use pw.x to optimize crystal structures at two
    pressures for As.

cluster_example:
    This example shows how to use pw.x to calculate propeties of
    isolated systems decoupling periodic images by using
    Martyna-Tuckerman approach with truncated coulomb interaction.

vdwDF_example:
    This example shows how to use the vdw-DF functional in pw.x.