Keywords: user_guide

Next: 2.9 Cray machines Up: 2 Installation Previous: 2.7 Running tests and Contents
Subsections

- 2.8.1 All architectures
- 2.8.2 Linux PC
  - 2.8.2.1 Linux PCs with gfortran
  - 2.8.2.2 Linux PCs with Intel compiler (ifort)
  - 2.8.2.3 Linux PCs with MKL libraries
  - 2.8.2.4 Linux PCs with AMD processors
- 2.8.3 Linux PC clusters with MPI
- 2.8.4 Microsoft Windows
- 2.8.5 Mac OS

## 2.8 Installation tricks and problems

### 2.8.1 All architectures

- Working Fortran and C compilers, compliant with F2003 and C89 standards (see Sec.2.2) respectively, are needed in order to compile QUANTUM ESPRESSO. Most recent Fortran compilers will do the job.

  C and Fortran compilers must be in your PATH. If `configure` says that you have no working compiler, well, you have no working compiler, at least not in your PATH, and not among those recognized by `configure`.

- If you get Compiler Internal Error or similar messages: your compiler version is buggy. Try to lower the optimization level, or to remove optimization just for the routine that has problems. If it doesn't work, or if you experience weird problems at run time, try to install patches for your version of the compiler (most vendors release at least a few patches for free), or to upgrade to a more recent compiler version.
- If you get error messages at the loading phase that look like file XYZ.o: unknown / not recognized/ invalid / wrong file type / file format / module version, one of the following things have happened:
  1. you have leftover object files from a compilation with another compiler: run `make clean` and recompile.
  2. `make` did not stop at the first compilation error (it may happen in some software configurations). Remove the file *.o that triggers the error message, recompile, look for a compilation error.
  If many symbols are missing in the loading phase: you did not specify the location of all needed libraries (LAPACK, BLAS, FFTW, machine-specific optimized libraries), in the needed order. Note that QUANTUM ESPRESSO is self-contained (with the exception of MPI libraries for parallel compilation): if system libraries are missing, the problem is in your compiler/library combination or in their usage, not in QUANTUM ESPRESSO.
- If you get Segmentation fault or similar errors in the provided tests and examples: your compiler, or your mathematical libraries, or MPI libraries, or a combination thereof, is buggy, or there is some software incompatibility. Although one can never rule out the presence of subtle bugs in QUANTUM ESPRESSO that are not revealed during the testing phase, it is very unlikely that this happens on the provided tests and examples.
- If all test fails, look into the output and error files: there is some dumb reason for failure.
- If most test pass but some fail, again: look into the output and error files. A frequent source of trouble is complex function `zdotc`. See the "Linux PCs with gfortran compilers" paragraph, or replace `zdotc` with fortran intrinsic `dot_product`.

### 2.8.2 Linux PC

Both AMD and Intel CPUs, 32-bit and 64-bit, are supported and work, either in 32-bit emulation and in 64-bit mode. 64-bit executables can address a much larger memory space than 32-bit executable, but there is no gain in speed. Beware: the default integer type for 64-bit machine is typically 32-bit long. You should be able to use 64-bit integers as well, but it is not guaranteed to work and will not give any advantage anyway.

Currently, `configure` supports Intel (ifort), NAG (nagfor), PGI (pgf90) and gfortran compilers. Pathscale, Sun Studio, AMD Open64, are no longer supported after v.6.2: g95, since v.6.1.

Both Intel MKL and AMD acml mathematical libraries are supported, the former much better than the latter.

It is usually convenient to create semi-statically linked executables (with only libc, libm, libpthread dynamically linked). If you want to produce a binary that runs on different machines, compile it on the oldest machine you have (i.e. the one with the oldest version of the operating system).

#### 2.8.2.1 Linux PCs with gfortran

Gfortran v.4.8.5, still often found on CentOS machines, no longer compiles QUANTUM ESPRESSO v.6.6 or later, due to a gfortran bug. You need at least gfortran v.4.9.X.

