Run examples

As a final check that compilation was successful, you may want to run some or all of the examples contained within the examples directory of the Quantum-ESPRESSO distribution. Those examples try to exercise all the programs and features of the Quantum-ESPRESSO package. A list of examples and of what each example does is contained in examples/README. 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 Quantum-ESPRESSO distribution and don't have the examples, you can get them from the Test and Examples Page of the Quantum-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 Quantum-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 Quantum-ESPRESSO distribution, you may set BIN_DIR=$TOPDIR/bin and PSEUDO_DIR=$TOPDIR/pseudo, where $TOPDIR is the root of the Quantum-ESPRESSO source tree.

   In order to be able to run all the examples, 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 can download them (and many others) from the Pseudopotentials Page of the Quantum-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 Quantum-ESPRESSO (this is the default if parallel libraries are detected), you will usually have to specify a driver program (such as poe or mpiexec) and the number of processors: read section , ``Running on parallel machines'' 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
   

   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. They were generated on a Linux PC using the 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.