.. _Installation:

Installation
============

Download
--------

A tar archive of the HEJ 2 source code can be downloaded and
decompressed with the command::

  curl https://hej.hepforge.org/downloads?f=HEJ_2.0.tar.gz | tar -xz

To obtain the latest stable HEJ version, `HEJ_2.0.tar.gz` should be
replaced by `HEJ.tar.gz`.

Alternatively, the HEJ source code can be obtained by installing the
`git version control system <https://git-scm.com/>`_. and running::

  git clone https://phab.hepforge.org/source/hej.git

We also provide a `Docker image <https://hub.docker.com/r/hejdock/hej>`_
containing a HEJ 2 installation on. This image can be pulled with::

  docker pull hejdock/hej

When using the Docker image the remaining installation steps can be
skipped.

Prerequisites
-------------

Before installing HEJ 2, you need the following programs and
libraries:

- `CMake <https://cmake.org/>`_ version 3.1
- A compiler supporting the C++14 standard, for example `gcc <https://gcc.gnu.org/>`_ 5 or later
- `FastJet <http://fastjet.fr/>`_
- `CLHEP <https://gitlab.cern.ch/CLHEP/CLHEP>`_
- `LHAPDF <https://lhapdf.hepforge.org/>`_
- The `IOStreams` and `uBLAS` `boost <https://www.boost.org>`_ libraries
- `yaml-cpp <https://github.com/jbeder/yaml-cpp>`_

If you want to include finite top mass corrections in Higgs boson + jets
production, you additionally need version 2 of the `QCDLoop
<https://github.com/scarrazza/qcdloop>`_ library. HEJ 2 supports
versions 2 and 3 of `HepMC <https://hepmc.web.cern.ch/hepmc/>`_ if it is
installed, but does not require it. Additional HEJ 2 can be interfaced to
`rivet <https://rivet.hepforge.org/>`_, which requires HepMC version 2.

Compilation
-----------

To compile and install HEJ 2 run::

  cmake source/directory -DCMAKE_INSTALL_PREFIX=target/directory
  make install

:file:`source/directory` is the directory containing the file
:file:`CMakeLists.txt`. If you omit
:code:`-DCMAKE_INSTALL_PREFIX=target/directory` HEJ 2 will be
installed to some default location.

In case some of the aforementioned prerequisites are not found by
:code:`cmake` you can give a hint by adding an additional argument
:code:`-Dlibname_ROOT_DIR=/directory/with/library`, where
:code:`libname` should be replaced by the name of the library in
question.

To not include specific packages one can add
:code:`-DEXCLUDE_packagename=TRUE` to :code:`cmake`, e.g. by
setting :code:`-DEXCLUDE_rivet=TRUE` HEJ 2 will not be interfaced
to `rivet` even if rivet is available on the system.

Testing
-------

To test your installation, download the NNPDF 2.3 PDF set with::

  lhapdf install NNPDF23_nlo_as_0119

and run::

  make test