..
    : PyBEST: Pythonic Black-box Electronic Structure Tool
    : Copyright (C) 2016-- The PyBEST Development Team
    :
    : This file is part of PyBEST.
    :
    : PyBEST is free software; you can redistribute it and/or
    : modify it under the terms of the GNU General Public License
    : as published by the Free Software Foundation; either version 3
    : of the License, or (at your option) any later version.
    :
    : PyBEST is distributed in the hope that it will be useful,
    : but WITHOUT ANY WARRANTY; without even the implied warranty of
    : MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    : GNU General Public License for more details.
    :
    : You should have received a copy of the GNU General Public License
    : along with this program; if not, see <http://www.gnu.org/licenses/>
    :
    : --

Linux Ubuntu 20.04 LTS
######################

Disclaimer
==========

    PyBEST has been tested on Ubuntu (18.04 LTS and 20.04 LTS) using the
    built-in package management system. Exceptions are the MKL, Libint2, Libchol, 
    and HighFive libraries. 

.. note::

    If you have already installed a Python distribution such as Anaconda or 
    Canopy, it may interfere with the one installed through the package management 
    system. The instructions below assume that you start with a clean system installation.


Download PyBEST
===============

The latest stable source code release of PyBEST can be downloaded here:

    * `version v1.0.1 <http://www.fizyka.umk.pl/~pybest/downloads/pybest.v1.0.1.tar.gz>`_

Choose a suitable directory, e.g. ``$HOME/my_pybest``, and download the above mentioned source and unpack:

.. code-block:: bash

    mkdir -p $HOME/my_pybest; cd $HOME/my_pybest
    wget http://www.fizyka.umk.pl/~pybest/downloads/pybest.v1.0.1.tar.gz
    tar -xvf pybest.v1.0.1.tar.gz

Dependencies for building, installing, and testing PyBEST
=========================================================

.. note::

    This part is solely based on the Ubuntu 20.04 LTS. For older versions you
    might need to adjust some of the dependencies to newer ones. 

To compile and test PyBEST, you need to install relatively recent
versions of the following programs/libraries:

.. note::

   Some of the packages will install others.

* ``gcc`` (>=9.3.0)

  .. code-block:: bash 
 
     sudo apt-get install gcc g++
     g++ --version
     gcc --version

* ``python38`` (>=3.8.2)

  .. code-block:: bash 

     sudo apt-get install python3.8
     python3 --version   

* ``cmake`` (>=3.16)

  .. code-block:: bash

     sudo apt-get -y install cmake

* ``git`` (>=2.25.1)

  .. code-block:: bash

     sudo apt-get install git
     git --version

* ``hdf5`` (>=1.10.4)

  .. code-block:: bash

     sudo apt-get install -y libhdf5-dev
     h5cc -showconfig

* ``boost`` (>=1.71.0)

  .. code-block:: bash

     sudo apt-get install libboost-dev
     dpkg -s libboost-dev | grep 'Version'   

* ``pip3`` (>=20.0.2)

  .. code-block:: bash

     sudo apt-get install python3-pip
     pip3 --version

* ``pybind`` (>=2.5.0)

  .. code-block:: bash

     sudo pip3 install pybind11==2.5.0


* ``numpy`` (>=1.18.3)

  .. code-block:: bash

     sudo pip3 install numpy
     python3 
     import numpy
     numpy.version.version
     exit()

* ``scipy`` (>=1.4.1)

  .. code-block:: bash

     sudo pip3 install scipy
     python3 
     import scipy
     scipy.version.version
     exit()


* ``h5py`` (>=2.10.0)

  .. code-block:: bash

     sudo pip3 install --no-binary=h5py h5py
     python3 
     import h5py
     h5py.version.version
     exit()

* ``nose`` (>=1.3.7)

  .. code-block:: bash

     sudo pip3 install nose

* ``setuptools`` (>=46.1.3)

  .. code-block:: bash

     sudo pip3 install setuptools 

* ``pytest`` (>=5.4.0)

  .. code-block:: bash

     sudo pip3 install pytest
   
* ``pylatexenc`` (>=2.7)

  .. code-block:: bash
    
    sudo pip3 install pylatexenc

* ``eigen`` (>=3.3.7-2)

  .. code-block:: bash

     sudo apt-get install libeigen3-dev
     dpkg -s libeigen3-dev| grep "Version"
     
