diff --git a/doc/sphinx/HEJC.rst b/doc/sphinx/HEJC.rst
index a84b447..6444e32 100644
--- a/doc/sphinx/HEJC.rst
+++ b/doc/sphinx/HEJC.rst
@@ -1,262 +1,279 @@
The HEJ Configuration Generator
===============================
``HEJ`` has to be used in conjunction with fixed-order generators. To
this end, the HEJ Configuration Generator ``HEJC`` generates a set of
consistent configuration files.
Installation
------------
The ``HEJC`` comes bundled together with HEJ 2 and the
installation is very similar. After downloading HEJ 2 and
installing the prerequisites as described in :ref:`Installation` the
``HEJC`` can be installed with::
cmake /path/to/config_generator -DCMAKE_INSTALL_PREFIX=target/directory
make install
where :file:`/path/to/config_generator` refers to the :file:`config_generator`
subdirectory in the HEJ 2 directory. If HEJ 2 was
installed to a non-standard location, it may be necessary to specify the
directory containing :file:`HEJ-config.cmake`. If the base installation
directory is :file:`/path/to/HEJ`, :file:`HEJ-config.cmake` should be
found in :file:`/path/to/HEJ/lib/cmake/HEJ` and the commands for
installing the ``HEJC`` would read::
cmake /path/to/config_generator -DHEJ_DIR=/path/to/HEJ/lib/cmake/HEJ -DCMAKE_INSTALL_PREFIX=target/directory
make install
Using the configuration generator
---------------------------------
Usage examples for all processes implemented in ``HEJ`` are given in
the :file:`examples` subdirectory. The general usage pattern is::
- HEJC --runs N [OPTIONS] CONFIGS.YML... TARGETDIR
+ HEJC --runs RANGE [OPTIONS] CONFIGS.YML... TARGETDIR
which takes one or more input configuration files in `YAML
<http://yaml.org/>`_ format and produces a number of configuration
-files for ``HEJ`` and the specified fixed-order generators. The value
-of the :code:`--runs` option is the number of statistically independent runs
-for which configuration files should be generated. For each run, the
+files for ``HEJ`` and the specified fixed-order generators.
+
+The value of the :code:`--runs` option specifies the statistically
+independent runs for which configuration files should be generated. It
+is a comma-separated list of numbers, where additionally inclusive
+ranges can be indicated with an ellipsis. For example :code:`--runs
+1,3,...,6,9` is equivalent to :code:`--runs 1,3,4,5,6,9`. For each run, the
configuration files will be written to a subdirectory `run_XXX` of
-`TARGETDIR`, where `XXX` is the run number from 0 to N-1.
+`TARGETDIR`, where `XXX` is the run number.
When using the ``HEJ`` docker image, the corresponding command is:
.. code-block:: bash
docker run -v $PWD:$PWD -w $PWD hejdock/hej HEJC --runs N [OPTIONS] CONFIGS.YML... TARGETDIR
Options
-------
-- :code:`--runs N` specifies the number of runs for which
- configuration files should be generated.
+- :code:`--runs RANGE` specifies the runs for which configuration
+ files should be generated.
- :code:`--copy-dir DIR` copies the given directory as a subdirectory
into each generated set of configuration files. This can be useful
to add external information to a run, e.g. precomputed integration
grids, custom analyses, or scale setting code.
- :code:`--help` prints a short help message.
Settings
--------
The ``HEJC`` supports the following settings. Note that not all
generators accept all settings. For example, when using
:ref:`HEJFOG`, the beam particles have to be either protons or
antiprotons. To facilitate organising the large number of
configuration options, it is possible to distribute them over more
than one configuration file.
.. _`HEJC process`:
**process**
The scattering process for which events are being generated. The
format is
:code:`in1 in2 => out1 out2 ...`
Particles can either be identified by their name or their `Monte
Carlo status code
<https://pdg.lbl.gov/2023/mcdata/mc_particle_id_contents.html>`_. The
process is always considered as inclusive in the number of jets. To
indicate this, the keyword :code:`jets` can be added.
.. _`HEJC jets`:
**jets**
Defines the properties of the generated jets.
.. _`HEJC jets: min pt`:
**min pt**
Minimum jet transverse momentum in GeV.
.. _`HEJC 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.
.. _`HEJC jets: R`:
**R**
The R parameter used in the jet algorithm.
.. _`HEJC jets: max rapidity`:
**max rapidity**
Maximum absolute value of the jet rapidity.
.. _`HEJC beam`:
**beam**
Defines various properties of the collider beam.
.. _`HEJC beam: energy`:
**energy**
The beam energy in GeV. For example, the 13
TeV LHC corresponds to a value of 6500.
.. _`HEJC beam: particles`:
**particles**
A list :code:`[p1, p2]` of two beam particles.
.. _`HEJC pdf`:
**pdf**
The `LHAPDF number or name <https://lhapdf.hepforge.org/pdfsets>`_
of the PDF set. For example, 230000 or NNPDF23_nlo_as_0119
corresponds to an NNPDF 2.3 NLO PDF set.
+.. _`HEJC low pt event fraction`:
+
+**low pt event fraction**
+ The fraction of the nominal number of events that should be
+ generated in separate low transverse momentum runs.
+
+.. _`HEJC low pt fraction`:
+
+**low pt fraction**
+ The fraction of the :ref:`minimum jet transverse momentum<HEJC
+ jets: min pt>` to be used for separate low transverse momentum
+ runs. Defaults to :code:`0.8` if omitted.
+
.. _`HEJC generators`:
**generators**
A sequence of generators for which configuration files should be
generated.
.. _`HEJC generators: generator`:
**generator**
The name of the generator. Should be the name of one of the
:ref:`Supported Generators`. If it is set to `HEJ`, then the
remaining keys apart from :code:`jets` will overwrite the general
settings and additional specific configuration files for the
given jet multiplicities will be generated. This can be useful
if certain `HEJ` settings should only apply to certain
multiplicities, e.g. for matching.
.. _`HEJC generators: jets`:
**jets**
The number of jets to which this configuration should
apply. This can either be a single number or an inclusive range
`N-M`. In the latter case a separate configuration file will be
written for each jet multiplicity from `N` to `M` .
.. _`HEJC generators: settings`:
**settings**
Generator-specific settings that should be added to
the generated file. See :ref:`Supported Generators` for the
supported entries.
.. _`HEJC generators: HEJ settings`:
**HEJ settings**
Settings that should be added to the HEJ configuration file
generated for the current generator and number of jets. In case
of conflicts, these specific HEJ entries overwrite the globally
defines ones. This entry is optional.
In addition, the following HEJ 2 :ref:`HEJ 2 settings` as well as all
advanced settings are supported and directly added to the generated
``HEJ`` configuration file:
* :ref:`trials<trials>`
* :ref:`event treatment<event treatment>`
* :ref:`scales<scales>`
* :ref:`scale factors<scale factors>`
* :ref:`max scale ratio<max scale ratio>`
* :ref:`import scales<Custom scales>`
* :ref:`unweight<unweight>`
* :ref:`event output<event output>`
* :ref:`analyses<analyses>`
* :ref:`random generator<random generator>`
* :ref:`log correction<log correction>`
* :ref:`vev<vev>`
* :ref:`particle properties<particle properties>`
* :ref:`Higgs coupling<Higgs coupling>`
* :ref:`off-shell tolerance<off-shell tolerance>`
.. _`Supported Generators`:
Supported Generators
--------------------------------
``HEJC`` can generate configuration files for ``HEJ`` as well as for
the following generators
.. _`HEJC Sherpa2`:
**Sherpa2**
Version 2.2 of the `Sherpa event generator <https://sherpa-team.gitlab.io/>`_.
The settings should be given in YAML format using the :code:`run`,
:code:`selector`, and :code:`analysis` keys. :code:`run` should be
a YAML map, while :code:`selector` and :code:`analysis` should be
sequences. `Sherpa tags
<https://sherpa.hepforge.org/doc/SHERPA-MC-2.2.15.html#Tags>`_ can
be set inside :code:`run:` by adding a YAML map under the key
:code:`tags`. The following entries in :code:`run` are generated
and should be omitted:
* :code:`PDF_LIBRARY`
* :code:`PDF_SET`
* :code:`USE_PDF_ALPHAS`
* :code:`BEAM_1`
* :code:`BEAM_2`
* :code:`FRAGMENTATION`
* :code:`YFS_MODE`
* :code:`MI_HANDLER`
* :code:`CSS_MAXEM`
* :code:`BEAM_REMNANTS`
* :code:`MASSIVE[4]`
* :code:`MASS[4]`
* :code:`MASSIVE[5]`
* :code:`MASS[5]`
* :code:`MASS[23]`
* :code:`MASS[23]`
* :code:`WIDTH[23]`
* :code:`MASS[24]`
* :code:`WIDTH[24]`
* :code:`MASS[25]`
* :code:`WIDTH[25]`
There is also experimental support for :code:`beam`, :code:`csv`,
:code:`me`, :code:`integration`, :code:`shower`, :code:`mi`,
:code:`fragmentation` as YAML maps, including support for Sherpa
tags.
**Sherpa2NLO**
NLO run card for Sherpa. The format is the same as for :ref:`Sherpa2<HEJC Sherpa2>`
**HEJFOG**
:ref:`HEJFOG`
The following settings are generated and should be omitted:
* :code:`jets`
* :code:`process`
* :code:`vev`
* :code:`particle properties`
* :code:`Higgs coupling`
* :code:`pdf`
* :code:`beam`