1.2. Mac OS X (14.4 or higher)

1.2.1. Disclaimer

This documentation has been tested on macOS 26.0 (Tahoe) using MacPorts (with the exception of OpenBLAS, Libint2, Eigen3, and Libchol libraries) and Xcode up to version 26.4.

Note that PyBEST has also been successfully installed on older macOS versions. If you are using an older version of macOS or a different package manager, some of the instructions below may need to be adjusted.

Note

If you have already installed a Python distribution using a different package manager than MacPorts (such as Anaconda or Miniconda), it may conflict with the version installed via MacPorts. The instructions below assume that no other Python installation is present on your system.

1.2.2. MacPorts

We strongly recommend installing all PyBEST dependencies through MacPorts. The latest version of MacPorts can be downloaded from: [https://www.macports.org/install.php](https://www.macports.org/install.php). This guide has been tested with MacPorts 2.9.1—2.11.6 , but it 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 = python313):

    sudo port list python313

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

    port search python313

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

    sudo port install python313

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

    sudo port select --set python python313

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 https://www.fizyka.umk.pl/~pybest/downloads/pybest.v2.2.0.tar.gz
tar -xvf pybest.v2.2.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.10. The guide below is written for Python 3.13, 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.

python -m venv ${HOME}/.mypybestenv
source ${HOME}/.mypybestenv/bin/activate
which python
python --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 Apple Silicon Macs (M-series chips), OpenBLAS can be used as a drop-in replacement for Intel MKL. It can be installed quickly and easily using MacPorts.

sudo port install OpenBLAS

Note that not all OpenBLAS versions provide the correct CMake targets required by PyBEST. If you encounter CMake-related errors, we recommend recompiling OpenBLAS from source using a compatible version. For convenience, a dedicated Makefile is provided in the repository to simplify this process.

Note

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

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

1.2.4.2. Installing Libint2

PyBEST requires Libint 2.11.2. 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.2.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.11.2 using make.

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

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 (correlated calculations with more than 200 basis functions.

  • compilation

    cd $HOME/my_pybest/pybest.v2.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

For Macs with Apple Silicon (chips M1–M5), 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.2.0/
python -m pip install -r requirements.txt -r requirements-build.txt
python -m build --sdist --wheel --no-isolation
python -m pip install pybest -f dist/ --no-index

To install all requirements, execute in addition

python -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 python -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

In case of issues with the PyBEST core, you should copy the compiled core module to the ./pybest/core/ directory. For example:

cp ../_skbuild/macosx-26.0-arm64-3.13/cmake-build/core.abi3.so ./pybest/core/

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

python -m pip install sphinx

sudo port install texlive

The missing sphinx_rtd_theme should be installed through PIP:

python -m pip install wheel
python -m pip install sphinx_rtd_theme
python -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

Alternatively, you can use the automatic live‑rebuild server provided by sphinx-autobuild. This will rebuild the documentation whenever a file changes and refresh the browser automatically:

cd doc
sphinx-autobuild . _build/html