1.2. Mac OS X (12.3 or higher)

1.2.1. Disclaimer

PyBEST has been tested on Mac OS X 13.4 (Ventura) 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.8.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 = python310):

    sudo port list python310

  • searching ports (e.g., port_name = python310):

    port search python310

  • installing ports (e.g., port_name = python310):

    sudo port install python310

  • selecting ports (e.g., select python310 as python):

    sudo port select --set python python310

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

Note

PyBEST requires at least Python 3.8. The guide below is written for Python 3.10, while the minimum supported versions are mentioned in parentheses.

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 or newer, 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.3.2/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):

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

cd $HOME/my_pybest/pybest.v1.3.2/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 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.3.2/depends
make libchol

Note

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

Note

For Macs with the M1 chip or newer, we assume that you use OpenBLAS and libomp installed via macports. OpenBLAS is shipped with a cblas_openblas.h header file. In order to use a different BLAS installation, you need to export environmental variables:

export OpenBLAS=/path/to/your/blas/directory
export OpenBLAS_INCLUDE_FILE=name_of_your_cblas.h

If no environmental variables are provided, OpenBLAS_INCLUDE_FILE is defaulted to cblas_openblas.h. For macports’ OpenBLAS, we recommend to use

export OpenBLAS=/opt/local

1.2.5. Building and installing PyBEST

1.2.5.1. Overriding default compiler/linker settings

cd $HOME/my_pybest/pybest.v1.3.2/
cp setup.cfg.ini setup.cfg

Adopt the existing setup.cfg to your specific setup. An example configuration file based on OS X Ventura (13.4) 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:${EIGEN_ROOT}/include/eigen3/Eigen
#
# 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
# If you have Intel chips/use the MKL library, uncomment the following lines
# 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 evironment variables are defined in, for instance, ~/.profile,

### PyBEST  ##########
export LIBINT2_ROOT=$HOME/my_pybest/pybest.v1.3.2/depends/libint-upstream/installdir
# If you have an M1 chip or newer, use macports' OpenBLAS
export MKL_ROOT=/opt/local
export OpenBLAS=/opt/local
export BOOST_ROOT=/opt/local
# If you use the MKL library, use the following
# export MKL_ROOT=/opt/intel/oneapi/mkl/latest/
# export DYLD_LIBRARY_PATH=/opt/intel/oneapi/mkl/latest/lib:$DYLD_LIBRARY_PATH
# If you installed libchol (and/or libint) as PyBEST dependency
# export DYLD_LIBRARY_PATH=/path-to-pybest/depends/libint-upstream/installdir/lib:/path-to-pybest/depends/libchol-upstream/installdir/lib:$DYLD_LIBRARY_PATH
# If you want to build pVp or Cholesky-decomposed ERI
# export PYBEST_ENABLE_PVP=1
# export PYBEST_ENABLE_CHOLESKY=1

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, in case environment variables are not set):

export PYBEST_ENABLE_PVP=1
python setup.py build_ext -i

Note

Instead of using environment variables, you can also build the extension with the user-defined option --enable-pvp

  • Building extensions with both pVp integrals and the Libchol library (optional, in case environment variables are not set):

export PYBEST_ENABLE_PVP=1
export PYBEST_ENABLE_CHOLESKY=1
python setup.py build_ext -i

Note

Instead of using environment variables, you can also build the extension with the user-defined options --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.3.2/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 wheel
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