1.2. Mac OS X (14.4 or higher)

1.2.1. Disclaimer

This documentation of PyBEST has been tested on Mac OS X 14.4.1 (Sonoma) using MacPorts (exceptions are the OpenBLAS, Libint2, Eigen3, and Libchol libraries) and Xcode 15 (https://developer.apple.com/xcode/). Note, however, that PyBEST has been successfully installed on Mac OS X 13.4+. If you are using an older version of OS X or other package managers, some instructions below may need to be revised.

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 installing all of the packages PyBEST requires 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.9.1 but should also work with older versions.

1.2.2.1. A quick tour of MacPorts

Here are some basic MacPort 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

doc/user_download_and_install_mac.rst 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.v2.0.0.tar.gz
tar -xvf pybest.v2.0.0.tar.gz

1.2.4. Dependencies for building, installing, and testing PyBEST

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 or might be automatically installed due to dependencies.

Note

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

Note

The remaining Python site-packages will be installed as required using pip. If you wish to install them using MacPorts, ensure version compatibility.

Note

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

1.2.4.1. Installing MKL/OpenBLAS

The installation of the 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. MKL only works for x86_64 Intel Processors. For Apple Silicone, we support OpenBLAS, since SciPy doesn’t support Accelerate (it might in the future)

Note

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

sudo port install OpenBLAS

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

Note

This installation guide has been tested for the OpenBLAS build shipped with this version of PyBEST.

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

1.2.4.2. Installing Eigen3

Note

This installation guide has been tested for the Eigen3 library provided by MacPorts.

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

  • Eigen3 compilation

    cd $HOME/my_pybest/pybest.v2.0.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 environment variable EIGEN_ROOT has to be set to /opt/local.

1.2.4.3. 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 built with pre-configured makefiles in depends (bundled with PyBEST):

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

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.

Note

PyBEST has been tested with libint-2.7 using make.

You should 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.v2.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.

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
# for instance, cblas.h (built from depends) or cblas_openblas.h (MacPorts installation)
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

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:

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_OPENBLAS=1

In addition, other variables may be required to be set for a successful CMake build. Below, a summary of all possible environment variables is listed, which need to be set in case of build problems.

# Paths for libint (MacPorts installation)
export BOOST_ROOT=/opt/local
export EIGEN_ROOT=/opt/local
# Paths for libchol
export OpenBLAS=/path/to/your/blas/directory
# assuming own build (no MacPorts installation)
export OpenBLAS_INCLUDE_FILE=cblas.h
export OpenBLAS_DIR=/path/to/your/blas/directory/lib/cmake/OpenBLAS
export LIBINT2_ROOT=/path/to/your/libint/directory
export LIBINT2_PKGCONFIG=/path/to/your/libint/directory/lib/pkgconfig
export Libint2_DIR=/path/to/your/libint/directory/lib/cmake/libint2
# Paths for PyBEST
export LIBCHOL_ROOT=/path/to/your/libchol/directory
export PYBEST_USE_OPENBLAS=1

1.2.5.2. Actual build and installation

To build PyBEST, all remaining Python site-packages have to be installed. You can either install only the requirements to build and run PyBEST or also all requirements used for building the docs and source-code development. Below, we install only the build requirements.

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 dist/ --no-index

To install all requirements, execute in addition

python3 -m pip install -r requirements-dev.txt -r requirements-docs.txt

Note

Build binaries will be linked with RPATH set to depends source shared libraries. If you remove depends, ``after installing them, 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

When executing PyBEST, problems related to loading the dynamically linked libraries may arise. This can be solved by telling the dynamic link loader where to search for the dynamic shared libraries PyBEST was linked against,

# Export paths to libomp, libchol, openblas, libint
export DYLD_LIBRARY_PATH=/opt/local/lib/libomp:/path/to/your/libchol/directory/lib:/path/to/your/openblas/directory/lib://path/to/your/libint/directory/lib:$DYLD_LIBRARY_PATH

1.2.6. Running the tests

Since parts of PyBEST (like libchol) have been linked against OpenBLAS and OpenMP, there might be a conflict with OpenBLAS/OpenMP multi-threading. If not properly set, PyBEST/libchol will not run on multiple threads. This behavior can be adjusted by setting the proper number of threads for OpenBLAS and OpenMP:

# We allow at most 9 threads to be used. You can adjust this number to the resources you have available
export OPENBLAS_NUM_THREADS=9 OMP_NUM_THREADS=1

To test that PyBEST was installed properly you can run:

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

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

  • sphinx (>=2.4.3)

python3 -m pip install sphinx

sudo port install texlive

The missing sphinx_rtd_theme should be installed through PIP:

python3 -m pip install wheel
python3 -m pip install sphinx_rtd_theme
python3 -m pip install --upgrade -r requirements-docs.txt

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