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 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 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.

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 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.16.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`