.. DOCUMENTATION BUILT FROM RELEASE: 2.0.1 (Jun 17, 2016) .. : 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 : : -- .. : THIS FILE IS AUTOMATICALLY GENERATED. CHANGES TO THIS FILE WILL BE OVERWRITTEN : WHEN REBUILDING THE DOCUMENTATION. MAKE CHANGES IN : user_download_and_install_mac.rst.template : OR : ../dependencies.json : INSTEAD. Download and installation on Mac OS X (10.8--10.11) ################################################### Disclaimer ========== HORTON has been tested on Mac OS X 10.8--10.11 using MacPorts. If you are running any other version of OS X or if you are using other package managers, some of the instructions below may not work. MacPorts ========= We strongly recommend that you install all of the packages required by HORTON 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.3.3 but should also work with newer versions. .. note :: If you have already installed a Python distribution (with another package manager than MacPorts), such as Canopy, it may interfere with the one installed through MacPorts. The instructions below assume that no such other installation of Python is present. Quick tour of MacPorts ---------------------- Here are some basic MacPorts commands: * updating ports (recommended): .. code-block:: bash sudo port -v selfupdate * upgrade ports: .. code-block:: bash sudo port upgrade outdated * finding ports (e.g, port_name = python27): .. code-block:: bash sudo port list python27 * searching ports (e.g, port_name = python27): .. code-block:: bash port search python27 * installing ports (e.g, port_name = python27): .. code-block:: bash sudo port install python27 * selecting ports (e.g, select python27 as python): .. code-block:: bash sudo port select --set python python27 Download the code ================= The latest stable source code release of HORTON can be downloaded here: https://github.com/theochem/horton/releases/download/2.0.1/horton-2.0.1.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.0.1/horton-2.0.1.tar.gz tar -xvzf horton-2.0.1.tar.gz cd horton-2.0.1 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: 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.) .. _mac_compile_install: Installing the dependencies with MacPorts ----------------------------------------- All dependencies can be installed with MacPorts. We recommend the following ports: * ``gcc49``: https://trac.macports.org/browser/trunk/dports/lang/gcc49/Portfile * ``python27``: https://trac.macports.org/browser/trunk/dports/lang/python27/Portfile * ``py27-nose``: https://trac.macports.org/browser/trunk/dports/python/py-nose/Portfile * ``atlas``: https://trac.macports.org/browser/trunk/dports/math/atlas/Portfile * ``py27-numpy``: https://trac.macports.org/browser/trunk/dports/python/py-numpy/Portfile * ``py27-scipy``: https://trac.macports.org/browser/trunk/dports/python/py-scipy/Portfile * ``py27-cython``: https://trac.macports.org/browser/trunk/dports/python/py-cython/Portfile * ``py27-h5py``: https://trac.macports.org/browser/trunk/dports/python/py-h5py/Portfile * ``py27-sympy``: https://trac.macports.org/browser/trunk/dports/python/py-sympy/Portfile * ``py27-matplotlib``: https://trac.macports.org/browser/trunk/dports/python/py-matplotlib/Portfile * ``libxc``: https://trac.macports.org/browser/trunk/dports/science/libxc/Portfile * ``libint``: https://trac.macports.org/browser/trunk/dports/science/libint/Portfile * ``py27-pip``: https://trac.macports.org/browser/trunk/dports/python/py-pip/Portfile These are installed with the following commands. (When MacPorts is installed in user space, the ``sudo`` can be omitted.): .. code-block:: bash sudo port install gcc49; sudo port select --set gcc mp-gcc49 sudo port install python27; sudo port select --set python python27 sudo port install py27-nose; sudo port select --set nosetests nosetests27 sudo port install atlas sudo port install py27-numpy +atlas sudo port install py27-scipy +atlas sudo port install py27-cython; sudo port select --set cython cython27 sudo port install py27-h5py sudo port install py27-sympy; sudo port select --set py-sympy py27-sympy sudo port install py27-matplotlib sudo port install libxc sudo port install libint sudo port install py27-pip; sudo port select --set pip pip27 .. _mac_manual_dependency_install: Installing dependencies manually -------------------------------- **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:`mac_compile_install`. Also, Keep in mind that MacPorts only supports Atlas for building NumPy and SciPy. **LibXC** The directory ``tooals/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 Mac 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 ``tooals/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 Mac guru to build LibInt2. For more info about LibInt2, check the website: http://sourceforge.net/p/libint/home 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 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 failed or if you would like to specify which libraries to use. Runtime configuration --------------------- You need to set some environment variables to use HORTON. Add the following to ``~/.bash_profile`` if it exists, otherwise add them to ``~/.profile``: .. code-block:: bash export PATH=${HOME}/Library/Python/2.7/bin:${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 either in ``${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 that HORTON was installed properly and that you can can access it from other directories, 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 MacPorts and PIP ------------------------------------------------- Most can be installed directly with MacPorts. The following list of ports is recommended: * ``doxygen``: https://trac.macports.org/browser/trunk/dports/textproc/doxygen/Portfile The following commands will install the ports and a few other dependencies (with pip), which are not available as ports: .. code-block:: bash sudo port install doxygen pip install --user --upgrade sphinx sphinx_rtd_theme breathe You must also manually build LibXC as explained in :ref:`mac_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; open _build/html/index.html) .. _mac_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/ The following list of ports is recommended: * ``doxygen``: https://trac.macports.org/browser/trunk/dports/textproc/doxygen/Portfile For the python development tools, we recommend that you install the latest versions with ``pip``. .. code-block:: bash sudo port install cppcheck sudo port install git pip install --user --upgrade pylint pycodestyle pydocstyle coverage GitPython