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


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.

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

  .. code-block:: bash

      sudo port list python310

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

  .. code-block:: bash

      port search python310

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

  .. code-block:: bash

      sudo port install python310

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

  .. code-block:: bash

      sudo port select --set python python310

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

    * `version <http://www.fizyka.umk.pl/~pybest/downloads/pybest.v2.0.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 http://www.fizyka.umk.pl/~pybest/downloads/pybest.v2.0.0.tar.gz
    tar -xvf pybest.v2.0.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.9. The guide below is written for Python 3.12, while
   the minimum supported versions are mentioned in parentheses.

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

  .. code-block:: bash

     sudo port install python312
     sudo port select --set python python312
     sudo port select --set python3 python312

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

  .. code-block:: bash

     sudo port install py312-pip
     sudo port select --set pip pip312
     sudo port select --set pip3 pip312

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

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

  .. code-block:: bash

     sudo port install cmake

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

      python3.12 -m venv ${HOME}/.mypybestenv
      source ${HOME}/.mypybestenv/bin/activate
      which python3
      python3 --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 Macs with the M1 chip or newer, OpenBlas can be used instead of MKL.
  The installation can be done very quickly using MacPorts.

.. code-block:: bash

   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.

.. code-block:: bash

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

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

  .. code-block:: bash

     cd $HOME/my_pybest/pybest.v2.0.0/depends
     make eigen3

Alternatively, you can install Eigen3 using MacPorts,

* ``eigen`` (>=3.4.0)

  .. code-block:: bash

    sudo port install eigen3

If you use MacPorts to install Eigen3, the environment variable ``EIGEN_ROOT`` has to be set
to ``/opt/local``.

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

.. code-block:: bash

   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.

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

  .. code-block:: bash

     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:

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

.. code-block:: bash

   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

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

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



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

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

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