quantum-espresso/PHonon/examples/README

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

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

     poe ph.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 ph.x to calculate phonon
    frequencies at Gamma and X for Si and C in the diamond structure and 
    for fcc-Ni.

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

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

example04:
    This example shows how to use pw.x and ph.x to calculate the
    normal modes of a molecule (CH4) at Gamma

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

example06
    This example shows how to use ph.x to calculate the phonon frequencies
    at Gamma and X and the dispersion for fcc-Pt with spin-orbit interactions.

example07:
    This example tests pw.x and ph.x in several cases that require the 
    noncollinear or the spin-orbit part of the code together with the gga.
    ph.x is used to calculate the phonons at X and Gamma of fcc-Pt with gga,
    and to calculate the phonons at X and Gamma of fcc-Ni to test the magnetic 
    case with gga with or without spin-orbit (experimental stage). 

example08:
   This example tests ph.x together with PAW. 

example09:
    This example illustrates how to use pw.x and ph.x to calculate 
    dynamic polarizability of methane molecules (experimental stage)

example10:
    This example tests pw.x and ph.x for the effective charges and
    dielectric constants with the noncollinear or the spin-orbit part of the
    code (experimental stage).

example11: 
    This example tests pw.x and ph.x for the noncollinear/spin-orbit case 
    and PAW (still experimental).

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

example13:
    Full dispersions for spin-polarized phonons (Ni)

example14:
    This example shows how to use ph.x to calculate the phonon frequencies
    on an arbitrary set of q points. The points can be generated automatically
    along paths or on a bi-dimensional plane.

example15:
    This example shows how to create Infrared and Raman spectra using pw.x, 
    ph.x and dynmat.x

example16:
    Graphite with DFT-D2

example17:
    This example shows how to compute the phonon dispersions of two-dimensional
    materials

example18:
    This example shows how to use pw.x and ph.x to calculate phonon frequencies
    of LiCoO2 with Hubbard U on Co 3d states (experimental stage).

Additional feature-specific examples:

Partial_example
    This example tests the computation of a part of the dynamical matrix.

GRID_example
    This example shows how to use ph.x on a GRID.

Image_example
    This example tests image parallelism of the ph.x.

Recover_example:
    This example tests the recover feature of ph.x.

GRID_recover_example
    This example tests the recover feature with the GRID or the images.