1.1. Linux Ubuntu 20.04 LTS

1.1.1. Disclaimer

PyBEST has been tested on Ubuntu (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, 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 2.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.v2.0.0.tar.gz
tar -xvf pybest.v2.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 a relatively recent versions of the following programs/libraries:

Note

Some of the packages will install others.

system dependencies

sudo apt-get update && sudo apt-get install -y g++ \
python3 \
python3-pip \
python3-venv \
git \
wget \
software-properties-common \
pkg-config \
automake \
autotools-dev \
libboost-dev \
libgmp-dev \
libomp-dev \
libboost-chrono-dev \
libeigen3-dev

Note

We strongly encourage to create a separate python environment, after you install python>=3.9. 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.9 -m venv ${HOME}/.mypybestenv
activate ${HOME}/.mypybestenv/bin/activate
which python3
python3 --version

python dependencies

After preparing fresh python venv (in one of previous steps) all of python-side dependencies can be installed using requirements files
python3.9 -m venv ${HOME}/.mypybestenv
activate ${HOME}/.mypybestenv/bin/activate
which python3
python3 --version
python3 -m pip install -r requirements-build.txt
python3 -m pip install -r requirements.txt
python3 -m pip install -r requirements-dev.txt

1.1.3.1. Installing MKL

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

https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl-download.html?operatingsystem=linux&distributions=aptpackagemanager

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.

Note

Don’t forget to activate the vars for package-manager controlled version. Usually it gets install into /opt/intel

source /opt/intel/oneapi/setvars.sh

1.1.3.2. Installing Libint2

PyBEST requires Psi4-fork of Libint 2.7 to detect correctly in the CMake setup. It’s provided within depends file.

It can be build with pre-configured makefiles in depends (bundled with PyBEST):

cd ${HOME}/my_pybest/pybest.v2.0.0/depends
make libint -j4

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 your MKL_ROOT is properly exported during the installation. 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.v2.0.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. PyBEST and Libchol should be linked to the same BLAS provider.

Note

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

1.1.3.4. Building OpenBLAS from source (optional)

Since not all versions of OpenBLAS have correct CMake targets, which PyBEST requires, it’s also advised to re-compile OpenBLAS in a suitable version if you encounter an error. For convenience, makefile is provided as well

cd ${HOME}/my_pybest/pybest.v2.0.0/depends
make openblas -j4

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

Since PyBEST uses Scikit-Build with CMake, it’s possible to customize options passed to the C-extension building using ordinary CMake flags. However, remember that you might need to modify setup.py _generate_dynamic_cmake_args() for some of them.

Refer to CMake documentation:

hinting desired compiler https://cmake.org/cmake/help/book/mastering-cmake/chapter/Getting%20Started.html#specifying-the-compiler-to-cmake

To hint the location of a suitable Libint2 (and Libchol) location, one can pre-set the following variables that can be put inside rc-files, e.g., ~/.bashrc.

#Exports for PyBEST linked to dependencies within `depends` folder
export LIBINT2_ROOT=$PYBEST_HOME/depends/libint-upstream/installdir
export LIBCHOL_ROOT=$PYBEST_HOME/depends/libchol-upstream/installdir # NOTE: if not set, PyBEST won't try to build against libchol
export PYBEST_USE_MKL=1 # if not set, will default to OpenBLAS

1.1.4.2. Actual build and installation

Building package and install:

cd ${HOME}/my_pybest/pybest.v2.0.0/
python3 -m pip install -r requirements.txt -r requirements-build.txt
python3 -m build --sdist --wheel --no-isolation
python3 -m pip install pybest -f wheelhouse/ --no-index

Note

Build binaries will be linked with RPATH set to depends source shared libraries. If you remove depends, after installing you might need to rebuild them. In case one wants to have system-wide installation, Libint2 and Libchol must be installed in a more permanent location, e.g., /opt

Building extensions with the Libchol library requires pre-compiling with makefiles (section above) (optional, in case environment variables are not set):

Export Libchol location

export LIBCHOL_ROOT=$(pwd)/depends/libchol-upstream/installdir

and then run the sequence of commands posted above again

Note

Mind CMake caches some aspect of configuration between rebuilds if you change options like Libint2 location or BLAS provider, you might need to run ./cleanfiles.sh to purge last compiled configuration before invoking python3 -m build

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:

# activate PyBEST's virtualenv first
python3 -c "import pybest; pybest.test(verbose=3, xdist=True)"

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