..
    : 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, and Libchol
    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 <http://www.fizyka.umk.pl/~pybest/downloads/pybest.v1.3.2.tar.gz>`_ |release|

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.3.2.tar.gz
    tar -xvf pybest.v1.3.2.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.

.. note::

   We strongly encourage to create a separate python environment, after you install ``python>=3.8``.
   This will prevent any damage to system-wide dependencies.
   You will have to activate this environment for the rest of the installation as well as
   for every time you want to use PyBEST.

   .. code-block:: bash

      python3.8 -m venv ${HOME}/.mypybestenv
      activate ${HOME}/.mypybestenv/bin/activate
      which python3
      python3 --version


* ``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.8-dev python3.8-venv
     python3 --version

* ``cmake`` (>=3.18)

  .. code-block:: bash

     sudo apt-get -y install cmake

* ``git`` (>=2.25.1)

  .. code-block:: bash

     sudo apt-get install git
     git --version

* ``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.6.2)

  .. code-block:: bash

     python3 -m pip install pybind11==2.6.2 --user


* ``numpy`` (>=1.18.3)

  .. code-block:: bash

     python3 -m pip install numpy>=1.18.3 --user
     python3 -c "import numpy; print(numpy.version.version)"

* ``scipy`` (>=1.4.1)

  .. code-block:: bash

     python3 -m pip install scipy>=1.4.1 --user
     python3 -c "import scipy; print(scipy.version.version)"


* ``h5py`` (>=2.10.0)

  .. code-block:: bash

     python3 -m pip install h5py --user
     python3 -c "import h5py; print(h5py.version.version)"

* ``setuptools`` (>=46.1.3)

  .. code-block:: bash

     python3 -m pip install setuptools --user

* ``pytest`` (>=5.4.0)

  .. code-block:: bash

     python3 -m pip install pytest>=5.4.0 --user

* ``pylatexenc`` (>=2.7)

  .. code-block:: bash

     python3 -m pip install pylatexenc>=2.7 --user

* ``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"


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/oneapi/base-toolkit/download.html


* Alternatively, the MKL library can be installed using the pip

.. code-block:: bash

   python3 -m pip install mkl-include~=2021.2.0 mkl~=2021.2.0

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

.. note::

   Note that this way mkl library and headers will be directly installed to your python environment
   under ``<venv>/include`` and ``<venv>/lib``, respectively. You must set ``MKLROOT`` or ``MKL_ROOT`` manually.

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

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

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

.. code-block:: bash

   cd ${HOME}/my_pybest/pybest.v1.3.2/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.

.. note::

   PyBEST has been tested with ``libint-2.6`` and ``libint-2.7``
   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.

.. note::

   Make sure that during the installation your ``MKL_ROOT`` is properly exported.
   Libint2 cmake finder is based on `pkgconfig` to this end, one can control the behavior by setting
   ``PKG_CONFIG_PATH=<PATH_TO_YOUR_LIBINT_INSTALL>/lib/pkgconfig``.
   Makefile for ``libchol``, depends on the libint2 build with ``depends/Makefile``.

.. code-block:: bash

   cd ${HOME}/my_pybest/pybest.v1.3.2/depends
   make libchol

.. note::

   In case one wants to customize linkage, with respect to BLAS provider or Libint2, one should
   download the current libchol tarball separately and configure it manually.
   If MKL is not found, cmake configuration will try to find `openblas` and link to it instead of MKL.

.. 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.3.2/
   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:${EIGEN_ROOT}/include/eigen3/Eigen
   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


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/oneapi/mkl/latest
   export MKLROOT=/opt/intel/oneapi/mkl/latest
   export LD_LIBRARY_PATH=${MKL_ROOT}/lib/intel64:${MKL_ROOT}/lib:${HOME}/my_pybest/pybest.v1.3.2/depends/libchol-upstream/installdir/lib:${HOME}/my_pybest/pybest.v1.3.2/depends/libint-upstream/installdir/lib:${LD_LIBRARY_PATH}
   export LIBINT2_PKGCONFIG=${HOME}/my_pybest/pybest.v1.3.2/depends/libint-upstream/installdir/lib/pkgconfig
   export LIBINT2_ROOT=${HOME}/my_pybest/pybest.v1.3.2/depends/libint-upstream/installdir
   export EIGEN_ROOT=/usr
   export INCLUDE=/usr/include:/usr/include/eigen3:${MKLROOT}/include:${INCLUDE}
   # If you want to build pVp or Cholesky-decomposed ERI
   # export PYBEST_ENABLE_PVP=1
   # export PYBEST_ENABLE_CHOLESKY=1

########

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

.. code-block:: bash

    python3 setup.py build_ext -i

* Building extensions with the scalar relativistic integrals (required for the DKH2 Hamiltonian, in case environment variables are not set):

.. code-block:: bash

    export PYBEST_ENABLE_PVP=1
    python3 setup.py build_ext -i

.. note::

   Instead of using environment variables, you can also build the extension with the user-defined option ``--enable-pvp``

* Building extensions with both pVp integrals and the Libchol library (optional, in case environment variables are not set):

.. code-block:: bash

    export PYBEST_ENABLE_PVP=1
    export PYBEST_ENABLE_CHOLESKY=1
    python3 setup.py build_ext -i

.. note::

   Instead of using environment variables, you can also build the extension with the user-defined options ``--enable-pvp --enable-cholesky``

* 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.3.2/src/

    LD_PRELOAD=${MKL_ROOT}/lib/intel64/libmkl_rt.so python3 -m pytest pybest -vs

.. note::

   Alternatively, one can use the `setvar.sh` Intel script to set the correct `LD_PRELOAD`.

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