Quantum-ESPRESSO tutorial: Installation

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:

Unix, or a Unix-like environment (a shell and the Make utility): Mac OS-X ok, Windows with "cygwin" ok
a working fortran-95 compiler (most "fortran-90" compilers are ok, "g77" is not)
a working C compiler ("gcc" is ok)
for parallel execution: MPI (Message-passing Interface) libraries and (important!) working "mpif90" scripts for parallel compilation

Supported hardware/software configurations: Quantum-ESPRESSO works or may work on the following hardware/software combinations:

all PCs (Intel/AMD) and PC clusters, including 64-bit CPUs (Itanium, Opteron), with most commercial (Intel, PGI, Pathscale,...) and free (g95, gfortran) compilers
PowerPC and Intel Macintosh with OS-X
most workstations: SGI with MIPS CPUs, SUN with SPARC CPUs, HP/Compaq (formerly DEC) with Alpha CPUs (both Linux and Unix), IBM PowerPC RISCs with AIX
most parallel machines: IBM SP and BG, SGI Origin and Altix, Cray XT
a few vector machines: NEC, Hitachi

Libraries: Quantum-ESPRESSO uses and provides a copy of the following external libraries:

BLAS (Basic Linear Algebra Subroutines): http://www.netlib.org/blas
LAPACK (Linear Algebra Package): http://www.netlib.org/lapack
FFTW (Fast Fourier-Transform package): http://www.fftw.org

Things that you SHOULD have on your machine for real-life usage:

Fast mathematical libraries
For parallel execution: fast interprocess communication hardware and software

Basic Installation

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, your home directory is perfectly fine (it is local to each PC) and you can install there, but BEWARE: each PC has a different home directory.
Download in the chosen directory the package espresso-4.0.4.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)
Uncompress and unpackage the file:
```
        tar -zxvf espresso-4.0.4.tar.gz
	
```
Some machines may not support the "z" flag (meaning "uncompress files compressed by gzip"). In this case:
```
        gunzip espresso-4.0.4.tar.gz
        tar -xvf espresso-4.0.4.tar
	
```
A directory "espresso-4.0.4/" will be created, containing many files and other directories. In the following this directory will be referred to as $espresso_dir.
Enter the "espresso-4.0.4/" directory and execute "./configure":
```
        cd espresso-4.0.4/
        ./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 1: Intel compiler will not be found if you did not initialize the needed environment variables (i.e. execute the initialization script)
BEWARE 2: if you have a parallel compiler 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 (recommanded).
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
        
```
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:

Fast Fourier Transform
matrix-matrix and matrix-vector multiplications (BLAS)
solution of linear systems, diagonalizations (LAPACK)

If you want a fast executable, you MUST provide:

machine-optimized BLAS (VERY important) and LAPACK libraries (important)
for some architectures (in particular IBM SP): machine-optimized FFT library

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:

essl for IBM RISC and SP machines
MKL for Intel/AMD PCs
ACML for AMD (e.g. Opterons) PCs
complib.sgimath for SGI Origin
SCSL for SGI Altix
sunperf for Sun workstations and parallel machines
cxml for HP-Compaq workstations and parallel machines with Alpha CPU and Unix (not Linux)

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:

essl for IBM RISC and SP machines
ACML for AMD Opteron machines (not yet in 4.0.4 version)
complib.sgimath for SGI Origin
SCSL for SGI Altix
sunperf for Sun workstations and parallel machines

and for a few more exotic architectures. 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:

compile the interface to the fortran v.3 of FFTW, provided by Intel
in file "make.sys"
- add "-D__FFTW3" to DFLAGS
- remove "-D__FTTW" and/or "-D__USE_INTERNAL_FFTW"
- add link to the MKL interface before the link to mkl (e.g. in BLAS_LIBS; leave FFT_LIBS empty)
compile quantum-ESPRESSO; if you already compiled it, "make clean" first, or else remove all Fortran and C files containing references to __FFTW, __FFTW3, __USE_INTERNAL_FFTW

Problematic cases

Most installation problems falls into one of the following categories:

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 only recent versions work)
- buy a commercial compiler (Portland, Lahey, Absoft, Pathscale)
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
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, or splitting routines into pieces, or simply moving around some lines, will do the job
"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")
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...

...read the manual and the documentation in directory Doc/
...and/or on the Wiki at http://www.quantum-espresso.org)
search the pw_forum mailing list (follow the link in the Tools section of http://www.quantum-espresso.org)
post to the pw_forum mailing list (subscribe by following the link in the Tools section of http://www.quantum-espresso.org)