1.2. Mac OS X (10.14 or higher)¶

1.2.1. Disclaimer¶

PyBEST has been tested on Mac OS X 10.14 (Mojave) and 10.15 (Catalina) using MacPorts (exceptions are MKL, Libint2, and HighFive libraries). If you are using an older version of OS X or other package managers, some of the instructions below may not work.

Note

If you have already installed a Python distribution (with another package manager than MacPorts, such as Anaconda or Canopy), it may interfere with the one installed through MacPorts. The instructions below assume that no such other installation of Python is present.

1.2.2. MacPorts¶

We strongly recommend that you install all of the packages required by PyBEST through MacPorts. The latest version of MacPorts can be downloaded from the web: https://www.macports.org/install.php. This guide has been tested using MacPorts 2.6.3 but should also work with older versions.

1.2.2.1. A quick tour of MacPorts¶

Here are some basic MacPorts commands:

checking port version:
```
port version
```
updating ports (recommended!):
```
sudo port -v selfupdate
```
upgrading ports:
```
sudo port upgrade outdated
```
finding ports (e.g, port_name = python38):
```
sudo port list python38
```
searching ports (e.g, port_name = python38):
```
port search python38
```
installing ports (e.g, port_name = python38):
```
sudo port install python38
```
selecting ports (e.g, select python38 as python):
```
sudo port select --set python python38
```

1.2.3. 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.2.4. Dependencies for building, installing, and testing PyBEST¶

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.

python38 (>=3.8.2), https://github.com/macports/macports-ports/blob/master/lang/python38/Portfile
```
sudo port install python38
```
python3_select (>=0.0), https://github.com/macports/macports-ports/blob/master/sysutils/python3_select/Portfile
```
sudo port install python3_select
sudo port select --set python python38
```
cmake (>=3.16), https://github.com/macports/macports-ports/blob/master/devel/cmake/Portfile
```
sudo port install cmake
```
git (>=2.25.1), https://github.com/macports/macports-ports/blob/master/devel/git/Portfile
```
sudo port install git
sudo port select --set python2 python27
```
py38-numpy (>=1.18.1), https://github.com/macports/macports-ports/blob/master/python/py-numpy/Portfile
```
sudo port install py38-numpy
port select --set cython cython38
```
py38-scipy (>=1.4.1), https://github.com/macports/macports-ports/blob/master/python/py-scipy/Portfile
```
sudo port install py38-scipy
```
boost (>=1.71.0), https://github.com/macports/macports-ports/blob/master/devel/boost/Portfile
```
sudo port install boost
```
py38-pip (>=20.0.2), https://github.com/macports/macports-ports/blob/master/python/py-pip/Portfile
```
sudo port install py38-pip
```
py38-h5py (>=2.10.0), https://ports.macports.org/port/py38-h5py/summary
```
sudo port install py38-h5py
h5cc --showconfig
```
pip_select (>=0.1), https://github.com/macports/macports-ports/blob/master/python/pip_select/Portfile
```
sudo port install pip_select
```
py38-nose (>=1.3.7), https://github.com/macports/macports-ports/blob/master/python/py-nose/Portfile
```
sudo port install py38-nose
```
py38-setuptools (>=43.0.0), https://github.com/macports/macports-ports/blob/master/python/py-setuptools/Portfile
```
sudo port install py38-setuptools
```
eigen3 (>=3.3.7), https://github.com/macports/macports-ports/blob/master/math/eigen3/Portfile
```
sudo port install eigen3
```
gcc9 (>=9.2.0), https://github.com/macports/macports-ports/blob/master/lang/gcc9/Portfile
```
sudo port install gcc9
```
gcc_select (>=0.1), https://github.com/macports/macports-ports/blob/master/sysutils/gcc_select/Portfile
```
sudo port install gcc_select
sudo port select --set gcc gcc-nm-mp-9
```
py38-pip (>=20.02), https://ports.macports.org/port/py38-pip/summary
```
sudo port install py38-pip
sudo port select --set pip pip38
```
h5py (>=2.10), http://docs.h5py.org/en/stable/build.html
```
pip3 install h5py
```
pytest (>=5.4.0), https://pypi.org/project/pytest/
```
pip3 install pytest
```

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.2.4.1. Installing MKL¶

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

https://software.intel.com/en-us/mkl/choose-download/macos

1.2.4.2. Installing Libint2¶

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

as a dependency within PyBEST (highly recommended):

cd $HOME/my_pybest/pybest.v1.0.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 using a clang compiler and with 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.2.4.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.2.5. Building and installing PyBEST¶

1.2.5.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 to your specific setup. An example configuration file based on OS X Catalinia (10.15.3) 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
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
library_dirs=${HDF5_ROOT}/lib
libraries=hdf5

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

### PyBEST  ##########
export LIBINT2_ROOT=/$HOME/my_pybest/pybest.v1.0.0/depends/libint-upstream/installdir
export EIGEN_ROOT=/opt/local
export HIGHFIVE_ROOT="path-to-your-HighFive"/highFive/HighFive
export MKL_ROOT=/opt/intel/compilers_and_libraries_2020.0.166/mac/mkl
export HDF5_ROOT=/opt/local
export BOOST_ROOT=/opt/local
export DYLD_LIBRARY_PATH=/opt/intel/mkl/lib:$DYLD_LIBRARY_PATH

1.2.5.2. Actual build and installation¶

Building extensions:

python setup.py build_ext -i

Building extensions with the Libchol library (optional):

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

Install PyBEST:

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

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

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

1.2.6. Running the tests¶

To test that PyBEST was installed properly you can run:

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

python -m pytest pybest -vs

1.2.7. Building the documentation¶

1.2.7.1. Installing the dependencies with MacPorts and PIP¶

Most can be installed directly with MacPorts. The following list of ports is recommended:

doxygen (>=1.8.17), https://www.macports.org/ports.php?by=library&substr=doxygen

sudo port install doxygen

py38-sphinx (>=2.4.3), https://github.com/macports/macports-ports/blob/master/python/py-sphinx/Portfile

sudo port install py38-sphinx
port select --set pygments py38-pygments
port select --set sphinx py38-sphinx

texlive (>=2019), https://github.com/macports/macports-ports/blob/master/tex/texlive/Portfile

sudo port install texlive

The missing sphinx_rtd_theme should be installed through PIP:

pip install sphinx_rtd_theme
pip install --user --upgrade sphinx breath

1.2.7.2. An actual documentation build¶

The documentation is compiled and viewed as follows:

cd doc; make html; open -a safari _build/html/index.html