1.2. Mac OS X (10.14 or higher)

1.2.1. Disclaimer

PyBEST has been tested on Mac OS X 10.14 (Mojave), 10.15 (Catalina), 11.2 (Big Sur), and 12.3 (Monterey) using MacPorts (exceptions are the MKL, Libint2, Eigen3, and Libchol 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.7.1 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 = python39):
```
sudo port list python39
```
searching ports (e.g., port_name = python39):
```
port search python39
```
installing ports (e.g., port_name = python39):
```
sudo port install python39
```
selecting ports (e.g., select python39 as python):
```
sudo port select --set python python39
```

1.2.3. Download PyBEST

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

version 1.2.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.2.0.tar.gz
tar -xvf pybest.v1.2.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 or might be automatically installed due to dependencies.

python39 (>=3.8.2), https://github.com/macports/macports-ports/blob/master/python/py-python-install/Portfile
```
sudo port install python39
```
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 python39
```
cmake (>=3.18), 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
```
automake (>=1.7.9), https://github.com/macports/macports-ports/blob/master/devel/automake/Portfile
```
sudo port install automake
```
numpy (>=1.15.1,<1.20.0), https://github.com/macports/macports-ports/blob/master/python/py-numpy/Portfile
```
sudo port install py39-numpy
sudo port select --set cython cython39
```
distro (>=1.5.0,<1.6.0), https://github.com/macports/macports-ports/blob/master/python/py-distro/Portfile
```
sudo port install py39-distro
```
scipy (>=1.1.0,<1.6.0), https://github.com/macports/macports-ports/blob/master/python/py-scipy/Portfile
```
sudo port install py39-scipy
```
pybind11 (>=2.5.0,<2.7.0), https://github.com/macports/macports-ports/blob/master/devel/pybind11/Portfile
```
sudo port install py39-pybind11
```
h5py (>=2.9.0,<3.1.0), https://github.com/macports/macports-ports/blob/master/python/py-h5py/Portfile
```
sudo port install py39-h5py
```
boost (>=1.71.0), https://github.com/macports/macports-ports/blob/master/devel/boost/Portfile
```
sudo port install boost
```
autoconf (>=2.70), https://github.com/macports/macports-ports/blob/master/devel/autoconf/Portfile
```
sudo port install autoconf
```
setuptools (>=43.0.0), https://github.com/macports/macports-ports/blob/master/python/py-setuptools/Portfile
```
sudo port install py39-setuptools
```
libomp (>=12.0.0), https://github.com/macports/macports-ports/blob/master/lang/libomp/Portfile
```
sudo port install libomp
```
pytest (>=6.2.4,<6.3.0), https://github.com/macports/macports-ports/blob/master/python/py-pytest-html/Portfile
```
sudo port install py39-pytest
sudo port select --set pytest pytest39
```
py39-pip (>=20.02), https://github.com/macports/macports-ports/blob/master/python/py-pip/Portfile
```
sudo port install py39-pip
sudo port select --set pip pip39
```
pylatexenc (>=2.8.0,<2.9.0), https://pypi.org/project/pylatexenc/
```
pip install pylatexenc
```
wget (>=1.21), https://github.com/macports/macports-ports/blob/master/net/wget/Portfile
```
sudo port install wget
```

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

Note

By default the MKL should be installed in /opt/intel/oneapi/mkl/latest.

Note

For Macs with the M1 chip, OpenBlas can be used instead of MKL. The installation can be done very easily using MacPorts.

sudo port install OpenBLAS

1.2.4.2. Installing Eigen3

Eigen3 is a high-level C++ library of template headers for linear algebra, matrix and vector operations, numerical solver and related algoritms.

Eigen3 compilation

cd $HOME/my_pybest/pybest.v1.2.0/depends
make eigen3

Alternatively, you can install Eigen3 using MacPorts,

eigen (>=3.4.0)
```
sudo port install eigen3
```

If you use MacPorts to install Eigen3, the enviroment variable EIGEN_ROOT has to be set to /opt/local.

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

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

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

compilation

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

Note

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

Note

Libchol is not supported in Mac M1.

1.2.5. Building and installing PyBEST

1.2.5.1. Overriding default compiler/linker settings

cd $HOME/my_pybest/pybest.v1.2.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
#
# If depends are used
include_dirs=./depends/eigen3-upstream
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:/opt/local/lib/libomp
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

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

### PyBEST  ##########
export LIBINT2_ROOT=$HOME/my_pybest/pybest.v1.2.0/depends/libint-upstream/installdir
export MKL_ROOT=/opt/intel/oneapi/mkl/latest/
export BOOST_ROOT=/opt/local
export DYLD_LIBRARY_PATH=/opt/intel/oneapi/mkl/latest/lib:$DYLD_LIBRARY_PATH

Note

For Macs with the M1 chip, environment variable for OpenBlas should be used against that of MKL.

export MKL_ROOT=$Path_to_OpenBlas

1.2.5.2. Actual build and installation

Building extensions:

python setup.py build_ext -i

Building extensions with the scalar relativistic integrals (required for the DKH2 Hamiltonian):

python setup.py build_ext -i --enable-pvp

Building extensions with both pVp integrals and the Libchol library (optional):

python setup.py build_ext -i --enable-pvp --enable-cholesky

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

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

sudo port install py39-sphinx
port select --set docutils py39-docutils
port select --set pygments py39-pygments
port select --set sphinx py39-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 wheel
pip install sphinx_rtd_theme
pip install --user --upgrade sphinx breath

Note

For Mac M1, we faced problems with py310- version of sphinx. We strongly recommend using py39 with sphinx or installing sphinx using pip (version 5.0 or later).

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

or

make latexpdf; open _build/latex/pybestmanual.pdf