"There is a known incompatibility problem between different calling convention for Fortran functions that return complex values [...] If your code crashes during a call to `zdotc`, recompile QUANTUM ESPRESSO using the internal BLAS and LAPACK routines (using `configure` options `–with-internal-blas` and `–with-internal-lapack`) to see if the problem disappears; or, add the `-ff2c` flag" (info by Giovanni Pizzi, Jan. 2013).

If you want to use MKL libraries together with gfortran, link `-lmkl_gf_lp64`, not `-lmkl_intel_lp64` (and the like for other architectures).

#### 2.8.2.2 Linux PCs with Intel compiler (ifort)

IMPORTANT NOTE: ifort versions earlier than v.15 miscompile the new XML code in QE v.6.4 and later. Please install this patch:
`https://gitlab.com/QEF/q-e/wikis/Support/Patch-for-old-Intel-compilers`.

The Intel compiler ifort `http://software.intel.com/` produces fast executables, at least on Intel CPUs, but not all versions work as expected. In case of trouble, update your version with the most recent patches. Since each major release of ifort differs a lot from the previous one, compiled objects from different releases may be incompatible and should not be mixed.

The Intel compiler is no longer free for personal usage, but it is still for students and open-source contributors (`https://software.intel.com/en-us/qualify-for-free-software`).

If `configure` doesn't find the compiler, or if you get Error loading shared libraries at run time, you may have forgotten to execute the script that sets up the correct PATH and library path. Unless your system manager has done this for you, you should execute the appropriate script – located in the directory containing the compiler executable – in your initialization files. Consult the documentation provided by Intel.

The warning: feupdateenv is not implemented and will always fail, can be safely ignored. Warnings on ``bad preprocessing option'' when compiling iotk and complains about ``recommended formats'' may also be ignored.

#### 2.8.2.3 Linux PCs with MKL libraries

On Intel CPUs it is very convenient to use Intel MKL libraries (freely available at `https://software.intel.com/en-us/performance-libraries`). MKL libraries can be used also with non-Intel compilers. They work also for AMD CPU, selecting the appropriate machine-optimized libraries: see ``Linux PCs with AMD processors''.

`configure` properly detects only recent (v.12 or later) MKL libraries, as long as the $MKLROOT environment variable is set in the current shell. Normally this environment variable is set by sourcing the Intel MKL or Intel Parallel Studio environment script. By default the non-threaded version of MKL is linked, unless option `configure –with-openmp` is specified. In case of trouble, refer to the following web page to find the correct way to link MKL:
`http://software.intel.com/en-us/articles/intel-mkl-link-line-advisor/`.

For parallel (MPI) execution on multiprocessor (SMP) machines, set the environment variable OMP_NUM_THREADS to 1 unless you know what you are doing. See Sec.3 for more info on this and on the difference between MPI and OpenMP parallelization.

If you get a mysterious "too many communicators" error and a subsequent crash: there is a bug in Intel MPI and MKL 2016 update 3. See this thread and the links quoted therein: `http://www.mail-archive.com/pw_forum@pwscf.org/msg29684.html`.

#### 2.8.2.4 Linux PCs with AMD processors

For AMD CPUs you may find convenient to link AMD acml libraries (can be freely downloaded from AMD web site). `configure` should recognize properly installed acml libraries. UPDATE (February 2020): ACML have been discontinued. There are new libraries called AMD Optimizing CPU Libraries (AOCL), tuned for the AMD EPYC processor family. `` Recently I played around with some AMD EPYC cpus and the bad thing is that I also saw some strange numbers when using libflame/aocl 2.1. (...) Since version 2020 the MKL performs rather well when using AMD cpus, however, if you want to get the best performance you have to additionally set:

    export MKL_DEBUG_CPU_TYPE=5

which gives an additional 10-20% speedup with MKL 2020, while for earlier versions the speedup is greater than 200%. [...] Another note, there seem to be problems using FFTW interface of MKL with AMD cpus. To get around this problem, one has to additionally set

    export MKL_CBWR=AUTO

