Page MenuHomeHEPForge
Files F8723884

No OneTemporary
Actions

View Options

diff --git a/doc/sphinx/HEJ.rst b/doc/sphinx/HEJ.rst
index db3fac2..1365039 100644
--- a/doc/sphinx/HEJ.rst
+++ b/doc/sphinx/HEJ.rst
@@ -1,304 +1,304 @@
.. _`Running HEJ 2`:
Running HEJ 2
=============
Quick start
-----------
In order to run HEJ 2, you need a configuration file and a file
containing fixed-order events. A sample configuration is given by the
:file:`config.yml` file distributed together with HEJ 2. Events in the
Les Houches Event File format can be generated with standard Monte Carlo
generators like `MadGraph5_aMC@NLO <https://launchpad.net/mg5amcnlo>`_
or `Sherpa <https://sherpa.hepforge.org/trac/wiki>`_. If HEJ 2 was
-compiled with `HDF5 <https://www.hdfgroup.org/>` support, it can also
-read event files in the format suggested in `arXiv:1905.05120
-<https://arxiv.org/abs/1905.05120>`. HEJ 2 assumes that the cross
-section is given by the sum of the event weights. Depending on the
-fixed-order generator it may be necessary to adjust the weights in the
-Les Houches Event File accordingly.
+compiled with `HDF5 <https://www.hdfgroup.org/>`_ support, it can also
+read event files in the format suggested in
+`arXiv:1905.05120 <https://arxiv.org/abs/1905.05120>`_.
+HEJ 2 assumes that the cross section is given by the sum of the event
+weights. Depending on the fixed-order generator it may be necessary to
+adjust the weights in the Les Houches Event File accordingly.
The processes supported by HEJ 2 are
- Pure multijet production
- Production of a Higgs boson with jets
..
- *TODO* Production of a W boson with jets
- *TODO* Production of a Z boson or photon with jets
where at least two jets are required in each case. For the time being,
only leading-order events are supported.
After generating an event file :file:`events.lhe` adjust the parameters
under the `fixed order jets`_ setting in :file:`config.yml` to the
settings in the fixed-order generation. Resummation can then be added by
running::
HEJ config.yml events.lhe
Using the default settings, this will produce an output event file
:file:`HEJ.lhe` with events including high-energy resummation.
When using the `Docker image <https://hub.docker.com/r/hejdock/hej>`_,
HEJ can be run with
.. code-block:: bash
docker run -v $PWD:$PWD -w $PWD hejdock/hej HEJ config.yml events.lhe
.. _`HEJ 2 settings`:
Settings
--------
HEJ 2 configuration files follow the `YAML <http://yaml.org/>`_
format. The following configuration parameters are supported:
.. _`trials`:
**trials**
High-energy resummation is performed by generating a number of
resummation phase space configurations corresponding to an input
fixed-order event. This parameter specifies how many such
configurations HEJ 2 should try to generate for each input
event. Typical values vary between 10 and 100.
.. _`min extparton pt`:
**min extparton pt**
Specifies the minimum transverse momentum in GeV of the most forward
and the most backward parton. This setting is needed to regulate an
otherwise uncancelled divergence. Its value should be slightly below
the minimum transverse momentum of jets specified by `resummation
jets: min pt`_. See also the `max ext soft pt fraction`_ setting.
.. _`max ext soft pt fraction`:
**max ext soft pt fraction**
Specifies the maximum fraction that soft radiation can contribute to
the transverse momentum of each the most forward and the most backward
jet. Values between around 0.05 and 0.1 are recommended. See also the
`min extparton pt`_ setting.
.. _`fixed order jets`:
**fixed order jets**
This tag collects a number of settings specifying the jet definition
in the event input. The settings should correspond to the ones used in
the fixed-order Monte Carlo that generated the input events.
.. _`fixed order jets: min pt`:
**min pt**
Minimum transverse momentum in GeV of fixed-order jets.
.. _`fixed order jets: algorithm`:
**algorithm**
The algorithm used to define jets. Allowed settings are
:code:`kt`, :code:`cambridge`, :code:`antikt`,
:code:`cambridge for passive`. See the `FastJet
<http://fastjet.fr/>`_ documentation for a description of these
algorithms.
.. _`fixed order jets: R`:
**R**
The R parameter used in the jet algorithm, roughly corresponding
to the jet radius in the plane spanned by the rapidity and the
azimuthal angle.
.. _`resummation jets`:
**resummation jets**
This tag collects a number of settings specifying the jet definition
in the observed, i.e. resummed events. These settings are optional, by
default the same values as for the `fixed order jets`_ are assumed.
.. _`resummation jets: min pt`:
**min pt**
Minimum transverse momentum in GeV of resummation jets. This
should be between 25% and 50% larger than the minimum transverse
momentum of fixed order jets set by `fixed order jets: min pt`_.
.. _`resummation jets: algorithm`:
**algorithm**
The algorithm used to define jets. The HEJ 2 approach to
resummation relies on properties of :code:`antikt` jets, so this
value is strongly recommended. For a list of possible other
values, see the `fixed order jets: algorithm`_ setting.
.. _`resummation jets: R`:
**R**
The R parameter used in the jet algorithm.
.. _`FKL`:
**FKL**
Specifies how to treat events respecting FKL rapidity ordering. These
configurations are dominant in the high-energy limit. The possible
values are :code:`reweight` to enable resummation, :code:`keep` to
keep the events as they are up to a possible change of
renormalisation and factorisation scale, and :code:`discard` to
discard these events.
.. _`unordered`:
**unordered**
Specifies how to treat events with one emission that does not respect
FKL ordering. In the high-energy limit, such configurations are
logarithmically suppressed compared to FKL configurations. The
possible values are the same as for the `FKL`_ setting, but
:code:`reweight` is currently only supported for Higgs boson plus
jets production.
.. _`non-HEJ`:
**non-HEJ**
Specifies how to treat events where no resummation is possible. The
allowed values are :code:`keep` to keep the events as they are up to
a possible change of renormalisation and factorisation scale and
:code:`discard` to discard these events.
.. _`scales`:
**scales**
Specifies the renormalisation and factorisation scales for the output
events. This can either be a single entry or a list :code:`[scale1,
scale2, ...]`. For the case of a list the first entry defines the
central scale. Possible values are fixed numbers to set the scale in
GeV or the following:
- :code:`H_T`: The sum of the scalar transverse momenta of all
final-state particles
- :code:`max jet pperp`: The maximum transverse momentum of all jets
- :code:`jet invariant mass`: Sum of the invariant masses of all jets
- :code:`m_j1j2`: Invariant mass between the two hardest jets.
Scales can be multiplied or divided by an overall factor,
e.g. :code:`H_T/2`.
It is also possible to import scales from an external library, see
:ref:`Custom scales`
.. _`scale factors`:
**scale factors**
A list of numeric factors by which each of the `scales`_ should be
multiplied. Renormalisation and factorisation scales are varied
independently. For example, a list with entries :code:`[0.5, 2]`
would give the four scale choices (0.5μ\ :sub:`r`, 0.5μ\ :sub:`f`);
(0.5μ\ :sub:`r`, 2μ\ :sub:`f`); (2μ\ :sub:`r`, 0.5μ\ :sub:`f`); (2μ\
:sub:`r`, 2μ\ :sub:`f`) in this order. The ordering corresponds to
the order of the final event weights.
.. _`max scale ratio`:
**max scale ratio**
Specifies the maximum factor by which renormalisation and
factorisation scales may difer. For a value of :code:`2` and the
example given for the `scale factors`_ the scale choices
(0.5μ\ :sub:`r`, 2μ\ :sub:`f`) and (2μ\ :sub:`r`, 0.5μ\ :sub:`f`)
will be discarded.
.. _`log correction`:
**log correction**
Whether to include corrections due to the evolution of the strong
coupling constant in the virtual corrections. Allowed values are
:code:`true` and :code:`false`.
.. _`event output`:
**event output**
Specifies the name of a single event output file or a list of such
files. The file format is either specified explicitly or derived from
the suffix. For example, :code:`events.lhe` or, equivalently
:code:`Les Houches: events.lhe` generates an output event file
:code:`events.lhe` in the Les Houches format. The supported formats
are
- :code:`file.lhe` or :code:`Les Houches: file`: The Les Houches
event file format.
- :code:`file.hepmc` or :code:`HepMC: file`: The HepMC format.
.. _`random generator`:
**random generator**
Sets parameters for random number generation.
.. _`random generator: name`:
**name**
Which random number generator to use. Currently, :code:`mixmax`
and :code:`ranlux64` are supported. Mixmax is recommended. See
the `CLHEP documentation
<http://proj-clhep.web.cern.ch/proj-clhep/index.html#docu>`_ for
details on the generators.
.. _`random generator: seed`:
**seed**
The seed for random generation. This should be a single number for
:code:`mixmax` and the name of a state file for :code:`ranlux64`.
.. _`analysis`:
**analysis**
Name and Setting for the event analyses; either a custom
analysis plugin or Rivet. For the first the :code:`plugin` sub-entry
should be set to the analysis file path. All further entries are passed on
to the analysis. To use Rivet a list of Rivet analyses have to be
given in :code:`rivet` and prefix for the yoda file has to be set
through :code:`output`. See :ref:`Writing custom analyses` for details.
.. _`Higgs coupling`:
**Higgs coupling**
This collects a number of settings concerning the effective coupling
of the Higgs boson to gluons. This is only relevant for the
production process of a Higgs boson with jets and only supported if
HEJ 2 was compiled with `QCDLoop
<https://github.com/scarrazza/qcdloop>`_ support.
.. _`Higgs coupling: use impact factors`:
**use impact factors**
Whether to use impact factors for the coupling to the most forward
and most backward partons. Impact factors imply the infinite
top-quark mass limit.
.. _`Higgs coupling: mt`:
**mt**
The value of the top-quark mass in GeV. If this is not specified,
the limit of an infinite mass is taken.
.. _`Higgs coupling: include bottom`:
**include bottom**
Whether to include the Higgs coupling to bottom quarks.
.. _`Higgs coupling: mb`:
**mb**
The value of the bottom-quark mass in GeV. Only used for the Higgs
coupling, external bottom-quarks are always assumed to be massless.
Advanced Settings
~~~~~~~~~~~~~~~~~
All of the following settings are optional. Please **do not set** any of the
following options, unless you know exactly what you are doing. The default
behaviour gives the most reliable results for a wide range of observables.
.. _`regulator parameter`:
**regulator parameter**
Slicing parameter to regularise the subtraction term, see :math:`\lambda`
in `arxiv:1706.01002 <https://arxiv.org/abs/1706.01002>`_. Default is 0.2
diff --git a/doc/sphinx/installation.rst b/doc/sphinx/installation.rst
index 79398c5..1d9de77 100644
--- a/doc/sphinx/installation.rst
+++ b/doc/sphinx/installation.rst
@@ -1,84 +1,91 @@
.. _Installation:
Installation
============
Download
--------
A tar archive of the HEJ 2 source code can be downloaded and
decompressed with the command::
curl https://hej.web.cern.ch/HEJ/downloads/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.
+In addition, some optional features have additional dependencies:
+
+- 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/>`_ as event output format if HepMC
+ is installed.
+- If both HepMC 2 and `Rivet <https://rivet.hepforge.org/>`_ are
+ available, HEJ 2 can use Rivet analyses.
+- To read event files in the in the `HDF5 <https://www.hdfgroup.org/>`_-based
+ format suggested in `arXiv:1905.05120 <https://arxiv.org/abs/1905.05120>`_
+ `HighFive <https://github.com/BlueBrain/HighFive>`_ has to be installed.
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

File Metadata

Mime Type
text/x-diff
Expires
Mon, Jan 20, 9:49 PM (1 d, 7 h)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
4242536
Default Alt Text
(14 KB)

Event Timeline