quantum-espresso/examples

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.pz-vbc.UPF, As.pz-bhs.UPF, C.pz-rrkjus.UPF, Cu.pz-d-rrkjus.UPF,
     Fe.pz-nd-rrkjus.UPF, H.blyp-vbc.UPF, H.pz-vbc.UPF, N.blyp-mt.UPF,
     Ni.pbe-nd-rrkjus.UPF, Ni.pz-nd-rrkjus.UPF, 
     O.blyp-mt.UPF, O.pbe-rrkjus.UPF, O.pz-van_ak.UPF,
     Pb.pz-d-van.UPF, Pt.rel-pz-n-rrkjus.UPF, Ti.pz-sp-van_ak.UPF,
     Si.pz-vbc.UPF,Si.pbe-rrkjus.UPF, C.tpss-mt.UPF, H.tpss-mt.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

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

   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
    and how to plot the Fermi Surface using XCrysDen

example09:
    This example shows how to use pw.x and phcg.x to calculate the
    normal modes of a molecule (SiH4) at Gamma. It shows also the
    use of ph.x for molecules (CH4) 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 and ph.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. pwcond.x is used to calculate the 
    complex bands including spin-orbit coupling. ph.x is used to calculate
    the phonon frequencies at Gamma and X of fcc-Pt.

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

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

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

example28:
    This example shows how to use pw.x and cp.x to run a meta-dynamics
    simulation to explore different conformations of the Si4H6 molecule.

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

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

example31:
    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 silicon.

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

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

example34:
    This example illustrates how to use vdw.x to calculate 
    dynamic polarizability of methane molecules (experimental stage).

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



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.

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.

GIPAW_example:
    This example shows how to use gipaw.x to calculate the magnetic susceptibility
    and NMR chemical shift of fcc Si, diamond, and of two molecules: CH4 and C2H4.

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

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

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.

XSpectra_example:
    This example tests K-edge X-ray absorption spectra calculation
    for diamond and NiO.

Note: additional documentation specific to pseudopotential generation,
including examples, is available in the ../atomic_doc/ directory.