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

1.1.2. Download PyBEST

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

• version 1.0.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.0.0.tar.gz
tar -xvf pybest.v1.0.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.

• 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 --version
  

• cmake (>=3.16)

  sudo apt-get -y install cmake
  

• git (>=2.25.1)

  sudo apt-get install git
  git --version
  

• hdf5 (>=1.10.4)

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

• 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.5.0)

  sudo pip3 install pybind11==2.5.0
  

• numpy (>=1.18.3)

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

• scipy (>=1.4.1)

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

• boost (>=1.71.0)

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

• h5py (>=2.10.0)

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

• nose (>=1.3.7)

  sudo pip3 install nose
  

• setuptools (>=46.1.3)

  sudo pip3 install setuptools
  

• pytest (>=5.4.0)

  sudo pip3 install pytest
  

• 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"
  

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

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

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/en-us/mkl/choose-download/macos

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

sudo apt install intel-mkl

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

1.1.3.2. Installing Libint2

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

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

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

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. PyBEST will work without it, but we strongly recommend it for large-scale calculations.

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

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.0.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
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,

#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.0/depends/libchol-upstream/installdir/lib:/$HOME/my_pybest/pybest.v1.0.0/depends/libint-upstream/installdir/lib:$LD_LIBRARY_PATH
export LIBINT2_PKGCONFIG=$HOME/my_pybest/pybest.v1.0.0/depends/libint-upstream/installdir/lib/pkgconfig
export LIBINT2_ROOT=$HOME/my_pybest/pybest.v1.0.0/depends/libint-upstream/installdir
export EIGEN_ROOT=/usr
export INCLUDE=/usr/include:/usr/include/eigen3:$MKLROOT/include:$INCLUDE

---

1.1.4.2. Actual build and installation

• Building extensions:

python3 setup.py build_ext -i

• Building extensions with the Libchol library (optional):

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

• 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.0.0/src/

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

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