* ``automake`` (>=1:1.16.1)

  .. code-block:: bash

     sudo apt-get install automake
     dpkg -s automake| grep "Version"

* ``libgmp`` (>=2:6.2.0)

  .. code-block:: bash

     sudo apt-get install libgmp-dev
     dpkg -s libgmp-dev| grep "Version"

* ``libomp`` (>=1:10.0-50)

  .. code-block:: bash

     sudo apt-get install libomp-dev
     dpkg -s libomp-dev| grep "Version"

* ``libboost-chrono`` (>=1.71.1)

  .. code-block:: bash
     
     sudo apt-get install libboost-chrono-dev
     dpkg -s libboost-chrono-dev | grep "Version"

* ``HighFive`` (>=2.2), https://github.com/BlueBrain/HighFive.git

  Please note that headers are enough (no CMake is required). 

  .. code-block:: bash

     mkdir ~/HighFive
     export HIGHFIVE_VER=2.2
     cd ~/HighFive; mkdir ${HIGHFIVE_VER}
     cd ${HIGHFIVE_VER}; 
     git clone https://github.com/BlueBrain/HighFive.git 



Installing MKL
--------------

* The installation of the Intel MKL library is pretty straightforward and can be found here:

https://software.intel.com/content/www/us/en/develop/tools/math-kernel-library/choose-download/linux.html


* Alternatively, the MKL library can be installed using the package manager

.. code-block:: bash

   sudo apt install intel-mkl

Please note that in this case, the path to MKL will be different. 

Installing Libint2
------------------

There are two ways of installing the Libint2 library (>=2.6.0):

1. as a dependency within PyBEST (**highly recommended**):

.. code-block:: bash

   cd $HOME/my_pybest/pybest.v1.0.1/depends
   make libint   


2. as a standalone package

* A recent version of Libint2 can be found here:

https://github.com/evaleev/libint

To properly work with PyBEST, Libint2 has to be compiled within the ``C++11`` 
standard. The maximum angular momentum should be set to 7.
Make sure that during the installation your ``MKL_ROOT`` is properly exported. 

.. note::

   PyBEST has been tested with ``libint-2.6`` and ``libint-2.7-beta`` 
   using ``make``.

Installing Libchol (optional)
-----------------------------

The Libchol library allows you to make use of the Cholesky decomposition technique
in the evaluation of two-electron integrals [aquilante2011]_. PyBEST will work without it, but 
we strongly recommend it for large-scale calculations. 

.. code-block:: bash

   cd $HOME/my_pybest/pybest.v1.0.1/depends
   make libchol   

.. note::

   You might need to set up some environmental variables at this point. 
   Examples are provided in the next section. 

Building and installing PyBEST
==============================

Overriding default compiler/linker settings
-------------------------------------------

.. code-block:: bash

   cd $HOME/my_pybest/pybest.v1.0.1/
   cp setup.cfg.ini setup.cfg  

Adopt the existing `setup.cfg` file to your specific setup.  
An example configuration file based on Ubuntu 20.04 LTS is shown below:

.. code-block:: bash

   [libint2]
   # If both paths have not been exported, you need to define them
   #include_dirs=/usr/include/
   #library_dirs=/usr/lib/
   #
   # If enviroment variables are defined
   include_dirs=${LIBINT2_ROOT}/include
   library_dirs=${LIBINT2_ROOT}/lib
   libraries=int2


   [eigen]
   # If the path to the include directory is not exported, you need to define it
   #include_dirs=/usr/include/eigen3
   #
   # If enviroment variables are defined
   include_dirs=${EIGEN_ROOT}/include/eigen3:${EIGEN_ROOT}/include
   libraries=eigen3


   [libchol]
   # To link to the shared libraries, uncomment below. Do not forget to update
   # the LD_LIBRARY_PATH
   # For Mac OS and Clang, you also need to add the path to omp.h (e.g.,
   # /opt/local/include/libomp or you build with additional
   # CPPFLAGS='-I/opt/local/include/libomp -lomp')
   # For intel and gnu compilers
   include_dirs=./depends/libchol-upstream/installdir/include
   library_dirs=./depends/libchol-upstream/installdir/lib
   libraries=chol
   # For Clang
   #include_dirs=./depends/libchol-upstream/installdir/include:/opt/local/include/libomp
   #library_dirs=./depends/libchol-upstream/installdir/lib
   #libraries=chol:omp


   [blas]
   # If both paths have not been exported, you need to define them
   #include_dirs=/usr/include/
   #library_dirs=/usr/lib/
   #
   # If enviroment variables are defined
   include_dirs=${MKL_ROOT}/include
   library_dirs=${MKL_ROOT}/lib:${MKL_ROOT}/lib/intel64
   libraries=mkl_rt


   [boost]
   # If the path to the include directory is not exported, you need to define it
   #include_dirs=/usr/include/boost
   #
   # If enviroment variables are defined
   include_dirs=${BOOST_ROOT}/include:${BOOST_ROOT}/include/boost
   libraries=boost


   [highfive]
   # If both paths have not been exported, you need to define them
   #include_dirs=/usr/include/
   #
   # If enviroment variables are defined
   include_dirs=${HIGHFIVE_ROOT}/include
   libraries=highfive


   [hdf5]
   # If both paths have not been exported, you need to define them
   #include_dirs=/usr/include/
   #library_dirs=/usr/lib/
   #
   # If enviroment variables are defined
   include_dirs=${HDF5_ROOT}/include:${HDF5_ROOT}/include/hdf5/serial
   library_dirs=${HDF5_ROOT}/lib
   libraries=hdf5


