/*! @file 
@brief Installation of BigDFT

@page INSTALL Installation of BigDFT
@brief Instruction for the installation of BigDFT

@tableofcontents

  The compilation and installation of BigDFT rely on the GNU standard building chain: 
  - <tt>configure</tt>
  - <tt>make</tt>
  - <tt>make</tt>

<p>
  BigDFT can be used as an independent program (as described in this manual), or as a library, to be embedded in other softwares, like inside ABINIT.
</p>


@section Building Building the executables

@subsection S1.1 Configure
<p>
The BigDFT build system is based on standard GNU autotools. 
The end user does not need to have the autotools package installed on his computer, the <tt>configure</tt> script provided in the BigDFT package 
will create the appropriate <tt>Makefile</tt> and set all the compilation options, like: the optimization level,
the associated libraries to link with, and so on.
</p>

<p>
After the package has been untarred, the sources should be configured to the local architecture of the system. 
Thanks to the autotools, it is possible to generate several builds from the same source tree. 
It is advised to create a compilation directory, either inside or outside the source tree. 
Lets call this directory <tt>compile-gFortran</tt> for instance. 
One starts the configure from there <tt>'source tree path'/configure</tt>.
</p>

@subsection Options General description of the options
One can tune the compilation environment using the following options:
- <tt>FC</tt>: Specify the compiler (including MPI aware wrappers).
- <tt>FCFLAGS</tt>, <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt>: Specify the flags, like the optimisation flags, 
  to pass to the compilers (default are {-g -O2} for GNU compilers).
- <tt>--prefix=DIR</tt>: Specify your installation directory (<tt>/usr/local</tt> is default).
- <b>Linear algebra options</b>:
  + <tt>--with-ext-linalg</tt>: Give the name of the libraries replacing BLAS and LAPACK (default = none specified). 
    Use the -l before the name(s).
  + <tt>--with-ext-linalg-path</tt>: Give the path of the other linear algebra libraries (default = <tt>-L/usr/lib</tt>). 
    Use the -L before the path(es).
  + <tt>--with-blacs</tt>: Use a parallelised version of Blas routines. If an argument is provided, 
    this argument should provide the linking options (like <tt>-lblacs_provider</tt>. 
    Use <tt>--with-blacs-path</tt> to specify a lookup path.
  + <tt>--with-scalapack</tt>: like <tt>--with-blacs</tt> for Scalapack.
  + <tt>--enable-dgemmsy</tt>: if the target machine supports SSE3 instruction set, 
    this will compile an optimized version of dgemm operations for symmetric matrices.
- <b>Accelarators</b>:
  + <tt>enable-cuda-gpu</tt>: Compile CUDA support for GPU computing.
    * <tt>--with-cuda-path</tt>: Give the path to the NVIDIA CUDA tools (default is <tt>/usr/local/cuda</tt>).
    * <tt>--with-nvcc-flags</tt>: Specify the flags for the NVIDIA CUDA Compiler.
  + <tt>--enable-opencl</tt>: Compile OpenCL support for GPU computing (compatible with <tt>--enable-cuda-gpu</tt>).
    * <tt>--with-ocl-path</tt>: Give the path to the OpenCL installation directory (default is <tt>/usr</tt>).
  + <tt>--enable-intel-mic</tt>: Compile Intel MIC support.
    * <tt>--with-intel-mic-libs</tt>: Link MIC executable with the given addional libraries.
- <b>Additional features</b>:
  + <tt>--with-etsf-io</tt>: Use ETSF file format (binary based on NetCDF) for densities, potentials and wavefunction files.
  + <tt>--with-archives</tt>: Use compression (tar.bz2) for position files during geometry optimisation.
  + <tt>--disable-bindings</tt>: C and Python bindings are enable by default.

<p>
The other available options can be browsed via the <tt>--help</tt> option. 
Some of them are listed here (and they can be of course combined with each other, when it does make sense):
</p>
- <tt>--disable-mpi</tt>: Force not to use MPI during build. By default the configure will try to detect if the compiler has some native MPI capabilities. 
  If not MPI will be automatically disabled.
- <tt>--enable-debug</tt>: Creates a slower version of the executable in which any of the array allocated is filled by <tt>NaN</tt> after its boundaries. 
  Useful to detect runtime errors during developments
- <tt>--with-memory-limit=&lt;mem&gt;</tt>: Creates a version of the executable which abort the run 
  if one of the processes allocates more memory than <tt>&lt;mem&gt;</tt> (in Gb).
  This version is not necessarily slower that traditional copilation.


@subsection Configure Example of configure output
<p>
At the end of the configure script a summary is printed. It looks like that:
</p>

<pre>
~/bigdft-trunk/tmp-gfortran$ ../configure \
  FC=mpif90.openmpi \
  FCFLAGS=&quot;-fbounds-check -O2 -Wall&quot;
  [...]
  Basics:
  Fortran90 compiler:        mpif90.openmpi
  Fortran90 compiler name:
  Fortran90 flags:           -fbounds-check -O2 -Wall
  Fortran77 compiler:        gfortran
  Fortran77 flags:           -g -O2
  Linker flags:              -L$(top_builddir)/libXC/src -L$(top_builddir)/libABINIT/src -L$(top_builddir)/libPAW/src
  Linked libraries:          -labinit -lpaw -lxc -llapack -lblas

  Build:
  Library ABINIT:            yes
  Library PAW:               yes
  Library PSolver:           yes
  Library BigDFT:            yes
  Main binaries (cluster...):yes
  Minima hopping binary:     no
  atom and pseudo binaries:  no
  User documentation:        yes
  Devel. documentation:      yes / no

  Options:
  Debug version:             no
  With MPI:                  yes
  | Include dir.:
  | Linker flags:
  | Linked libraries:
  | MPI2 support:            yes
  With optimised conv.:      yes
  With Cuda GPU conv.:       no
  | NVidia Cuda Compiler:
  | Cuda flags:
  With OpenCL support:       no
  With dgemmsy support:      no
  With libXC:                yes
  | internal built:          yes
  | include dir.:            -I$(top_builddir)/libXC/src
  With libABINIT:            yes
  | internal built:          yes
  | include dir.:            -I$(top_builddir)/libABINIT/src
  With libPAW:               yes
  | internal built:          yes
  | include dir.:            -I$(top_builddir)/libPAW/src
  With libS_GPU:             no
  | internal built:          no
  | include dir.:
  With ETSF_IO:              no
  | include dir.:           

  Installation paths:
  Source code location:      ..
  Prefix:                    /usr/local
  Exec prefix:               ${prefix}
  Binaries:                  ${exec_prefix}/bin
  Static libraries:          ${exec_prefix}/lib
  Fortran modules:           ${prefix}/include/
  Documentation:             ${datarootdir}/doc/${PACKAGE_TARNAME}
</pre>

<p>
Now, let's look at some most common cases...
</p>


@subsection MKL Use Intel MKL libraries
<p>
The Intel compiler is usually provided with native Lapack and Blas implementations, called the MKL libraries. 
To use them, the option to pass to configure is <tt>--with-ext-linalg</tt>.
</p>
<pre>
  ../configure --with-ext-linalg=&quot;-lmkl_ia32 -lmkl_lapack&quot;
  --with-ext-linalg-path=&quot;-L/opt/intel/mkl72/lib/32&quot;
  --prefix=/home/caliste/usr FC=ifort
</pre>
<p>
In this example, the <tt>--prefix</tt> option is not mandatory and is just provided  to specify the destination directory for installation.
</p>


@subsection MPI MPI compilation
<p>
MPI detection is enable by default and the current Fortran compiler (specified with <tt>FC</tt>) is tested with respect to MPI capabilities. 
MPI and MPI2 are supported. If MPI2 is not available a fallback has been implemented.
</p>
<pre>
../configure FC=mpif90
</pre>
<p>
If the Fortran compiler does not support MPI, a warning message is output by configure script. 
To remove this message, one needs to specify not to detect MPI capabilities with <tt>--disable-mpi</tt> option.
</p>
<p>
One can also pass all the options for the MPI link proceeding using the options <tt>--with-mpi-include</tt>, <tt>--with-mpi-ldflags</tt> 
and <tt>--with-mpi-libs</tt> (not recommended).
</p>


@subsection OpenCL OpenCL compilation
<p>
Here is a example using the Intel Fortran compiler and OpenCL installed in <tt>/applications/cuda-3.2</tt>:
</p>
<pre>
  ../../sources/bigdft-1.5.1/configure FC=ifort
  --enable-opencl --with-ocl-path=/applications/cuda-3.2
</pre>


@subsection CUDA CUDA compilation
<p>
The compilation with CUDA currently required to compile the code with "second underscore". 
It is for the compiler to know how to link C and Fortran sources together. 
Here is a example using the Intel Fortran compiler and CUDA installed in /applications/cuda-2.2:
</p>
<pre>
  ../../sources/bigdft-1.3.0-dev/configure
  FC=ifort FCFLAGS=&quot;-O2 -assume_2underscores&quot;
  CC=icc CXX=icc CXXFLAGS=&quot;-O2 -I/applications/cuda-2.2/include/&quot;
  CFLAGS=&quot;-O2 -I/applications/cuda-2.2/include/&quot;
  --enable-cuda-gpu --with-cuda-path=/applications/cuda-2.2
</pre>

@subsection NetCDF NetCDF I/O
<p>
Here is a example using the Intel Fortran compiler, NetCDF installed in <tt>/applications/netcdf-3.6.3</tt> and ETSF_IO compiled in a home directory:
</p>
<pre>
  ../../sources/bigdft-1.5.1/configure FC=ifort --with-etsf-io
  --with-etsf-io-path=$HOME/usr
  --with-netcdf-path=/applications/netcdf-3.6.3
</pre>



@section Compilation Compilation

@subsection Make Make
<p>
Make the package and create the &#8217;bigdft&#8217; executable, issuing <tt>make</tt>. 
The GNU option <i>-jn</i> is working with whatever value of <i>n</i> (tested up to 16).
</p>

@subsection Install Install
<p>
To install the package, issue <tt>make install</tt>. 
It will copy all files to the specified prefix (see configure). Additionaly, another installation path can be specified by providing a <tt>prefix</tt> option.
</p>
<pre>
make install prefix=$HOME/usr
</pre>
<p>
This example will install, binaries and documentation in <tt>$HOME/usr</tt> whatever the prefix specified at configuration time. 
The destination directory will be created automatically if not existing.
</p>

@subsection Clean Clean
<p>
Clean the source tree of the &#8217;make&#8217; action by <tt>make clean</tt>.
</p>

@subsection Executables The executables
See the file @ref README-MAIN "README" for more explanations.


@section Library Building a library
<p>
To avoid to create the binary executables, use <tt>--disable--build-binary</tt> option.
</p>

<p>
The main subroutine of the BigDFT package is the {call\_bigdft}routine. *
For a given set of input coordinates and input parameters it returns the total energy and the forces acting on the nuclei. 
The <tt>BigDFT.f90</tt> main program calls the {call\_bigdft}routine and can also do a geometry optimization by calling the <tt>geopt</tt> routine 
(which in turn calls again {call\_bigdft}). 
For other standard applications other main programs exist. 
At present main programs to do a vibrational analysis, saddle point search and global optimization have been developed.
Users are encouraged to write their own main programs for specific applications.
</p>


@section Tests Running the tests
<p>
BigDFT is provided with several test cases (that can also be studied as examples). 
They are located in the <tt>tests</tt> directory. To run the tests, after compilation, issue <tt>make check</tt> in this directory.
</p>

<p>
To run tests with MPI support, use the environment variable <tt>run_parallel</tt> as:
</p>
<pre>
export run_parallel='mpirun -np 2'
</pre>
<p>To run tests with OCL support, use the environment variable <tt>run_ocl</tt> as:
</p>
<pre>
export run_ocl='on'
</pre>
*/
