quantum-espresso/README.install

----------------------------------------------------------------------
INSTALLATION INSTRUCTIONS
----------------------------------------------------------------------

More detailed instructions can be found in the Quantum-ESPRESSO User's
Guide: you can find it in the "Doc/" directory of the Quantum-ESPRESSO
source distribution, or download it from
http://www.pwscf.org/guide.htm

----------------------------------------------------------------------

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/).
You also need a minimal Unix environment: basically, a command shell
(e.g., "bash" or "tcsh") and the utilities "make", "awk" and "sed".
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 all

Executable 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.

----------------------------------------------------------------------
CONFIGURE
----------------------------------------------------------------------

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 hasn't been tested
extensively, but we had at least one successful report (compilation
for NEC SX6 on a PC).

Specifically, "configure" generates the following files:

  make.sys         compilation settings 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 the next section 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 shell

Some environment variables that are relevant to "configure" are:

  ARCH : label identifying the machine type (see below)
  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)

For example, the following command line:

  ./configure MPIF90=mpf90 FFLAGS="-O2 -assume byterecl" \
              CC=gcc CFLAGS=-O3 LDFLAGS=-static

instructs "configure" to use "mpf90" as parallel Fortran 90 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:

  ia32       Intel 32-bit machines (x86) running Linux
  ia64       Intel 64-bit (Itanium) running Linux
  amd64      AMD 64-bit (Opteron) running Linux
  aix        IBM AIX machines
  mips       SGI MIPS machines
  alpha      HP-Compaq alpha machines
  alinux     HP-Compaq alpha running Linux
  sparc      Sun SPARC machines
  crayx1     Cray X1 machines
  mac        Apple PowerPC running Mac OS X
  cygwin     MS-Windows PCs with Cygwin

Finally, "configure" recognizes the following command-line options:

  --disable-parallel : compile serial code, even if parallel
                       environment is available.
  --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.

If you want to modify the "configure" script itself (advanced users
only!), read the instructions in "README.configure" first.  You'll
need GNU Autoconf (http://www.gnu.org/software/autoconf/).

----------------------------------------------------------------------
LIBRARIES

Quantum-ESPRESSO makes use of the following external libraries:

  BLAS (http://www.netlib.org/blas/) and LAPACK
    (http://www.netlib.org/lapack/) for linear algebra
  FFTW (http://www.fftw.org/) for Fast Fourier Transforms

A copy of the needed routines is provided with the distribution.
However, when available, optimized vendor-specific libraries can be
used instead: this often yields huge performance gains.

Quantum-ESPRESSO can use the following architecture-specific
replacements for BLAS and LAPACK:

  essl for IBM machines
  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.

If 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.

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/

At compilation time you have to choose whether to use the built-in
copy of FFTW (v.<3), a precompiled FFTW v.<3 library, or a
precompiled FFTW v.3 library. This is done using preprocessing
options with rather obvious meaning : __FFTW, __USE_INTERNAL_FFTW, __FFTW3

The FFTW library can also be replaced by vendor-specific FFT libraries, 
when available.

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 v.<3 library, you will need 
the corresponding "fftw.h" include file. 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 to do this and
what it is exactly called depends on your operating system version).

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 the Quantum-ESPRESSO User's Guide for instructions.

*** 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.

----------------------------------------------------------------------
COMPILE
----------------------------------------------------------------------

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:

  make pw           compile PW/pw.x (electronic and ionic optimization), 
                      PW/memory.x (checks memory usage and tests input)
  make cp           compile CPV/cp.x (Car-Parrinello MD with ultrasoft
                      pseudopotentials)
  make ph           compile PH/ph.x (phonons)
  make pp           compile postprocessing codes in the PP directory
  make gamma        compile Gamma/phcg.x (Gamma-only version of ph.x)
  make pwcond       compile PWCOND/pwcond.x (ballistic conductance)
  make d3           compile D3/d3.x (third-order energy derivatives)
  make raman        compile Raman/ram.x (Raman cross-section calculation)
  make tools        compile pwtools/* (miscellaneous tools for data
                      analysis)

  make ld1          compile atomic/ld1.x code for pseudopotential generation
  make upf          compile upftools/* (utilities for pseudopotential
                      conversion)

  make pwall        same as "make pw ph pp d3 raman pwcond gamma tools"
  make all          same as "make pwall ld1 cp upf"

  make clean        remove object files and executables
  make veryclean    remove configuration files too
  make tar          build a tarball of the current source tree

For more detailed information, see the Quantum-ESPRESSO User's Guide.