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.
- Unix, or a Unix-like environment
(a shell and the Make utility): Mac OS-X ok, Windows with
- a working fortran-95 compiler (most "fortran-90" compilers are ok,
"g77" is not)
- a working C compiler ("gcc" is ok)
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
Things that you SHOULD have on your machine for real-life usage:
- working MPI (Message-passing Interface):
parallel compiler ("mpif90" or similar scripts), MPI libraries,
run-time environment ("mpirun" or similar launchers)
OpenMP-capable compiler and autothreading mathematical libraries
(for multi-core CPUs)
- Fast mathematical libraries
- For parallel execution: fast interprocess communication hardware
- 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.
- Download in the chosen directory the package
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)
- 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:
tar -xvf espresso-5.0.2.tar
A directory "espresso-5.0.2/" will be created, containing many files
and other directories.
- 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
- Enter the "espresso-5.0.2/" directory and execute "./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
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
to produce a serial executable. Use
to produce a parallel executable with OpenMP enabled.
- Compile the packages you need. Let us start from PWscf:
"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/":
- Quick test (for "pw.x" executable only) to verify that things look good:
- Compile other packages. "make" with no argument yields a list
of targets, i.e., packages to be compiled. If you want to compile
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
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:
- Fast Fourier Transform
- matrix-matrix and matrix-vector multiplications (BLAS)
- solution of linear systems, diagonalizations (LAPACK)
Most vendors provide highly optimized BLAS and LAPACK replacements
and FFT libraries (different from FFTW)
- machine-optimized BLAS (VERY important) and LAPACK libraries (important)
- for some architectures (in particular IBM SP):
machine-optimized FFT library
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:
- essl for IBM RISC and SP machines
- MKL for Intel/AMD PCs
- ACML for AMD (e.g. Opterons) PCs
- SCSL for SGI Altix
- sunperf for Sun workstations and parallel machines
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.
- essl for IBM SP machines
- MKL for Intel CPUs
- ACML for AMD CPUs
- ASL for NEC-SX machines
- SCSL for SGI Altix
- sunperf for Sun workstations and parallel machines
"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
depending upon whether you are linking Intel version of MPI or OpenMPI.
Most installation problems falls into one of the following categories:
- 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
- fortran-95 compiler unable to compile Quantum ESPRESSO:
"internal compiler error" or some other strange errors occur.
- 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
- "configure" unable to locate some external libraries
you know are there.
- 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")
- Parallel Machines (especially PC clusters):
In all cases mentioned above, see also the documentation on:
- 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
When everything else fails...