..
    : PyBEST: Pythonic Black-box Electronic Structure Tool
    : Copyright (C) 2016-- The PyBEST Development Team
    :
    : This file is part of PyBEST.
    :
    : PyBEST is free software; you can redistribute it and/or
    : modify it under the terms of the GNU General Public License
    : as published by the Free Software Foundation; either version 3
    : of the License, or (at your option) any later version.
    :
    : PyBEST is distributed in the hope that it will be useful,
    : but WITHOUT ANY WARRANTY; without even the implied warranty of
    : MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    : GNU General Public License for more details.
    :
    : You should have received a copy of the GNU General Public License
    : along with this program; if not, see <http://www.gnu.org/licenses/>
    : --

Mac OS X (14.4 or higher)
#########################

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.

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.

A quick tour of MacPorts
------------------------

Here are some basic MacPort commands:

* checking port version:

  .. code-block:: bash

      port version

* updating ports (recommended!):

  .. code-block:: bash

      sudo port -v selfupdate

* upgrading ports:

  .. code-block:: bash

      sudo port upgrade outdated

* finding ports (e.g., port_name = python313):

  .. code-block:: bash

      sudo port list python313

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

  .. code-block:: bash

      port search python313

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

  .. code-block:: bash

      sudo port install python313

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

  .. code-block:: bash

      sudo port select --set python python313

Download PyBEST
===============
doc/user_download_and_install_mac.rst
The latest stable source code release of PyBEST can be downloaded here:

    * `version <https://www.fizyka.umk.pl/~pybest/downloads/pybest.v2.2.0.tar.gz>`_ |release|

Choose a suitable directory, e.g., ``$HOME/my_pybest``, and download the above mentioned source and unpack:

.. code-block:: bash

    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

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.

* ``python313`` (>=3.10.0), https://github.com/macports/macports-ports/blob/master/python/py-python-install/Portfile

  .. code-block:: bash

     sudo port install python313
     sudo port select --set python python313

* ``py313-pip`` (>=20.02), https://github.com/macports/macports-ports/blob/master/python/py-pip/Portfile

  .. code-block:: bash

     sudo port install py313-pip
     sudo port select --set pip pip313

.. note::

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


* ``libomp`` (>=12.0.0), https://github.com/macports/macports-ports/blob/master/lang/libomp/Portfile

  .. code-block:: bash

     sudo port install libomp

* ``boost`` (>=1.71.0), https://github.com/macports/macports-ports/blob/master/devel/boost/Portfile

  .. code-block:: bash

     sudo port install boost

* ``automake`` (>=1.7.9), https://github.com/macports/macports-ports/blob/master/devel/automake/Portfile

  .. code-block:: bash

     sudo port install automake

* ``autoconf`` (>=2.70), https://github.com/macports/macports-ports/blob/master/devel/autoconf/Portfile

  .. code-block:: bash

     sudo port install autoconf

* ``py313-build`` (>=1.4.3), https://ports.macports.org/port/py313-build/

  .. code-block:: bash

     sudo port install py313-build

* ``cmake`` (>=3.18), https://github.com/macports/macports-ports/blob/master/devel/cmake/Portfile

  .. code-block:: bash

     sudo port install cmake

* ``eigen3`` (>=3.4.0), https://ports.macports.org/port/eigen3/

  .. code-block:: bash

     sudo port install eigen3


* ``wget`` (>=1.21), https://github.com/macports/macports-ports/blob/master/net/wget/Portfile

  .. code-block:: bash

   sudo port install wget


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

   .. code-block:: bash

      python -m venv ${HOME}/.mypybestenv
      source ${HOME}/.mypybestenv/bin/activate
      which python
      python --version


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.

.. code-block:: bash

   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.

.. code-block:: bash

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

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

.. code-block:: bash

   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.

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

  .. code-block:: bash

     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:

.. code-block:: bash

    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

.. code-block:: bash

    export OpenBLAS=/opt/local

Building and installing PyBEST
==============================

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:

* hinting desired compiler https://cmake.org/cmake/help/book/mastering-cmake/chapter/Getting%20Started.html#specifying-the-compiler-to-cmake

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

.. code-block:: bash

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

.. code-block:: bash

   # 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


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.

.. code-block:: bash

   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

.. code-block:: bash

   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

.. code-block:: bash

    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,

.. code-block:: bash

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

.. code-block:: bash

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


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:

.. code-block:: bash

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

.. code-block:: bash

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


Building the documentation
==========================

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

.. code-block:: bash

   sudo port install doxygen

* ``sphinx`` (>=2.4.3)

.. code-block:: bash

   python -m pip install sphinx

* ``texlive`` (>=2019), https://github.com/macports/macports-ports/blob/master/tex/texlive/Portfile

.. code-block:: bash

   sudo port install texlive

The missing ``sphinx_rtd_theme`` should be installed through PIP:

.. code-block:: bash

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


An actual documentation build
-----------------------------

The documentation is compiled and viewed as follows:

.. code-block:: bash

    cd doc; make html; open -a safari _build/html/index.html

or

.. code-block:: bash

    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:

.. code-block:: bash

   cd doc
   sphinx-autobuild . _build/html