.. 
    DOCUMENTATION BUILT FROM RELEASE: 2.1.0b1-1-ge018244 (Feb 03, 2017)

..
    : HORTON: Helpful Open-source Research TOol for N-fermion systems.
    : Copyright (C) 2011-2016 The HORTON Development Team
    :
    : This file is part of HORTON.
    :
    : HORTON 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.
    :
    : HORTON 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/>
    :
    : --

..
    : THIS FILE IS AUTOMATICALLY GENERATED. CHANGES TO THIS FILE WILL BE OVERWRITTEN
    : WHEN REBUILDING THE DOCUMENTATION. MAKE CHANGES IN
    :     user_download_and_install_linux.rst.template
    : OR
    :     ../dependencies.json
    : INSTEAD.



Download and installation on Linux (Fedora and Ubuntu)
######################################################


Disclaimer
==========

HORTON has been tested on Fedora and Ubuntu Linux. If you are running
another Linux distribution, some of the instructions below may not work.


Download the code
=================

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

    https://github.com/theochem/horton/releases/download/2.1.0b1/horton-2.1.0b1.tar.gz

Choose a suitable directory, e.g. ``~/build``, download and unpack the archive

.. code-block:: bash

    mkdir -p ~/build
    cd ~/build
    curl -kLO https://github.com/theochem/horton/releases/download/2.1.0b1/horton-2.1.0b1.tar.gz
    tar -xvzf horton-2.1.0b1.tar.gz
    cd horton-2.1.0b1


Dependencies for building, installing and testing HORTON
========================================================

In order to compile and test HORTON, you need to install relatively recent
versions of the following programs/libraries:

* GCC, G++ and GFortran >=4.9: http://gcc.gnu.org (In principle the Intel compilers or any other combination of C++11 and Fortran compiler should work. The GNU compilers are used for development and testing.)
* Python >=2.7,<3.0: http://www.python.org/ (Also install development files.)
* Nosetests >=1.1.2: http://readthedocs.org/docs/nose/en/latest/
* Atlas >=3.10.1: http://math-atlas.sourceforge.net/ (Also install development files. You should be able to use any other BLAS implementation as well.)
* NumPy >=1.9.1: http://www.numpy.org/
* SciPy >=0.11.0: http://www.scipy.org/
* Cython >=0.17.1,!=0.24: http://www.cython.org/
* H5Py >=2.2.1: http://www.h5py.org/
* Sympy >=0.7.1: http://code.google.com/p/sympy/
* Matplotlib >=1.0: http://matplotlib.org/
* LibXC ==2.2.2: http://www.tddft.org/programs/octopus/wiki/index.php/Libxc (Also install development files.)
* LibInt ==2.0.3: http://sourceforge.net/p/libint/home (Also install development files.)
* Curl >=7.0: http://curl.haxx.se/
* PIP >=7.0: https://pip.pypa.io/ (Not required in some scenarios but never bad to have.)


Installing dependencies with a package manager
----------------------------------------------

With popular Linux distributions, most of these dependencies can be installed
with a package manager:

* **Ubuntu Linux 16.04**:

  .. code-block:: bash

    sudo apt-get install gcc g++ gfortran python-dev python-nose libatlas-base-dev \
                python-scipy cython python-h5py python-sympy \
                python-matplotlib libxc-dev curl python-pip

  Note that Ubuntu 16.04 does not have up-to-date packages for all dependencies. LibInt2
  must be compiled manually as explained in :ref:`linux_manual_dependency_install`. (The
  beta version of LibInt2 that comes with Ubuntu 16.04 is compiled with a too low
  LIBINT2_MAX_AM_ERI value.)

* **Ubuntu Linux 15.04 and 14.04**:

  .. code-block:: bash

    sudo apt-get install gcc g++ gfortran python-dev python-nose libatlas-base-dev \
                python-scipy cython python-h5py python-sympy \
                python-matplotlib libxc-dev curl python-pip
    pip install --user --upgrade numpy

  Note that Ubuntu 15.04 and 14.04 do not have up-to-date packages for all dependencies.
  Hence, some are installed with PIP. LibInt2 must be compiled manually as explained in
  :ref:`linux_manual_dependency_install`.

* **Fedora Linux 24**:

  .. code-block:: bash

    sudo dnf install gcc gcc-c++ gcc-gfortran redhat-rpm-config python-devel \
                python-nose atlas-devel python2-numpy \
                python2-scipy Cython python2-h5py sympy \
                python2-matplotlib libxc-devel libint2-devel \
                curl python-pip

* **Fedora Linux 22 and 23**:

  .. code-block:: bash

    sudo dnf install gcc gcc-c++ gcc-gfortran redhat-rpm-config python-devel \
                python-nose atlas-devel numpy scipy Cython \
                h5py sympy python-matplotlib libxc-devel \
                libint2-devel curl python-pip


.. _linux_manual_dependency_install:

Installing dependencies manually
--------------------------------

If the package manager of your Linux distribution does not have the desired
packages (or the right versions), you have to install them manually, e.g.
download and execute an installer, or download and unpack a binary package. On
HPC environments a compilation from scratch is recommended.

**BLAS**

In principle, any BLAS implementation may be used. In case of a custom build,
some environment variables must be set prior to building HORTON, as discussed
in :ref:`linux_compile_install`.


**LibXC**

The directory ``tools/qa`` of the HORTON source tree contains scripts to download and
build LibXC, which will work on most systems:

.. code-block:: bash

    ./tools/qa/install_libxc-2.2.2.sh

This results in a LibXC library suitable for compiling HORTON. If this fails,
consult your local Linux guru to build LibXC. For more info about LibXC, check
the website: http://www.tddft.org/programs/octopus/wiki/index.php/Libxc

