
How to compile CP2K code
========================

 1) Acquire the code:

    see http://cp2k.berlios.de/
    The preferred method is to download it from the CVS
    (just use <Enter> if a password is asked for).

    cd $HOME
    touch $HOME/.cvspass
    cvs -d:pserver:anonymous@cvs.cp2k.berlios.de:/cvsroot/cp2k login
    cvs -z3 -d:pserver:anonymous@cvs.cp2k.berlios.de:/cvsroot/cp2k co cp2k

    if cvs is not installed on your system get it at http://www.nongnu.org/cvs/

 2a) gnu make should be on your system (gmake or make on linux) and used for the build, 
     go to http://www.gnu.org/software/make/make.html 
     download from http://ftp.gnu.org/pub/gnu/make/

 2b) an f95 compiler should be installed on your system. We have good experience with gfortran 4.4.X.
     Be aware that some compilers have bugs that might cause them to fail (internal compiler errors, segfaults),
     or, worse, that yield to a miscompiled CP2K. Report bugs to compiler vendors, they (and we) have an interest in fixing them.

 2c) BLAS and LAPACK should be installed.
     using vendor provided libraries can make a very significant difference (up to 100% use e.g. acml, mkl, essl)
     notice that the blas/lapack libraries must match the Fortran compiler used.
     (use the latest versions available, download all patches)
     http://www.netlib.org/blas/
     http://www.netlib.org/lapack/ (see also http://www.netlib.org/lapack-dev/)
     http://math-atlas.sourceforge.net/
     http://www.tacc.utexas.edu/resources/software/ (GotoBLAS)

 2d) MPI and SCALAPACK are needed for parallel runs
     (use the latest versions available, download all patches !!)
     http://www-unix.mcs.anl.gov/mpi/mpich/
     http://www.netlib.org/scalapack/ (see also http://www.netlib.org/lapack-dev/)
     Scalapack can be part of acml or cluster mkl, and these libraries are recommended.
     Recently a scalapack installer has been added that makes installing scalapack easier:
     http://www.netlib.org/scalapack/scalapack_installer.tgz

 2e) fftw can be used to improve FFT speed (depending on architecture).
     It is strongly recommended to install and use FFTW3.
     the current version of the code works with FFTW 2.X or FFTW 3.X (use -D__FFTW2 *or* -D__FFTW3)
     http://www.fftw.org/
     Notice that FFTW must know the Fortran compiler you will use in order to install properly
     (e.g. 'export F77=g95' before configure if you intend to use g95)
     Notice that on machines and compilers which support sse you can configure FFTW3 with --enable-sse2.
     Compilers/systems that do not allign memory (NAG f95) should not use '--enable-sse2' or set the flag
     FFTW_ARRAYS_ALIGNED to false in the CP2K input file. 

 2f) Hartree-Fock exchange (optional use -D__LIBINT) requires the libint package to be installed,
     and is easiest to install with a Fortran compiler that supports ISO_C_BINDING and
     Fortran procedure pointers (recent gfortran, g95, xlf90, ifort).
     Additional information can be found in cp2k/tools/hfx_tools/libint_tools/README_LIBINT
     Tested against libinit-1.1.4, and currently hardcoded to the default angular momentum LIBINT_MAX_AM 5
     (check your include/libint/libint.h to see if it matches)
     http://www.chem.vt.edu/chem-dept/valeev/software/libint/libint.html
     Note, do *NOT* use libinit-1.1.3.

 3) to compile the code:

 3a) The location of compiler and libraries needs to be specified. For a number of common architectures,
     examples can be found in cp2k/arch/*.*
     The names of these files match architecture.version (e.g. Linux-x86-64-g95.sopt).
     Conventionally, 'sopt' stands for serial, while 'popt' stands for parallel.

     You'll need to modify one of these to match your system's settings.
     You can now build CP2K using these settings (where -j N allows for a parallel build using N processes):
     
     > cd cp2k/makefiles
     > make -j N ARCH=architecture VERSION=version
     e.g.
     > make -j N ARCH=Linux-x86-64-g95 VERSION=sopt
     as a short-cut, you can build several version of the code at once
     > make -j N ARCH=Linux-x86-64-g95 sopt popt ssmp psmp

     An executable should appear in cp2k/exe/*

     all compiled files, libraries, executables, .. of all architectures / versions can be removed with
     > make distclean
     to remove objects and mod files only (i.e. keep exe) for a given ARCH/VERSION only use
     > make ARCH=Linux-x86-64-g95 VERSION=sopt clean
     to remove all for a given ARCH/VERSION
     > make ARCH=Linux-x86-64-g95 VERSION=sopt realclean

 3b) The following flags should be present (or not) in the arch file:
     -D__parallel -D__BLACS -D__SCALAPACK: parallel runs
     -D__LIBINT: use libint (needed for HF exchange)
     various FFTs (use __FFTW3 if possible) :
     -D__FFTSG: Stefan Goedecker FFT (should always be there)
     -D__FFTW3: FFTW version 3
     -D__FFTW2: FFTW version 2
     -D__FFTESSL: ESSL
     -D__FFTMKL: mkl
     -D__FFTACML: acml (interface known to be buggy)
     various compilers/architectures needing their own machine_* file
     -D__G95
     -D__NAG
     -D__AIX
     -D__ABSOFT
     -D__PGI
     -D__INTEL
     -D__GFORTRAN
     -D__SX
     -D__DEC
     -D__XT3
     with -D__GRID_CORE=X (with X=1..6) specific optimized core routines can be selected.
     reasonable defaults are provided (see src/lib/collocate_fast.F) but trial-and-error might yield (a small ~10%) speedup.
     -D__HAS_NO_OMP_3: CP2K assumes that compilers support OpenMP 3.0 - If this is not the case
     specify this flag to compile.  Runtime performance will be poorer on low numbers of processors
     Subparts of Fortran 2003 or later that help various aspects of the code:
     -D__PTR_RANK_REMAP: compiler supports pointer rank remapping

 3c) The `I'm feeling lucky' version of building will try to guess what architecture you're on.
     Just type
     > make sopt
     and the script '~/cp2k/tools/get_arch_code' will try to guess your architecture. 
     You can set the 'FORT_C_NAME' to indicate the compiler part of the architecture string.
     > export FORT_C_NAME=g95

 4) If things fail, take a break... and go back to 3a (or skip to step 7)

 5) If your compiler/machine is really special , it shouldn't be too difficult to support it.
    Only ~/cp2k/src/machine*.F should be affected.

 6) If compilation works fine, you can run one of the test cases 
    to try out the executable
    (most inputs in any of the cp2k/tests/*regtest*/ directories are tested on a daily basis)

    >  cd ~/cp2k/tests/QS/
    > ~/cp2k/exe/YOURMACHINE/cp2k.sopt C.inp

    systematic testing can be done following the description on regtesting:
    http://cp2k.berlios.de/regtest.html

 7) In any case please tell us your comments, praise, criticism, thanks, ...

    you can sent email to the people in the team :

    http://developer.berlios.de/project/memberlist.php?group_id=129

 8) A reference manual of CP2K can be found on the web:

    http://cp2k.berlios.de/input/

    or can be generated using the cp2k executable, see

    http://cp2k.berlios.de/manual/generate_manual_howto.html


 9) Happy computing!

 the cp2k team.
