1.1. Linux Ubuntu 20.04 LTS¶

1.1.1. 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.

1.1.2. Download PyBEST¶

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

version 1.3.0

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

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

1.1.3. 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.

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

gcc (>=9.3.0)

sudo apt-get install gcc g++
g++ --version
gcc --version

python38 (>=3.8.2)

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

cmake (>=3.18)
```
sudo apt-get -y install cmake
```
git (>=2.25.1)
```
sudo apt-get install git
git --version
```

boost (>=1.71.0)

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

pip3 (>=20.0.2)

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

pybind (>=2.6.2)

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

numpy (>=1.18.3)

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

scipy (>=1.4.1)

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

h5py (>=2.10.0)

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

setuptools (>=46.1.3)

python3 -m pip install setuptools --user

pytest (>=5.4.0)

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

pylatexenc (>=2.7)

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

eigen (>=3.3.7-2)

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

automake (>=1:1.16.1)

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

libgmp (>=2:6.2.0)

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

libomp (>=1:10.0-50)

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

libboost-chrono (>=1.71.1)

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

1.1.3.1. 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

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.

1.1.3.2. Installing Libint2¶

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

as a dependency within PyBEST (highly recommended):

cd ${HOME}/my_pybest/pybest.v1.3.0/depends
make libint

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.

1.1.3.3. 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.

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

1.1.4. Building and installing PyBEST¶

1.1.4.1. Overriding default compiler/linker settings¶

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

[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,

#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.0/depends/libchol-upstream/installdir/lib:${HOME}/my_pybest/pybest.v1.3.0/depends/libint-upstream/installdir/lib:${LD_LIBRARY_PATH}
export LIBINT2_PKGCONFIG=${HOME}/my_pybest/pybest.v1.3.0/depends/libint-upstream/installdir/lib/pkgconfig
export LIBINT2_ROOT=${HOME}/my_pybest/pybest.v1.3.0/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

1.1.4.2. Actual build and installation¶

Building extensions:

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):

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):

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:

# 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:

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.

1.1.5. Running the tests¶

To test that PyBEST was installed properly you can run:

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

1.1.6. Building the documentation¶

1.1.6.1. Installing the dependencies¶

doxygen (>=1.8.17)

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

sphinx (>=2.4.3)

sudo pip3 install sphinx

texlive

sudo apt-get install texlive-full

sphinx_rtd_theme

sudo pip3 install sphinx-rtd-theme

1.1.6.2. An actual documentation build¶

The documentation is compiled and viewed as follows:

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

or

make latexpdf; acroread _build/latex/pybestmanual.pdf