.. _start_guide:

************
Installation
************

-------------
Prerequisites
-------------
    ===================  =====================================  ==============================
    MPI C++ compiler                                            C++11 and MPI-3 support
    GNU Libtool          https://www.gnu.org/software/libtool
    GNU Autoconf         https://www.gnu.org/software/autoconf  Version 2.69 or newer
    GNU Automake         https://www.gnu.org/software/automake
    Boost C++ Libraries  http://www.boost.org                   Version 1.53.0 or newer
    BLAS                 http://www.netlib.org/blas             Use optimized BLAS
    LAPACK               http://www.netlib.org/lapack           Use optimized LAPACK
    ScaLAPACK            http://www.netlib.org/scalapack        Use optimized ScaLPACK
    ===================  =====================================  ==============================

Intel MKL is strongly recommended for BLAS, LAPACK, and ScaLAPACK (distributed for free for academic users)

----------------------
Downloading the source
----------------------

The simplest approach is to just download and extract the tarball containing the most recent BAGEL release:

.. parsed-literal::
     $ wget https://github.com/nubakery/bagel/archive/v\ |version|\ .tar.gz
     $ tar xvf bagel-\ |version|\ .tar.gz
     $ cd bagel

Alternatively, you can clone the git repository:

.. parsed-literal::
     $ git clone https://github.com/nubakery/bagel.git
     $ cd bagel

The SMITH3 code generator can be downloaded in a similar manner from `the NUBakery GitHub page <https://github.com/nubakery/>`_.

-----------
Build BAGEL
-----------

* Automake ::

     $ glibtoolize (or, libtoolize)
     $ aclocal
     $ autoconf
     $ autoheader
     $ automake -a

* Create an object directory ::

    $ mkdir obj
    $ cd obj

* Configure

  A minimal set of configure options is ::

    $ export BOOST_ROOT=/path/to/boost
    $ export LD_LIBRARY_PATH=$BOOST_ROOT/lib:$LD_LIBRARY_PATH

    $ ../configure --enable-mkl --with-boost=$BOOST_ROOT

  Configure options:
     | ``--with-mpi=value``  turns on MPI, where "value" can be "mvapich", "intel", or "openmpi".
                             However, Open MPI is not recommended.
     | ``--enable-mkl``  turns on MKL extensions, such as efficient matrix transposition. MKL libraries are automatically detected.
     | ``--with-boost=/path/to/boost`` specifies the BOOST library to be used.
     | ``--disable-scalapack``  will disable the use of ScaLapack (parallel Lapack) which is not recommended.
     | ``--disable-smith``  will disable the code generated by SMITH which is not recommended.
     | ``--with-include``  can be used to specifically include paths.
     | ``--with-libxc`` turns on the interface to libxc.
     | ``CXXFLAGS=-DNDEBUG`` deactivates the debugging mode. **It is absolutely essential to specify this for release builds**.
     | ``CXXFLAGS=-DCOMPILE_J_ORB`` allows the inclusion of *j*-type atomic basis functions.

  Example (Release build on the Shiozaki group's cluster) ::

       $ export BOOST_ROOT=/usr/local/boost/boost_1_64_0_gcc-7.1.0
       $ export LD_LIBRARY_PATH=$BOOST_ROOT/lib:$LD_LIBRARY_PATH

       $ ../configure CXXFLAGS="-DNDEBUG -O3 -mavx" --enable-mkl --with-boost=$BOOST_ROOT --with-mpi=intel

* Compile ::

    $ make -j4
    $ make install

* Test run ::

    $ BAGEL path_to_bagel/test/benzene_svp_mp2.json

  Also there is a suite of test programs. To run this, in obj ::

    $ cd bagel/obj
    $ make check 
    $ cd src
    $ ./TestSuite --log_level=all

  One of the tests (ASD-DMRG) is meant to fail.

* Additional Notes

  * Configuring without MKL

    | If MKL is not available, the path to cblas headers may need to be included as a configure option
           (e.g., '--with-include=-I/usr/path/to/cblas'). One may also add "LDFLAGS=-lcblas" as an option.
      Furthermore, if relativistic calculations fail without MKL, users may consider reconfiguring and recompiling with -DZDOT_RETURN in CXXFLAGS.
  
  * Compiling on small machines

    | Some files in BAGEL require several GB of RAM to compile.  This is generally not a problem for clusters, but on personal computers the 
           compilation will occasionally fail.  Compiling with one thread (make -j1) and not using -DCOMPILE_J_ORB may help.  




