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.
  2. Download in the chosen directory the package espresso-5.0.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-5.0.2.tar.gz
    	
    Some machines may not support the "z" flag (meaning "uncompress files compressed by gzip"). In this case:
            gunzip espresso-5.0.2.tar.gz
            tar -xvf espresso-5.0.2.tar
    	
    A directory "espresso-5.0.2/" will be created, containing many files and other directories. .
  4. Execute initialization steps, if needed. For instance, in order to enable the usage of Intel compiler and MKL libraries, you should set a number of variables; for parallel execution, you should add a parallel compiler to your path. How to do this depends on the specific machine. Sometimes one has to use the command "module", as in the following example:
             module load intel/12.0
             module load mkl/12.0
             
    .
  5. Enter the "espresso-5.0.2/" directory and execute "./configure":
            cd espresso-5.0.2/
            ./configure
            
    "configure" is a wrapper, calling the "install/configure" script, that tries to guess your machine and to choose compilation and linking options accordingly. "install/configure" is generated from "install/configure.ac" using the complex but well-known Unix utility "autoconf". The result of "configure" is a file called "make.sys" containing the compilation and linking options. You may want to have a look at it to verify what "configure" thinks about your system. Several options to "configure" may (and sometimes, have to) be specified (see below).
    • If you get a message "architecture xxx not recognized", specify option "ARCH=...", such as e.g. (for a BlueGene machine):
              ./configure ARCH=ppc64-bg
              
    • If "configure" selects a compiler you don't like (or one that doesn't like Quantum ESPRESSO) specify option "F90=..." or "MPIF90=...", e.g.:
              ./configure F90=gfortran
              
    If everything is fine 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 you have a parallel compiler in you path, "configure" will choose it. If the parallel and serial compilers do not match, you may run into trouble (check for the presence of "WARNING" in the output of "configure"!). You can use "configure" optional variables F90, MPIF90 to select the compiler you want, and in some cases, environment variables like OMPI_MPIFC to select the compiler used in parallel compilation. Use
            ./configure --disable-parallel
            
    to produce a serial executable. Use
            ./configure --enable-openmp 
            
    to produce a parallel executable with OpenMP enabled.
  6. Compile the packages you need. Let us start from PWscf:
    	make pw 
            
    "make" is another complex but standard unix utility 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 are generated by "configure". If everything goes well, executables will appear in "bin/":
    	ls bin/*.x
            
  7. Quick test (for "pw.x" executable only) to verify that things look good:
    	cd PW/tests
            ./check-pw.x.j
            
  8. Compile other packages. "make" with no argument yields a list of targets, i.e., packages to be compiled. If you want to compile everything:
    	make all 
            
    Packages that are not contained in the base tarball will be download from the net. Beware: this will work only if you have direct access to the internet, and working "wget" or "curl" commands. If not, you will need to download the required packages from http://www.quantum-espresso.org and to put them into "archive/". Then you can do "make" again. .

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: You may want to check for the presence of preprocessing options "-D" in the definition of DFLAGS in file "make.sys". For recent MKL versions, it is sufficient to have "-D__FFTW3" in DFLAGS, to have MKL properly linked, and nothing in FFTLIBS. 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 good. Only ESSL on IBM machines beats them by a large margin.

ScaLAPACK

"configure" by default tries to compile support for ScaLAPACK (check for "-D__SCALAPACK in DFLAGS, file "make.sys"). For machines with recent Intel MKL libraries, you may need to specify
     ./configure --with-scalapack=intelmpi
     
or
     ./configure --with-scalapack=openmpi
     
depending upon whether you are linking Intel version of MPI or OpenMPI.

Problematic cases

Most installation problems falls into one of the following categories:

  1. fortran-95 compiler not installed or not working
    • buy a commercial compiler: Intel, PGI, Lahey, Pathscale are supported; Absoft may or may not work. The Linux version of the Intel compiler is free for personal usage.
    • download the GNU gfortran compiler (recent versions work quite well) or the g95 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:
    • bug your system manager until he/she sets up properly the libraries, or puts them in a sane location
    • 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. Solution:
      1) bug your system manager until he/she sets up properly the script
    • you manage to compile but the executable yields strange errors in parallel execution. Solution:
      bug your system manager until he/she install a working combination of libraries and of compiler
    In all cases mentioned above, see also the documentation on: http://www.quantum-espresso.org

When everything else fails...