..
    : 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 (12.3 or higher)
##########################

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.


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.

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

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

The latest stable source code release of PyBEST can be downloaded here:

    * `version <http://www.fizyka.umk.pl/~pybest/downloads/pybest.v1.3.2.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.v1.3.2.tar.gz
    tar -xvf pybest.v1.3.2.tar.gz

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.

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

  .. code-block:: bash

     sudo port install python310

* ``python3_select`` (>=0.0), https://github.com/macports/macports-ports/blob/master/sysutils/python3_select/Portfile

  .. code-block:: bash

     sudo port install python3_select
     sudo port select --set python python310

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

  .. code-block:: bash

     sudo port install cmake

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

  .. code-block:: bash

     sudo port install git


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

  .. code-block:: bash

     sudo port install automake

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

  .. code-block:: bash

     sudo port install py310-numpy
     sudo port select --set cython cython310

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

  .. code-block:: bash

     sudo port install py310-scipy

* ``pybind11`` (>=2.5.0,<2.7.0), https://github.com/macports/macports-ports/blob/master/devel/pybind11/Portfile

  .. code-block:: bash

     sudo port install py310-pybind11

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

  .. code-block:: bash

     sudo port install py310-h5py

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

  .. code-block:: bash

     sudo port install boost

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

  .. code-block:: bash

     sudo port install autoconf

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

  .. code-block:: bash

     sudo port install py310-setuptools

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

  .. code-block:: bash

     sudo port install libomp

* ``pytest`` (>=6.2.4), https://github.com/macports/macports-ports/blob/master/python/py-pytest-html/Portfile

  .. code-block:: bash

     sudo port install py310-pytest
     sudo port select --set pytest pytest310

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

  .. code-block:: bash

     sudo port install py310-pip
     sudo port select --set pip pip310

* ``pylatexenc`` (>=2.8.0), https://pypi.org/project/pylatexenc/

  .. code-block:: bash

    pip install pylatexenc

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

  .. code-block:: bash

   sudo port install wget


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.

.. code-block:: bash

   sudo port install OpenBLAS

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

  .. code-block:: bash

     cd $HOME/my_pybest/pybest.v1.3.2/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 enviroment variable ``EIGEN_ROOT`` has to be set
to ``/opt/local``.

Installing Libint2
------------------

There are two ways of installing the Libint2 library (>=2.6.0):

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

.. code-block:: bash

   cd $HOME/my_pybest/pybest.v1.3.2/depends
   make libint


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

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

.. code-block:: bash

    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

.. code-block:: bash

    export OpenBLAS=/opt/local

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

Overriding default compiler/linker settings
-------------------------------------------

.. code-block:: bash

   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:

.. code-block:: bash

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

.. code-block:: bash

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


Actual build and installation
-----------------------------
* Building extensions:

.. code-block:: bash

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

.. code-block:: bash

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

.. code-block:: bash

    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:

.. code-block:: bash

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

.. code-block:: bash

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

Running the tests
=================

To test that PyBEST was installed properly you can run:

.. code-block:: bash

    cd $HOME/my_pybest/pybest.v1.3.2/src/

    python -m pytest pybest -vs


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

* ``py310-sphinx`` (>=2.4.3), https://github.com/macports/macports-ports/blob/master/python/py-sphinx/Portfile

  .. code-block:: bash

     sudo port install py310-sphinx
     port select --set docutils py310-docutils
     port select --set pygments py310-pygments
     port select --set sphinx py310-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

    pip install wheel
    pip install sphinx_rtd_theme
    pip install --user --upgrade sphinx breath


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