Installing the Quantum ESPRESSO distribution

How to get the distribution, how to install it, i.e. produce the executables; what you need for a succesful installation, and what to do if the installation is NOT successful!

Requirements for Quantum ESPRESSO installation

Things that you MUST have on your machine: All hardware is supported, as long as it has what is listed above.
In order to run in parallel, you MUST have at least one of the following: Libraries: Quantum ESPRESSO uses and provides a copy of the following external libraries: Things that you SHOULD have on your machine for real-life usage:

Basic Installation

  1. Choose and create a directory where to install Quantum ESPRESSO. It should be on a file system that
    • is local to the PC you are using: sometimes the home directory in a PC cluster is accessed via the network (NFS). Moving large amount of data via the network MUST BE AVOIDED.
    • has enough disk space and a large enough disk quota: sometimes the home directory is small, or has a quota enforced. You will need a few tens of Mb just to compiler the distribution.
    In this workshop, the home directory should be OK.
  2. Download in the chosen directory the package espresso-4.2.tar.gz.
    The suffix ".gz" means "compressed by gzip" (a free utility found on most Unix machines).
    The suffix ".tar" means "archived by tar" (the standard Unix command for archiving and retrieving files)
  3. Uncompress and unpackage the file: 
            tar -zxvf espresso-4.2.tar.gz
    Some machines may not support the "z" flag (meaning "uncompress files compressed by gzip"). In this case: 
            gunzip espresso-4.2.tar.gz
        tar -xvf espresso-4.2.tar
    A directory "espresso-4.2/" will be created, containing many files and other directories. In the following this directory will be referred to as $espresso_dir.
  4. In order to include also tests, examples and the pseudopotentials needed to run them, download in the same directory the file espresso-4.2-examples.tar.gz.
    Uncompress and unpackage the file: 
            tar -zxvf espresso-4.2-examples.tar.gz
  5. Depending on the machine configuration you may need to execute initialization steps. In order to enable the usage of a particular Intel compiler or MKL libraries: 
             module load intel-cc/10.1.015
         module load intel-fc/10.1.015
         module load intel-mkl/10.0.1.014
    or if you want to compile for parallel execution: 
             module load openmpi/1.2.6_intel-10.1.015
    In this workshop the default definition should work fine for a serial compilation.
  6. Enter the "espresso-4.2/" directory and execute "./configure": 
            cd espresso-4.2/
        ./configure
    "configure" is a rather complex utility that tries to guess your machine and to choose compilation and linking options accordingly. If everything is ok you should get a bunch of (mostly obscure and irrelevant) messages but no error. Read the last lines: you may need to understand them if something goes wrong at compilation stage, or if you need to boost performances.
    BEWARE: if a parallel compiler is defined in you path, "configure" will choose it. If the parallel and serial compilers do not match, you will run into trouble (check for the presence of "WARNING" in the output of "configure"!). Use 
            ./configure --disable-parallel
    to produce a serial executable.
  7. Compile the package: 
    	make all
    "make" is another rather complex unix utilities that compiles what is needed in the way it is needed and in the order in which is needed (in Fortran-90 you need to compile modules before programs that use them, for instance). The configuration files for "make" are either coming with the package or automatically generated by "configure". If everything goes well, there will be a bunch of executables in "bin/": 
    	ls bin/*.x
  8. Quick test (for "pw.x" executable only) to verify that things look good: 
    	cd tests
        ./check-pw.x.j

Requirements for installation of a FAST executable

Most of the CPU time in a typical run is spent in: If you want a fast executable, you MUST provide: Most vendors provide highly optimized BLAS and LAPACK replacements and FFT libraries (different from FFTW)

Machine-optimized libraries: BLAS, LAPACK

The "configure" scripts can recognize and use the following architecture-specific replacements for BLAS and LAPACK: If none of these is available, you should try the ATLAS (Automatically Tuned Linear Algebra Subroutines) library: http://math-atlas.sourceforge.net

Machine-optimized libraries: FFT

Quantum ESPRESSO can use the following architecture-specific mathematical libraries instead of FFTW: If none of the above is available, a precompiled FFTW v.3 library or the built-in FFTW library contained in the distribution will be fine. Their performances are quite decent. Only ESSL on IBM machines beats them by a large margin.

FFT from MKL libraries

You can use the FFT's contained in Intel MKL v.8 and later. This requires the following steps:

Problematic cases

Most installation problems falls into one of the following categories:

  1. fortran-95 compiler not installed or not working
    For Intel/AMD PC's, including 64-bit new CPU's:
    • download or buy the Intel compiler (Linux version free for academic use)
    • download the free g95 compiler (quite stable) or the GNU gfortran compiler (produces faster executables than g95 but not all of them work)
    • buy a commercial compiler (PGI, Lahey, Pathscale supported, Absoft unknown)
    For all other machines:
    • try the free g95 or GNU gfortran compiler (they are designed to be portable and in principle should work on any architecture)
    • buy a commercial compiler
  2. fortran-95 compiler unable to compile Quantum ESPRESSO: "internal compiler error" or some other strange errors occur. Possible solutions:
    • upgrade to the latest available compiler version, or install the patches provided by the vendor (if any)
    • install and try a different compiler
    • try to figure out what to do: sometimes lowering the optimization level of a specific routine, or splitting a routine into pieces, or simply moving around some lines, will do the job
  3. "configure" unable to locate some external libraries you know are there. Possible solutions:
    1) bug your system manager until he/she sets up properly the libraries, or puts them in a sane location
    2) manually provide the correct location of libraries (you will have to use "configure" options, or to edit file "make.sys")
  4. Parallel Machines (especially PC clusters):
    • configure says that there is a mismatch between the serial and parallel compiler. Possible solution: 1) use "./configure F90=..." of "MPIF90=..." to force the choice of the correct compiler
      2) modify your $PATH so that "configure" finds the good combination of serial and parallel compilers
    • mpif90 doesn't work. Possible solution:
      1) bug your system manager until he/she sets up properly the script
      2) provide the correct location of MPI libraries and include files to the ordinary f90 compiler (you will have to set run "./configure" with appropriate options, or to edit file "make.sys")
    • you manage to compile but the executable yields strange errors in parallel execution. Possible solution:
      bug your system manager until he/she install a working combination of libraries and of compiler
    In all the above cases, see also the Wiki on http://www.quantum-espresso.org

When everything else fails...