Presently, the Quantum-ESPRESSO package is only distributed in source
form; some precompiled executables (binary files) are provided only
for
PWgui. Providing binaries would require too much effort
and would work only for a small number of machines anyway.
Stable releases of the Quantum-ESPRESSO source package (current version is 3.0) can be downloaded from this URL:
http://www.pwscf.org/download.htm
Uncompress and unpack the distribution using the command:
tar zxvf espresso-3.0.tar.gz
If your version of tar doesn't recognize the z flag, use this instead:
gunzip -c espresso-3.0.tar.gz | tar xvf -
cd to the directory espresso/ that will be created. The bravest may access the (unstable) development version via anonymous CVS (Concurrent Version System): see the file README.cvs contained in the distribution.
To install Quantum-ESPRESSO from source, you need C and Fortran-95 compilers (Fortran-90 is not sufficient, but most "Fortran-90" compilers are actually Fortran-95-compliant). If you don't have a commercial Fortran-95 compiler, you may install the free g95 compiler (http://www.g95.org/): it is still unfinished but already usable. You also need a minimal Unix environment: basically, a command shell (e.g., bash or tcsh) and the make and awk utilities. MS-Windows users need to have Cygwin (a UNIX environment which runs under Windows) installed. See http://www.cygwin.com/.
Instructions for the impatient:
./configure make allExecutable programs (actually, symlinks to them) will be placed in the bin/ directory.
If you have problems or would like to tweak the default settings, read the detailed instructions below.
To configure the Quantum-ESPRESSO source package, run the configure script. It will (try to) detect compilers and libraries available on your machine, and set up things accordingly. Presently it is expected to work on most Linux 32- and 64-bit (Itanium and Opteron) PCs and clusters, IBM SP machines, SGI Origin, some HP-Compaq Alpha machines, Cray X1, Mac OS X, MS-Windows PCs. It may work with some assistance also on other architectures (see below).
For cross-compilation, you have to specify the target machine with the -host option (see below). This feature has not been extensively tested, but we had at least one successful report (compilation for NEC SX6 on a PC).
Specifically, configure generates the following files:
make.sys: compilation rules and flags
*/make.depend: dependencies, per source directory
configure.msg: a report of the configuration run
configure.msg is only used by configure to print its final report. It isn't needed for compilation. make.depend files are actually generated by invoking the makedeps.sh shell script. If you modify the program sources, you might have to rerun it.
You should always be able to compile the Quantum-ESPRESSO suite of programs
without having to edit any of the generated files. However you may
have to tune configure by specifying appropriate environment
variables and/or command-line options.
Usually the most tricky part is to get external libraries recognized
and used: see section
, ``Libraries'', for details and
hints.
Environment variables may be set in any of these ways:
export VARIABLE=value # sh, bash, ksh ./configure setenv VARIABLE value # csh, tcsh ./configure ./configure VARIABLE=value # any shellSome environment variables that are relevant to configure are:
ARCH: label identifying the machine type (see below)For example, the following command line:
F90, F77, CC: names of Fortran 95, Fortran 77, and C compilers
MPIF90, MPIF77, MPICC: names of parallel compilers
CPP: source file preprocessor (defaults to $CC -E)
LD: linker (defaults to $MPIF90)
CFLAGS, FFLAGS, F90FLAGS, CPPFLAGS, LDFLAGS: compilation flags
LIBDIRS: extra directories to search for libraries (see below)
./configure MPIF90=mpf90 FFLAGS="-O2 -assume byterecl" \
CC=gcc CFLAGS=-O3 LDFLAGS=-static
instructs configure to use mpf90 as Fortran 95
compiler with flags -O2 -assume byterecl,
gcc as C compiler with flags -O3, and to link with
flags -static. Note that the value of FFLAGS must
be quoted, because it contains spaces.
If your machine type is unknown to configure, you may use the ARCH variable to suggest an architecture among supported ones. Try the one that looks more similar to your machine type; you'll probably have to do some additional tweaking. Currently supported architectures are:
linux64: Linux 64-bit machines (Itanium, Opteron)Finally, configure recognizes the following command-line options:
linux32: Linux PCs
aix: IBM AIX machines
mips: SGI MIPS machines
alpha: HP-Compaq alpha machines
sparc: Sun SPARC machines
crayx1: Cray X1 machines
mac: Apple PowerPC machines running Mac OS X
cygwin: MS-Windows PCs with Cygwin
-disable-parallel: compile serial code, even if parallel environment is available.If you want to modify the configure script (advanced users only!), read the instructions in README.configure first. You'll need GNU Autoconf (http://www.gnu.org/software/autoconf/).
-disable-shared: don't use shared libraries: generate static executables.
-enable-shared: use shared libraries.
-host=target: specify target machine for cross-compilation.
Target must be a string identifying the architecture that you want to compile for; you can obtain it by running config.guess on the target machine.
Quantum-ESPRESSO makes use of the following external libraries:
Quantum-ESPRESSO can use the following architecture-specific replacements for BLAS and LAPACK:
essl for IBM machinesIf none of these is available, we suggest that you use the optimized ATLAS library (http://math-atlas.sourceforge.net/). Note that ATLAS is not a complete replacement for LAPACK: it contains all of the BLAS, plus the LU code, plus the full storage Cholesky code. Follow the instructions in the ATLAS distributions to produce a full LAPACK replacement.
complib.sgimath for SGI Origin
SCSL for SGI Altix
scilib for Cray/T3e
sunperf for Sun
MKL for Intel Linux PCs
ACML for AMD Linux PCs
cxml for HP-Compaq Alphas.
Axel Kohlmeyer maintains a set of ATLAS libraries,
containing all of LAPACK and no external reference to fortran
libraries:
http://www.theochem.rub.de/~axel.kohlmeyer/cpmd-linux.html#atlas
Sergei Lisenkov reported success and good performances with optimized BLAS by Kazushige Goto. They can be downloaded freely (but not redistributed!) from: http://www.cs.utexas.edu/users/flame/goto/
The FFTW library can also be replaced by vendor-specific FFT libraries, when available, or you can link to a precompiled FFTW library. Please note that you must use FFTW version 2. Support for version 3 is in progress: contact the developers if you want to try.
Finally, Quantum-ESPRESSO can use the MASS vector math library from IBM, if available (only on AIX).
The configure script attempts to find optimized libraries, but may fail if they have been installed in non-standard places. You should examine the final value of BLAS_LIBS, LAPACK_LIBS, FFT_LIBS, MPI_LIBS (if needed), MASS_LIBS (IBM only), either in the output of configure or in the generated make.sys, to check whether it found all the libraries that you intend to use.
If any libraries weren't found, you can specify a list of directories to search in the environment variable LIBDIRS, and rerun configure; directories in the list must be separated by spaces. For example:
./configure LIBDIRS="/opt/intel/mkl70/lib/32 /usr/lib/math"If this still fails, you may set some or all of the *_LIBS variables manually and retry. For example:
./configure BLAS_LIBS="-L/usr/lib/math -lf77blas -latlas_sse"Beware that in this case, configure will blindly accept the specified value, and won't do any extra search. This is so that if configure finds any library that you don't want to use, you can override it.
If you want to use a precompiled FFTW library, the corresponding fftw.h include file is also required. That may or may not have been installed on your system together with the library: in particular, most Linux distributions split libraries into ``base'' and ``development'' packages, include files normally belonging to the latter. Thus if you can't find fftw.h on your machine, chances are you must install the FFTW development package (how exactly it's called depends on your distribution).
If instead the file is there, but configure doesn't find it, you may specify its location in the INCLUDEFFTW environment variable. For example:
./configure INCLUDEFFTW="/usr/lib/fftw-2.1.3/fftw"If everything else fails, you'll have to write the make.sys file manually: see section
, ``Manual configuration''.
Please Note: If you change any settings after a previous (successful or failed) compilation, you must run make clean before recompiling, unless you know exactly which routines are affected by the changed settings and how to force their recompilation.
To configure Quantum-ESPRESSO manually, you have to write a working make.sys yourself, and run makedeps.sh to generate */make.depend files.
For make.sys, several templates (each for a different machine type) to start with are provided in the install/ directory: they have names of the form Make.system, where system is a string identifying the architecture and compiler. Currently available systems are:
alpha: HP-Compaq alpha workstationsTo select the appropriate templates, you can run:
alphaMPI: HP-Compaq alpha parallel machines
altix: SGI Altix 350/3000 with Linux, Intel compiler
beo_ifc: Linux clusters of PCs, Intel compiler
beowulf: Linux clusters of PCs, Portland compiler
cygwin: Windows PC, Intel compiler
fujitsu: Fujitsu vector machines
hitachi: Hitachi SR8000
hp: HP PA-RISC workstations
hpMPI: HP PA-RISC parallel machines
ia64: HP Itanium workstations
ibm: IBM RS6000 workstations
ibmsp: IBM SP machines
irix: SGI workstations
origin: SGI Origin 2000/3000
pc_abs: Linux PCs, Absoft compiler
pc_ifc: Linux PCs, Intel compiler
pc_lahey: Linux PCs, Lahey compiler
pc_pgi: Linux PCs, Portland compiler
sun: Sun workstations
sunMPI: Sun parallel machines
sxcross: NEC SX-6 (cross-compilation)
t3e: Cray T3E
./configure.old system
where system is the best match to your configuration; configure.old with no arguments prints the up-to-date list of available systems.
That will copy Make.system to make.sys; for convenience, it'll also run makedeps.sh to generate */make.depend files.
Most probably (and even more so if there isn't an exact match to your machine type), you'll have to tweak make.sys by hand. In particular, you must specify the full list of libraries that you intend to link to. You'll also have to set the MYLIB variable to:
blas_and_lapack to compile BLAS and LAPACK from source;
lapack_mkl to use the Intel MKL library;
lapack_t3e to use the LAPACK for Cray T3E;
otherwise, leave it empty.
The Makefile for HP PA-RISC workstations and parallel machines is based on a Makefile contributed by Sergei Lysenkov. It assumes that you have HP compiler with MLIB libraries installed on a machine running HP-UX.
The Makefile for Windows PCs is based on a Makefile written for an earlier version of PWscf (1.2.0), contributed by Lu Fu-Fa, CCIT, Taiwan. You will need the Cygwin package. The provided Makefile assumes that you have the Intel compiler with MKL libraries installed. It is untested.
If you run into trouble, a possibility is to install Linux in dual-boot mode. You need to create a partition for Linux, install it, install a boot loader (LILO, GRUB). The latter step is not needed if you boot from floppy or CD-ROM. In principle one could avoid installation altogether using a distribution like Knoppix that runs directly from CD-ROM, but for serious use disk access is needed.
There are a few adjustable parameters in Modules/parameters.f90. The present values will work for most cases. All other variables are dynamically allocated: you do not need to recompile your code for a different system.
At your option, you may compile the complete Quantum-ESPRESSO suite of programs (with make all), or only some specific programs.
make with no arguments yields a list of valid compilation targets. Here is a list:
pw.x calculates electronic structure, structural optimization, molecular dynamics, barriers with NEB. memory.x is an auxiliary program that checks the input of pw.x for correctness and yields a rough (under-) estimate of the required memory.
ph.x calculates phonon frequencies and displacement patterns, dielectric tensors, effective charges (uses data produced by pw.x).
d3.x calculates anharmonic phonon lifetimes (third-order derivatives of the energy), using data produced by pw.x and ph.x (Ultrasoft pseudopotentials not supported).
phcg.x is a version of ph.x that calculates phonons at q = 0 using conjugate-gradient minimization of the density functional expanded to second-order. Only the ( q = 0 ) point is used for Brillouin zone integration. It is faster and takes less memory than ph.x, but does not support Ultrasoft pseudopotentials.
, ``Pseudopotentials'').
The codes for data postprocessing in PP/ are:
The utility programs in pwtools/ are:
awk -f bs.awk < my-pw-file > myfile.bs awk -f mv.awk < my-pw-file > myfile.mvThe files so produced are suitable for use with xbs, a very simple X-windows utility to display molecules, available at:
As a final check that compilation was successful, you may want to run some or all of the examples contained within the examples directory of the Quantum-ESPRESSO distribution. Those examples try to exercise all the programs and features of the Quantum-ESPRESSO package. A list of examples and of what each example does is contained in examples/README. For details, see the README file in each example's directory. If you find that any relevant feature isn't being tested, please contact us (or even better, write and send us a new example yourself!).
If you haven't downloaded the full Quantum-ESPRESSO distribution and don't have the examples, you can get them from the Test and Examples Page of the Quantum-ESPRESSO web site (http://www.pwscf.org/tests.htm). The necessary pseudopotentials are included.
To run the examples, you should follow this procedure:
BIN_DIR= directory where Quantum-ESPRESSO executables resideIf you have downloaded the full Quantum-ESPRESSO distribution, you may set BIN_DIR=$TOPDIR/bin and PSEUDO_DIR=$TOPDIR/pseudo, where $TOPDIR is the root of the Quantum-ESPRESSO source tree.
PSEUDO_DIR= directory where pseudopotential files reside
TMP_DIR= directory to be used as temporary storage area
In order to be able to run all the examples, the PSEUDO_DIR directory must contain the following files:
If any of these are missing, you can download them (and many others) from the Pseudopotentials Page of the Quantum-ESPRESSO web site (http://www.pwscf.org/pseudo.htm).Al.vbc.UPF, As.gon.UPF, C.pz-rrkjus.UPF, Cu.pz-d-rrkjus.UPF, Fe.pz-nd-rrkjus.UPF, H.fpmd.UPF, H.vbc.UPF, N.BLYP.UPF, Ni.pbe-nd-rrkjus.UPF, NiUS.RRKJ3.UPF, O.BLYP.UPF, O.LDA.US.RRKJ3.UPF, O.pbe-rrkjus.UPF, O.vdb.UPF, OPBE_nc.UPF, Pb.vdb.UPF, Ptrel.RRKJ3.UPF, Si.vbc.UPF, SiPBE_nc.UPF, Ti.vdb.UPF
TMP_DIR must be a directory you have read and write access to, with enough available space to host the temporary files produced by the example runs, and possibly offering high I/O performance (i.e., don't use an NFS-mounted directory).
, ``Running on parallel machines'' for
details.
In order to do that, edit again the environment_variables file and set the PARA_PREFIX and PARA_POSTFIX variables as needed. Parallel executables will be run by a command like this:
$PARA_PREFIX pw.x $PARA_POSTFIX < file.in > file.out
For example, if the command line is like this (as for an IBM SP4):
poe pw.x -procs 4 < file.in > file.outyou should set PARA_PREFIX="poe", PARA_POSTFIX="-procs 4".
Furthermore, if your machine does not support interactive use, you must run the commands specified below through the batch queueing system installed on that machine. Ask your system administrator for instructions.
./run_exampleThis will create a subdirectory results, containing the input and output files generated by the calculation.
Some examples take only a few seconds to run, while others may require several minutes depending on your system.
To run all the examples in one go, execute:
./run_all_examplesfrom the examples directory. On a single-processor machine, this typically takes one to three hours.
The make_clean script cleans the examples tree, by removing all the results subdirectories. However, if additional subdirectories have been created, they aren't deleted.
Instead, you can run the check_example script in the examples directory:
./check_example example_dir
where example_dir is the directory of the example that you want to check (e.g., ./check_example example01). You can specify multiple directories.
Note: at the moment check_example is in early development and (should be) guaranteed to work only on examples 01 to 04.
The main development platforms are IBM SP and Intel/AMD PC with Linux and Intel compiler. For other machines, we rely on user's feedback.
Working fortran-95 and C compilers are needed in order to compile Quantum-ESPRESSO. Most so-called ``fortran-90'' compilers implement the fortran-95 standard, but older versions may not be fortran-95 compliant.
If you get ``Compiler Internal Error'' or similar messages, 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, 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 version.
If you get an error in the loading phase that looks like ``ld: file XYZ.o: unknown (unrecognized, invalid, wrong, missing, ...) file type'', or ``While processing relocatable file XYZ.o, no relocatable objects were found'' (T3E), one of the following things have happened:
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). If you did, but symbols are still missing, see below (for Linux PC).
Many versions of the MIPS compiler yield compilation errors in conjunction with with FORALL constructs. There is no known solution other than editing the FORALL construct that gives a problem, or to replace it with an equivalent DO...END DO construct.
If at linking stage you get error messages like: ``undefined reference to `for_check_mult_overflow64' '' with Compaq/HP fortran compiler on Linux Alphas, check the following page: http://linux.iol.unh.edu/linux/fortran/faq/cfal-X1.0.2.html.
The web site of Axel Kohlmeyer contains a very informative section
on compiling and running CPMD on Linux.
Most of its contents applies to the Quantum-ESPRESSO code as well:
http://www.theochem.rub.de/~axel.kohlmeyer/cpmd-linux.html.
On newer Linux machines, even statically linked binaries will try to open some shared libraries, which will lead to crashes if libc/libm/libpthreads are not linked dynamically. Machines using glibc-2.2.4 and older seem ok: compile on these machines if you want to share precompiled binaries. Crashes due to multithreading (e.g. when using a multithreaded ATLAS or MKL) on machines with the newer threads (nptl) can be worked around by setting the environment variable LD_ASSUME_KERNEL to '2.2.5'. For the newest Intel compilers, -static-libcxa does the trick most of the time. (info from Axel Kohlmeyer)
Since there is no standard compiler for Linux, different compilers have different ideas about the right way to call external libraries. As a consequence you may have a mismatch between what your compiler calls ("symbols") and the actual name of the required library call. Use the nm command to determine the name of a library call, as in the following examples:
nm /usr/local/lib/libblas.a | grep T | grep -i daxpy
nm /usr/local/lib/liblapack.a | grep T | grep -i zhegv
where typical location and name of libraries is assumed.
Most precompiled libraries have lowercase names with one or two
underscores (_) appended. configure should select the
appropriate preprocessing options in make.sys, but in
case of trouble, be aware that:
With some precompiled lapack libraries, you may need to add -lg2c or -lm or both.
Quantum-ESPRESSO does not work reliably, or not at all, with some
versions (in particular, 5.2) of the Portland Group compiler.
We think that this is due to compiler bugs, not to Quantum-ESPRESSO
bugs. In any event, use the latest version of each release of the
compiler, with patches if available: see the Portland Group web
site,
http://www.pgroup.com/faq/install.htm#release_info
If configure doesn't find the compiler, or if you get ``Error
loading shared libraries...'' at run time, you 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.
Each major release of the Intel compiler differs a lot from the previous one. Do not mix compiled objects from different releases: they are incompatible. Intel compiler v. 7 and later use a different method to locate where modules are with respect to v. < 7 : if you are using the manual configuration, choose the appropriate line MODULEFLAG=... in make.sys.
Some releases of Intel compiler v. 7 and 8 yield ``Compiler Internal
Error''.
Update to the last version (presently 7.1.41, 8.0.046 or
8.1.018, respectively), available via Intel Premier support
(registration free of charge for Linux):
http://developer.intel.com/software/products/support/#premier.
There are conflicting reports on the newest version 9. In any event,
look for the last version with the most patches.
Warnings ``size of symbol ... changed ...'' are produced by ifc 7.1 at the loading stage. These seem to be harmless, but they may cause the loader to stop, depending on your system configuration. If this happens and no executable is produced, add the following to LDFLAGS: -Xlinker -noinhibit-exec.
On Intel CPUs, it is very convenient to use Intel MKL libraries. If configure doesn't find them, try configure -enable-shared. MKL also contains optimized FFT routines, but they are presently not supported: use FFTW instead. Note that Intel compiler v. 8 fails to load with MKL v. 5.2 or earlier versions, because some symbols that are referenced by MKL are missing. There is a fix for this (info from Konstantin Kudin): add libF90.a from ifc 7.1 at the linking stage, as the last library. Note that some combinations of not-so-recent versions of MKL and ifc may yield a lot of "undefined references" when statically loaded: use configure -enable-shared, or remove the -static option in make.sys. Note that pwcond.x works only with recent versions (v.7 or later) of MKL.
When using/testing/benchmarking MKL on SMP (multiprocessor) machines, one should set the environmental variable OMP_NUM_THREADS to 1, unless the OpenMP parallelization is desired. MKL by default sets the variable to the number of CPUs installed and thus gives the impression of a much better performance, as the CPUu time is only measured for the master thread (info from Axel Kohlmeyer).
The I/O libraries used by older versions of the Intel compiler are incompatible with those called by most precompiled BLAS/LAPACK libraries (including ATLAS): you get error messages at linking stage. A workaround is to recompile BLAS/LAPACK with ifc, or (better) to replace the BLAS routine xerbla and LAPACK routine dlamch (the only two containing I/O calls) with recompiled objects:
ifc -c xerbla.f
ifc -O0 -c dlamch.f
(do not forget -O0 -- dlamch.f must be
compiled without optimization) and replace them into the library, as
in the following example:
ar rv libatlas.a xerbla.o dlamch.o
(assuming that the library and the two object files are in the same
directory). See also Axel Kohlmeyer's web site.
Linux distributions using glibc 2.3 or later (such as e.g. RedHat 9) may be incompatible with ifc 7.0 and 7.1. The incompatibility shows up in the form of messages ``undefined reference to `errno' '' at linking stage. A workaround is available: see http://newweb.ices.utexas.edu/misc/ctype.c.
There is a well known problem with version 8 of Intel compiler and pthreads (that are used both in Debian Woody and Sarge) that causes "segmentation fault" errors (info from Lucas Fernandez Seivane). Version 7 does not have this problem.
AMD Athlon CPUs can be basically treated like Intel Pentium CPUs. You can use the Intel compiler and MKL with Pentium-3 optimization.
Konstantin Kudin reports that the best results in terms of performances are obtained with ATLAS optimized BLAS/LAPACK libraries, using AMD Core Math Library (ACML) for the missing libraries. ACML can be freely downloaded from AMD web site. Beware: some versions of ACML - i.e. the GCC version with SSE2 - crash PWscf. The ``_nosse2'' version appears to be stable. Load first ATLAS, then ACML, then -lg2c, as in the following example (replace what follows -L with something appropriate to your configuration):
-L/location/of/fftw/lib/ -lfftw \ -L/location/of/atlas/lib -lf77blas -llapack -lcblas -latlas \ -L/location/of/gnu32_nosse2/lib -lacml -lg2c64-bit CPUs like the AMD Opteron and the Intel Itanium are supported and should work both in 32-bit emulation and in 64-bit mode (in the latter case, -D__LINUX64 is needed among the preprocessing flags). Both the PGI and the Intel compiler (v8.1 EM64T-edition, available via Intel Premier support) should work. 64-bit executables can address a much larger memory space, but apparently they are not especially faster than 32-bit executables. The Intel compiler has been reported to be more reliable and to produce faster executables wrt the PGI compiler. You may also try with g95.
PC clusters running some version of MPI are a very popular computational platform nowadays. Two major MPI implementations (MPICH, LAM-MPI) are available. The number of possible configurations, in terms of type and version of the MPI libraries, kernels, system libraries, compilers, is very large. Quantum-ESPRESSO compiles and works on all non-buggy, properly configured configuration. You may have to recompile MPI libraries in order to be able to use them with the Intel compiler. See Axel Kohlmeyer's web site for precompiled versions of the MPI libraries.
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 a bad configuration of MPI libraries: see section ``Running on parallel machines''. If you get weird errors with LAM-MPI, add -D__LAM to preprocessing options and recompile. See also Axel Kohlmeyer's web site for more info.
If you are dis satisfied with the performances in parallel execution, read the ``Parallelization issues'' section.
The following workaround is needed: in files PW/bp_zgefa.f and PW/bp_zgedi.f, replace all occurrences of zscal, zaxpy, zswap, izamax with cscal, caxpy, cswap, icamax. Also, in PP/dist.f you need to comment the call to getarg and uncomment the call to pxfgetarg.
If you have a T3E with ``benchlib'' installed, you may want to use it by adding -D__BENCHLIB to preprocessing flags. If you get errors at loading because symbols LPUTP, LGETV, LSETV are undefined, you either need to link ``benchlib'', or to remove -D__BENCHLIB and recompile (after a make clean).
The PWSCF Group - 2005-11-18