`` (Info by Tobias Klöffel, Feb. 2020)

###
2.8.3 Linux PC clusters with MPI

PC clusters running some version of MPI are a very popular computational platform nowadays. QUANTUM ESPRESSO is known to work with at least two of the major MPI implementations (MPICH, LAM-MPI), plus with the newer MPICH2 and OpenMPI implementation. `configure` should automatically recognize a properly installed parallel environment and prepare for parallel compilation. Unfortunately this not always happens. In fact:

- `configure` tries to locate a parallel compiler in a logical place with a logical name, but if it has a strange names or it is located in a strange location, you will have to instruct `configure` to find it. Note that in many PC clusters (Beowulf), there is no parallel Fortran compiler in default installations: you have to configure an appropriate script, such as mpif90.
- `configure` tries to locate libraries (both mathematical and parallel libraries) in the usual places with usual names, but if they have strange names or strange locations, you will have to rename/move them, or to instruct `configure` to find them. If MPI libraries are not found, parallel compilation is disabled.
- `configure` tests that the compiler and the libraries are compatible (i.e. the compiler may link the libraries without conflicts and without missing symbols). If they aren't and the compilation fails, `configure` will revert to serial compilation.

Apart from such problems, QUANTUM ESPRESSO compiles and works on all non-buggy, properly configured hardware and software combinations. In some cases you may have to recompile MPI libraries: not all MPI installations contain support for the Fortran compiler of your choice (or for any Fortran compiler at all!).

If QUANTUM ESPRESSO does not work for some reason on a PC cluster, try first if it works in serial execution. A frequent problem with parallel execution is that QUANTUM ESPRESSO does not read from standard input, due to the configuration of MPI libraries: see Sec.3.4. If you are dissatisfied with the performances in parallel execution, see Sec.3 and in particular Sec.3.4.

###
2.8.4 Microsoft Windows

Since February 2020 QUANTUM ESPRESSO can be compiled on MS-Windows 10 using PGI 19.10 Community Edition (freely downloadable). `configure` works with the bash script provided by PGI but the `configure` of FoX fails: use script `install/build_fox_with_pgi.sh` to manually compile FoX.

Another option: use MinGW/MSYS. Download the installer from `https://osdn.net/projects/mingw/`, install MinGW, MSYS, gcc and gfortran. Start a shell window; run "./configure"; edit `make.inc`; uncommenting the second definition of TOPDIR (the first one introduces a final "/" that Windows doesn't like); run "make". Note that on some Windows the code fails when checking that `tmp_dir` is writable, for unclear reasons.

Another option is Cygwin, a UNIX environment which runs under Windows: see
`http://www.cygwin.com/`.

Windows-10 users may also enable the Windows Subsystem for Linux (see here:
`https://docs.microsoft.com/en-us/windows/wsl/install-win10`), install a Linux distribution, compile QUANTUM ESPRESSO as on Linux. It works very well.

As a final option, one can use Quantum Mobile:
`https://www.materialscloud.org/work/quantum-mobile`.

### 2.8.5 Mac OS

Mac OS-X machines with gfortran or with the Intel compiler ifort and MKL libraries should work, but "your mileage may vary", depending upon the specific software stack you are using. Parallel compilation with OpenMPI should also work.

If you get an error like

      clang: error: no input files
      make[1]: *** [laxlib.fh] Error 1
      make: *** [libla] Error 1i

redefine `CPP` as `CPP=gcc -E` in `make.inc`.

Gfortran information and binaries for Mac OS-X here: `http://hpc.sourceforge.net/` and `https://wiki.helsinki.fi/display/HUGG/GNU+compiler+install+on+Mac+OS+X`.

Mysterious crashes in `zdotc` are due to a known incompatibility of complex functions with some optimized BLAS. See the "Linux PCs with gfortran" paragraph.

Next: 2.9 Cray machines Up: 2 Installation Previous: 2.7 Running tests and Contents