..
: 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 (10.14 or higher)
##########################
Disclaimer
==========
PyBEST has been tested on Mac OS X 10.14 (Mojave) and 10.15 (Catalina) using
MacPorts (exceptions are the MKL, Libint2, Libchol, and HighFive 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.6.3 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 = python38):
.. code-block:: bash
sudo port list python38
* searching ports (e.g, port_name = python38):
.. code-block:: bash
port search python38
* installing ports (e.g, port_name = python38):
.. code-block:: bash
sudo port install python38
* selecting ports (e.g, select python38 as python):
.. code-block:: bash
sudo port select --set python python38
Download PyBEST
===============
The latest stable source code release of PyBEST can be downloaded here:
* `version |release| <http://www.fizyka.umk.pl/~pybest/downloads/pybest.v1.0.2.tar.gz>`_
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.0.2.tar.gz
tar -xvf pybest.v1.0.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.
* ``python38`` (>=3.8.2), https://github.com/macports/macports-ports/blob/master/lang/python38/Portfile
.. code-block:: bash
sudo port install python38
* ``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 python38
* ``cmake`` (>=3.16), 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://www.gnu.org/software/automake/
.. code-block:: bash
sudo port install automake
* ``py38-numpy`` (>=1.18.1), https://github.com/macports/macports-ports/blob/master/python/py-numpy/Portfile
.. code-block:: bash
sudo port install py38-numpy
port select --set cython cython38
* ``py38-scipy`` (>=1.4.1), https://github.com/macports/macports-ports/blob/master/python/py-scipy/Portfile
.. code-block:: bash
sudo port install py38-scipy
* ``boost`` (>=1.71.0), https://github.com/macports/macports-ports/blob/master/devel/boost/Portfile
.. code-block:: bash
sudo port install boost
* ``py38-h5py`` (>=2.10.0), https://ports.macports.org/port/py38-h5py/summary
.. code-block:: bash
sudo port install py38-h5py
h5cc -showconfig
* ``py38-nose`` (>=1.3.7), https://github.com/macports/macports-ports/blob/master/python/py-nose/Portfile
.. code-block:: bash
sudo port install py38-nose
* ``py38-setuptools`` (>=43.0.0), https://github.com/macports/macports-ports/blob/master/python/py-setuptools/Portfile
.. code-block:: bash
sudo port install py38-setuptools
* ``eigen3`` (>=3.3.7), https://github.com/macports/macports-ports/blob/master/math/eigen3/Portfile
.. code-block:: bash
sudo port install eigen3
* ``gcc9`` (>=9.2.0), https://github.com/macports/macports-ports/blob/master/lang/gcc9/Portfile
.. code-block:: bash
sudo port install gcc9
* ``gcc_select`` (>=0.1), https://github.com/macports/macports-ports/blob/master/sysutils/gcc_select/Portfile
.. code-block:: bash
sudo port install gcc_select
sudo port select --set gcc gcc-nm-mp-9
* ``py38-pip`` (>=20.02), https://ports.macports.org/port/py38-pip/summary
.. code-block:: bash
sudo port install py38-pip
sudo port select --set pip pip38
* ``pytest`` (>=5.4.0), https://pypi.org/project/pytest/
.. code-block:: bash
pip3 install pytest
* ``pylatexenc`` (>=2.7), https://pypi.org/project/pylatexenc/
.. code-block:: bash
pip install pylatexenc
* ``HighFive`` (>=2.2), https://github.com/BlueBrain/HighFive.git
Please note that headers are enough (no CMake is required).
.. code-block:: bash
mkdir ~/HighFive
export HIGHFIVE_VER=2.2
cd ~/HighFive; mkdir ${HIGHFIVE_VER}
cd ${HIGHFIVE_VER};
git clone https://github.com/BlueBrain/HighFive.git
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
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.0.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-beta``
using ``make``.
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.
* ``wget`` (>=1.20.3), https://ports.macports.org/port/wget/summary
.. code-block:: bash
sudo port install wget
* ``autoconf`` (>=2.69), https://ports.macports.org/port/autoconf/summary
.. code-block:: bash
sudo port install autoconf
* compilation
.. code-block:: bash
cd $HOME/my_pybest/pybest.v1.0.2/depends
make libchol
.. note::
You might need to set up some environmental variables at this point. Examples
are provided in the next section.
Building and installing PyBEST
==============================
Overriding default compiler/linker settings
-------------------------------------------
.. code-block:: bash
cd $HOME/my_pybest/pybest.v1.0.2/
cp setup.cfg.ini setup.cfg
Adopt the existing `setup.cfg` to your specific setup.
An example configuration file based on OS X Catalinia (10.15.3) 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
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
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
[highfive]
# If both paths have not been exported, you need to define them
#include_dirs=/usr/include/
#
# If enviroment variables are defined
include_dirs=${HIGHFIVE_ROOT}/include
libraries=highfive
[hdf5]
# 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=${HDF5_ROOT}/include
library_dirs=${HDF5_ROOT}/lib
libraries=hdf5
where the evironmental variables are defined in, for instance, ``~/.profile``,
.. code-block:: bash
### PyBEST ##########
export LIBINT2_ROOT=/$HOME/my_pybest/pybest.v1.0.2/depends/libint-upstream/installdir
export EIGEN_ROOT=/opt/local
export HIGHFIVE_ROOT="path-to-your-HighFive"/highFive/HighFive
export MKL_ROOT=/opt/intel/compilers_and_libraries_2020.0.166/mac/mkl
export HDF5_ROOT=/opt/local
export BOOST_ROOT=/opt/local
export DYLD_LIBRARY_PATH=/opt/intel/mkl/lib:$DYLD_LIBRARY_PATH
Actual build and installation
-----------------------------
* Building extensions:
.. code-block:: bash
python setup.py build_ext -i
* Building extensions with the Libchol library (optional):
.. code-block:: bash
python setup.py build_ext -i --enable-cholesky=1
* 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.0.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
* ``py38-sphinx`` (>=2.4.3), https://github.com/macports/macports-ports/blob/master/python/py-sphinx/Portfile
.. code-block:: bash
sudo port install py38-sphinx
port select --set pygments py38-pygments
port select --set sphinx py38-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 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