**LibInt2**

The directory ``tools/qa`` of the HORTON source tree contains scripts to download and
build LibInt2, which will work on most systems:

.. code-block:: bash

    ./tools/qa/install_libint-2.0.3.sh

The compilation of LibInt2 takes a few minutes and results in a library suitable for
compiling HORTON. If this fails, consult your local Linux guru to build LibInt2. For more
info about LibInt2, check the website: https://github.com/evaleev/libint

**Python dependencies**

In some cases, PIP, the Python package manager, may be a good choice to install
the most recent versions of the Python packages in the list of dependencies. Examples
are given above for Ubuntu and Fedora.


.. _linux_compile_install:

Compilation and installation
============================

Build and install
-----------------

The regular build and install is done as follows:

.. code-block:: bash

    ./setup.py install --user

The ``setup.py`` script makes a reasonable attempt at configuring the compiler and
linker settings for the LibXC, LibInt2 and BLAS libraries. However, this does
not work in all environments. In case of a failure, or if a configuration other
than the default is desired, read the following section.


Overriding default compiler/linker settings for LibXC, LibInt2 and BLAS
-----------------------------------------------------------------------

The manual configuration of the compiler and linker settings is described here:
:ref:`setup_cfg`. You should read this section if the default build and install
has failed or if you would like to specify which libraries to use.


Runtime configuration
---------------------

You need to set the following variable in ``~/.bashrc`` to use HORTON:

.. code-block:: bash

    export PATH=${HOME}/.local/bin:${PATH}

    # If you used special link options for LibXC, LibInt2 or BLAS, something along
    # the following lines may also be needed:
    # export LD_LIBRARY_PATH=some_dir/with/shared_objects/${LD_LIBRARY_PATH}

If you run HORTON on a headless node, i.e. without an X server, you need to
configure Matplotlib to use a backend that does not require a graphical user
interface. (See http://matplotlib.org/faq/usage_faq.html#what-is-a-backend for
more details on the Matplotlib backends.) This can be done by adding the
following line to your ``matplotlibrc`` file:

.. code-block:: text

    backend: agg

This file is located in either ``${HOME}/.matplotlib`` or
``${HOME}/.config/matplotlib``.


Reference atoms
===============

Several parts of HORTON make use of reference atomic computations. When compiling
a stable release from a .tar.gz file these reference atoms are already included in
the release. When building a development version of HORTON, please refer to
:ref:`ref_build_refatoms` on how to build these reference atoms.


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

To test if HORTON was installed properly and if it can be accessed from any directory,
you should change to a directory outside of the source tree and call nosetests
as follows:

.. code-block:: bash

    (cd ~; nosetests -v horton)


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

Dependencies
------------

If you are interested in generating the documentation from source, the following
packages are also needed:

* Sphinx >=1.3.1: http://sphinx.pocoo.org/
* Sphinx Read-The-Docs theme >=0.1.8: https://github.com/snide/sphinx_rtd_theme
* Doxygen >=1.8.6: http://www.doxygen.org/
* Breathe >=1.2.0: http://breathe.readthedocs.org/en/latest/
* Docutils >=0.11: http://docutils.sourceforge.net/


Installing the dependencies with a package manager and PIP
----------------------------------------------------------

* **Ubuntu Linux 16.04**:

  .. code-block:: bash

      sudo apt-get install python-sphinx python-sphinx-rtd-theme doxygen \
                python-docutils

* **Ubuntu Linux 15.04 and 14.04**:

  .. code-block:: bash

      sudo apt-get install doxygen python-docutils
      pip install --user --upgrade sphinx sphinx_rtd_theme breathe

* **Fedora Linux 24**:

  .. code-block:: bash

      sudo dnf install python2-sphinx python2-sphinx_rtd_theme doxygen \
                python2-breathe python-docutils

* **Fedora Linux 22 and 23**:

  .. code-block:: bash

      sudo dnf install doxygen python-docutils
      pip install --user --upgrade sphinx sphinx_rtd_theme breathe

You must also manually build LibXC as explained in :ref:`linux_manual_dependency_install`,
to generate the list of DFT functionals in the documentation.


Actual build
------------

The documentation is compiled and viewed as follows:

.. code-block:: bash

    (cd doc; make html; firefox _build/html/index.html)


.. _linux_install_dev:

Development tools
=================

If you want to contribute to the development of HORTON, you'll need to install at least
the following dependencies:

* PyLint >=1.5.0: https://www.pylint.org/
* pycodestyle >=2.0.0: http://pycodestyle.readthedocs.io/
* pydocstyle >=1.0.0: http://pydocstyle.readthedocs.io/
* coverage >=4.1: https://coverage.readthedocs.io/
* Cppcheck >=1.73: http://cppcheck.sourceforge.net/
* Git >=1.8: https://git-scm.com/
* GitPython >=2.0.5: http://gitpython.readthedocs.io/

For the python development tools, we generally recommend installing the latest versions
with ``pip``.

* **Ubuntu Linux 16.04**:

  .. code-block:: bash

      sudo apt-get install cppcheck git
      pip install --user --upgrade pylint pycodestyle pydocstyle coverage GitPython

* **Ubuntu Linux 15.04 and 14.04**:

  .. code-block:: bash

      sudo apt-get install cppcheck git
      pip install --user --upgrade pylint pycodestyle pydocstyle coverage GitPython

* **Fedora Linux 24**:

  .. code-block:: bash

      sudo dnf install cppcheck git
      pip install --user --upgrade pylint pycodestyle pydocstyle coverage GitPython

* **Fedora Linux 22 and 23**:

  .. code-block:: bash

      sudo dnf install cppcheck git
      pip install --user --upgrade pylint pycodestyle pydocstyle coverage GitPython