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 the MKL, Libint2, Libchol, 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:

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.1.tar.gz
tar -xvf pybest.v1.0.1.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.

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

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

cd $HOME/my_pybest/pybest.v1.0.1/depends
make libint

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

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.1/
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:/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

[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.1/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.1/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:

sudo port install doxygen

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

or

make latexpdf; open _build/latex/pybestmanual.pdf