quantum-espresso/CPV/examples

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

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

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

   (except for example 04, see 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.

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 cp.x to perform molecular dynamics
    simulation of SiO2.

example02:
    This example shows how to use cp.x to perform molecular dynamics
    simulation of H2O.

example03:
    This example shows how to use cp.x to perform molecular dynamics
    simulation of NH3.

example04:
    This example shows how to use cp.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.

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

example06:
    Additional example of calculation of Wannier functions with cp.x,
    using the Jacobi Rotation algorithm for localizing Wannier functions
    (contributed by IRRMA, Lausanne)

example07:
    This example shows how to use cp.x to perform TPSS metaGGA calculations
    for C4H6

example08:
    This example shows how to perform Born-Oppenheimer molecular dynamics
    with conjugate gradient algorithm for the electronic states and
    ensemble-DFT for treating metallic systems.
    It is a simple Si dimer.

example09:
    This example shows how to use cp.x to perform molecular dynamics
    in the presence of an electric field described through the
    modern theory of the polarization. The example shows how to
    calculate high-frequency and static dielectric constants and 
    Born effective charges.


Additional feature-specific examples:

autopilot-example:
    This example (a water molecule) shows how to use cp.x to perform
    molecular dynamics with variable parameters using AUTOPILOT.

Restart_example:
    This example shows how to use cp.x together with pw.x
    to perform an electronic minimization at Gamma for SiO2.