where the evironmental variables are defined in, for instance, ``~/.bashrc``, 

.. code-block:: bash

   #Exports for PyBEST
   export BOOST_ROOT=/usr:/usr/include/boost
   export MKL_ROOT=/opt/intel/mkl
   export MKLROOT=/opt/intel/mkl
   export HIGHFIVE_ROOT=$HOME/HighFive/HighFive
   export HDF5_ROOT=/usr #:/usr/include/hdf5/serial/
   export LD_LIBRARY_PATH=/opt/intel/mkl/lib/intel64:/opt/intel/mkl/lib:$HOME/my_pybest/pybest.v1.0.1/depends/libchol-upstream/installdir/lib:/$HOME/my_pybest/pybest.v1.0.1/depends/libint-upstream/installdir/lib:$LD_LIBRARY_PATH
   export LIBINT2_PKGCONFIG=$HOME/my_pybest/pybest.v1.0.1/depends/libint-upstream/installdir/lib/pkgconfig
   export LIBINT2_ROOT=$HOME/my_pybest/pybest.v1.0.1/depends/libint-upstream/installdir
   export EIGEN_ROOT=/usr
   export INCLUDE=/usr/include:/usr/include/eigen3:$MKLROOT/include:$INCLUDE

########                                                                        

Actual build and installation
-----------------------------
* Building extensions:

.. code-block:: bash

    python3 setup.py build_ext -i

* Building extensions with the Libchol library (optional): 

.. code-block:: bash

    python3 setup.py build_ext -i --enable-cholesky=1

* Install PyBEST:

.. code-block:: bash

   # using pip
   pip3 install . --user
   # OR using setup.py
   python3 setup.py install --prefix=/path/to/your/installdir

If you do not install PyBEST as a local site package of python (using
``pip3 install . --user``, you need to set some environment variables to use PyBEST. Add the following to 
your ``~/.bashrc``:

.. code-block:: bash

   export PATH=/path/to/your/installdir/bin:$PATH

If need be, you have to update your ``PYTHONPATH`` as well. We thus recommend the
installation option using `pip3`.

Running the tests
=================

To test that PyBEST was installed properly you can run:

.. code-block:: bash

    cd $HOME/my_pybest/pybest.v1.0.1/src/

    LD_PRELOAD=/opt/intel/mkl/lib/intel64/libmkl_rt.so python3 -m pytest pybest -vs


Building the documentation
==========================

Installing the dependencies 
---------------------------

* ``doxygen`` (>=1.8.17)

.. code-block:: bash

   sudo apt-get install doxygen
   dpkg -s doxygen |grep "Version"
   
* ``sphinx`` (>=2.4.3)

.. code-block:: bash 
  
     sudo pip3 install sphinx

* ``texlive``

.. code-block:: bash

   sudo apt-get install texlive-full  
     
* ``sphinx_rtd_theme``

.. code-block:: bash

    sudo pip3 install sphinx-rtd-theme

An actual documentation build
-----------------------------

The documentation is compiled and viewed as follows:

.. code-block:: bash

    cd doc; make html; firefox _build/html/index.html

or 

.. code-block:: bash

    make latexpdf; acroread _build/latex/pybestmanual.pdf