Page MenuHomeHEPForge
Files F11222061

No OneTemporary
Actions

View Options

diff --git a/Changes.md b/Changes.md
index 0c3d748..003ce83 100644
--- a/Changes.md
+++ b/Changes.md
@@ -1,191 +1,192 @@
# Changelog
This is the log for changes to the HEJ program. Further changes to the HEJ API
are documented in [`Changes-API.md`](Changes-API.md). If you are using HEJ as a
library, please also read the changes there.
## In Development (To be moved)
* Added HEJ@NLO truncation option to yaml config.
+* Added option for running lowpt contributions separately.
## Version 2.2
This release adds support for the new processes:
* Wp+Wp with jets.
* Wm+Wm with jets.
This release includes minor changes which affect users of HEJ as a library (see
[`Changes-API.md`](Changes-API.md)). Compilation now requires a
compiler supporting C++17.
### 2.2.0
#### New Processes
* Resummation for WpWp/WmWm with jets, including interference between
configurations.
* Significantly improved description of Higgs boson plus jet production:
- Processes with extremal Higgs boson emission are now treated as
leading-log.
- Resummation is now enabled for Higgs boson production with a
single jet.
* `HEJFOG` can generate multiple jets together with a charged lepton-antilepton
pair via a virtual Z boson or photon.
## Version 2.1
This release adds support for two new processes:
* W boson with jets.
* Jets with a charged lepton-antilepton pair via a virtual Z boson or photon.
In addition, the complete set of first subleading processes (unordered
gluon, central and extremal quark-antiquark pair) is implemented for
pure jets and W + jets, see
[arXiv:2012.10310](https://arxiv.org/abs/2012.10310). Unordered gluon emission
is also supported for Higgs boson + jets and Z boson/photon + jets.
This release include many changes to the code, which affect users of
HEJ as a library (see [`Changes-API.md`](Changes-API.md)).
### 2.1.3
* Updated documentation.
### 2.1.2
* Updated `cxxopts.hpp` dependency.
### 2.1.1
* Fixed invalid iterator accesses.
* Reorganised automated tests.
* Updated documentation.
### 2.1.0
#### New Processes
* Resummation for W bosons with jets
- New subleading processes `extremal qqbar` & `central qqbar` for a quark and
anti-quark in the final state, e.g. `g g => u d_bar Wm g` (the other
subleading processes also work with W's)
- `HEJFOG` can generate multiple jets together with a (off-shell) W bosons
decaying into lepton & neutrino
* Resummation for jets with a charged lepton-antilepton pair via a
virtual Z boson or photon. Includes the `unordered` subleading process.
* Resummation can now be performed on all subleading processes within pure
jets also. This includes `unordered`, `extremal qqbar` and `central
qqbar` processes.
#### More Physics implementation
* Partons now have a Colour charge
- Colours are read from and written to LHE files
- For reweighted events the colours are created according to leading colour in
the FKL limit
* Use relative fraction for soft transverse momentum in tagging jets (`soft pt
regulator`) as new (optional) parameter.
- This supersedes `min extparton pt`, which is marked **deprecated** and will
be removed in version 2.2.0
- This is a direct replacement for the old `max ext soft pt fraction`, which
is also **deprecated**.
* Changed the redistribution of the momenta of soft emissions. Now also bosons
can take part of the recoil (previously only jets).
#### Updates to Runcard
* Allow multiplication and division of multiple scale functions e.g.
`H_T/2*m_j1j2`
* Grouped `event treatment` for subleading channels together in runcard
- Rename `non-HEJ` processes to `non-resummable`
* Read electro-weak constants from input
- new mandatory setting `vev` to change vacuum expectation value
- new mandatory settings `particle properties` to specify mass & width of
bosons
- `HEJFOG`: decays are now specified in `decays` setting (previously under
`particle properties`)
* Allow loading multiple analyses with `analyses`. The old `analysis` (with "i")
is marked **deprecated**.
* Optional setting to specify maximal number of Fixed Order events (`max
events`, default is all)
* Allow changing the regulator lambda in input (`regulator parameter`, only for
advanced users)
#### Changes to Input/Output
* Added support to read & write `hdf5` event files suggested in
[arXiv:1905.05120](https://arxiv.org/abs/1905.05120) (needs
[HighFive](https://github.com/BlueBrain/HighFive))
* Support input with average weight equal to the cross section (`IDWTUP=1 or 4`)
* Support unmodified Les Houches Event Files written by Sherpa with
`cross section = sum(weights)/sum(trials)`
* Analyses now get general run information (`LHEF::HEPRUP`) in the
constructor. **This might break previously written, external analyses!**
- external analyses should now be created with
`make_analysis(YAML::Node const & config, LHEF::HEPRUP const & heprup)`
* Support `rivet` version 3 with both `HepMC` version 2 and 3
- Multiple weights with `rivet 3` will only create one `.yoda` file (instead
of one per weight/scale)
* Added option to unweight only resummation events
(`unweight: {type: resummation}`)
* Added option for partially unweighting resummation events, similar to
the fixed-order generator.
* Improved unweighting algorithm.
* Follow HepMC convention for particle Status codes: incoming = 11,
decaying = 2, outgoing = 1 (unchanged)
#### Miscellaneous
* Print cross sections at end of run
* Added example analysis & scale to `examples/`. Everything in `examples/` will
be build when the flag `-DBUILD_EXAMPLES=TRUE` is set in `cmake`.
* Dropped support for HepMC 3.0.0, either HepMC version 2 or >3.1 is required
- It is now possible to write out both HepMC 2 and HepMC 3 events at the same
time
* Require LHADPF version 6. Dropped support for all other versions.
* Use `git-lfs` for raw data in test (`make test` now requires `git-lfs`)
* Currents are now generated with [`FORM`](https://github.com/vermaseren/form)
- `FORM` is included as a `git submodule`, use `git submodule update --init`
to download `FORM`
* Create [Sphinx](http://sphinx-doc.org/) and [Doxygen](http://doxygen.org/)
documentation by `make sphinx` or `make doxygen` in your `build/` folder
## Version 2.0
First release of HEJ 2. Complete code rewrite compared to HEJ 1. Improved
matching to Fixed Order ([arXiv:1805.04446](https://arxiv.org/abs/1805.04446)).
Implemented processes: Higgs boson with jets (FKL and unordered gluon emission,
with finite quark mass loop,
[arXiv:1812.08072](https://arxiv.org/abs/1812.08072)), and pure jets (only FKL).
See [arXiv:1902.08430](https://arxiv.org/abs/1902.08430)
## 2.0.7
* Added missing `#include` directives.
### 2.0.6
* Fixed compiling rivet when YODA headers are _outside_ of rivet directory.
### 2.0.5
* Fixed event classification for input not ordered in rapidity.
### 2.0.4
* Fixed wrong path of `HEJ_INCLUDE_DIR` in `hej-config.cmake`.
### 2.0.3
* Fixed parsing of (numerical factor) * (base scale) in configuration.
* Don't change scale names, but sanitise Rivet output file names instead.
### 2.0.2
* Changed scale names to `"_over_"` and `"_times_"` for proper file names (was
`"/"` and `"*"` before).
### 2.0.1
* Fixed name of fixed-order generator in error message.
### 2.0.0
* First release.
diff --git a/doc/sphinx/HEJ.rst b/doc/sphinx/HEJ.rst
index 3198fe7..c9485ef 100644
--- a/doc/sphinx/HEJ.rst
+++ b/doc/sphinx/HEJ.rst
@@ -1,463 +1,471 @@
.. _`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 and write 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
- Production of a W boson with jets
- Production of jets with a charged lepton-antilepton pair, via a
virtual Z boson and/or photon
- Production of two same-sign W bosons with jets
where at least two jets are required in each case. For the time being,
only leading-order input 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.
.. _`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.
.. _`event treatment`:
**event treatment**
Specify how to treat different event types. The different event types
contribute to different orders 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. The following types are
implemented for the different bosons:
.. csv-table::
:header: , "FKL", "unordered", "extremal qqbar", "central qqbar"
:widths: auto
:align: center
:stub-columns: 1
"pure jets", "Yes", "Yes", "Yes", "Yes"
"Higgs + jets", "Yes", "Yes", "No", "No"
"W + jets", "Yes", "Yes", "Yes", "Yes"
"Z/γ + jets", "Yes", "Yes", "No", "No"
"same-sign W + jets", "Yes", "No", "No", "No"
Non-implemented process will always be classified as :code:`non-resummable`.
The different types are:
.. _`FKL`:
**FKL**
Specifies how to treat events respecting FKL rapidity ordering, where all
but the two partons extremal in rapidity have to be gluons, e.g.
:code:`u d => u g d`. These configurations are dominant in the high-energy
limit.
.. _`unordered`:
**unordered**
Specifies how to treat events with one gluon emission that does not respect
FKL ordering, e.g. :code:`u d => g u d`. In the high-energy limit, such
configurations are logarithmically suppressed compared to FKL
configurations.
.. _`extremal qqbar`:
**extremal qqbar**
Specifies how to treat events with a quark-antiquark pair as extremal
partons in rapidity, e.g. :code:`g d => u u_bar d`. In the high-energy
limit, such configurations are logarithmically suppressed compared to FKL
configurations.
.. _`central qqbar`:
**central qqbar**
Specifies how to treat events with a quark-antiquark pair central in
rapidity, e.g. :code:`g g => g u u_bar g`. In the high-energy limit, such
configurations are logarithmically suppressed compared to FKL
configurations.
.. _`non-resummable`:
**non-resummable**
Specifies how to treat events that do not fall into any of the above
categories or that are not yet implemented. Only :code:`keep` or
:code:`discard` are valid options, *not* :code:`reweight` for obvious
reasons.
.. _`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 overall factors, 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`.
.. _`NLO truncation`:
**NLO truncation**
Options to truncate the HEJ resummation at next-to-leading order. Used for
bin-by-bin NLO reweighting.
.. _`NLO truncation: enabled`:
**enabled**
Enable truncation. Allowed values are :code:`true` and
:code:`false` (default).
.. _`NLO truncation: nlo order`:
**nlo order**
Set the (base) number of jets in the NLO sample.
Allowed values are integers (default: 2).
.. _`unweight`:
**unweight**
Settings for unweighting events. Unweighting can greatly reduce the
number of resummation events, speeding up analyses and shrinking
event file sizes.
.. _`type`:
**type**
How to unweight events. The supported settings are
- :code:`weighted`: Generate weighted events. Default, if nothing
else specified.
- :code:`resummation`: Unweight only resummation events. Each set
of resummation events coming from *a single fixed order event*
are unweighted separately according to the largest weight in the
current chunk of events.
- :code:`partial`: Unweight only resummation events with weights
below a certain threshold. The weight threshold is determined
automatically in a calibration run prior to the usual event
generation.
.. _`unweight: trials`:
**trials**
Maximum number of trial resummation events generated in the
calibration run for partial unweighting. This option should only
be set for partial unweighting.
If possible, each trial is generated from a different input
fixed-order event. If there are not sufficiently many input
events, more than one trial event may be generated for each of
them and the actual number of trial events may be smaller than
requested.
Increasing the number of trials generally leads to better
unweighting calibration but increases the run time. Between 1000
and 10000 trials are usually sufficient.
.. _`unweight: max deviation`:
**max deviation**
Controls the range of events to which unweighting is
applied. This option should only be set for partial unweighting.
A larger value means that a larger fraction of events are
unweighted. Typical values are between -1 and 1.
.. _`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.hepmc2` or :code:`HepMC2: file`: HepMC format version 2.
- :code:`file.hepmc3` or :code:`HepMC3: file`: HepMC format version 3.
- :code:`file.hepmc` or :code:`HepMC: file`: The latest supported
version of the HepMC format, currently version 3.
- :code:`file.hdf5` or :code:`HDF5: file`: The HDF5-based format of
`arXiv:1905.05120 <https://arxiv.org/abs/1905.05120>`_.
.. _`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`.
.. _`analyses`:
**analyses**
Names and settings for one or more custom and Rivet event
analyses.
Entries containing the :code:`rivet` key are interpreted as Rivet analyses;
the values corresponding to this key should be the analyses names. In
addition, there is a mandatory :code:`output` key which determines the prefix
for the yoda output file.
For a custom analysis the :code:`plugin` sub-entry
should be set to the analysis file path. All further entries are passed on
to the analysis. See :ref:`Writing custom analyses` for details.
.. _`vev`:
**vev**
Higgs vacuum expectation value in GeV. All electro-weak constants are derived
from this together with the `particle properties`_.
.. _`particle properties`:
**particle properties**
Specifies various properties of the different particles (Higgs, W or Z). All
electro-weak constants are derived from these together with the :ref:`vacuum
expectation value<vev>`.
.. _`particle properties: particle`:
**Higgs, W or Z**
The particle (Higgs, |W+| or |W-|, Z) for which the following properties
are defined.
.. |W+| replace:: W\ :sup:`+`
.. |W-| replace:: W\ :sup:`-`
.. _`particle properties: particle: mass`:
**mass**
The mass of the particle in GeV.
.. _`particle properties: particle: width`:
**width**
The total decay width of the particle in GeV.
.. _`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.
.. _`soft pt regulator`:
**soft pt regulator**
Specifies the maximum fraction that soft radiation can contribute to the
transverse momentum of each the tagging jets, i.e. any jet that affects the
event classification, like the most forward and most backward jet or the jets
of the central qqbar pair. This setting is needed to regulate an otherwise
- cancelled divergence. Default is 0.1
+ cancelled divergence. Default is 0.1.
.. _`max ext soft pt fraction`:
**max ext soft pt fraction**
This is the same as `soft pt regulator`_ and will be removed in future
versions.
.. _`min extparton pt`:
**min extparton pt**
Specifies the minimum transverse momentum in GeV of the most forward and the
most backward parton. Its value should be slightly below the minimum
transverse momentum of jets specified by `resummation jets: min pt`_. This
setting got superseded by `soft pt regulator`_ and will be removed in future
versions.
.. _`max events`:
**max events**
Maximal number of (input) Fixed Order events. HEJ will stop after processing
`max events` many events. Default considers all events.
.. _`regulator parameter`:
**regulator parameter**
Slicing parameter to regularise the subtraction term, called :math:`\lambda`
- in `arxiv:1706.01002 <https://arxiv.org/abs/1706.01002>`_. Default is 0.2
+ in `arxiv:1706.01002 <https://arxiv.org/abs/1706.01002>`_. Default is 0.2.
+
+.. _`lowpt only`:
+
+**lowpt only**
+ Restrict output to only include events which have fixed order jets with pT
+ less than the `resummation jets: min pt`_ and have resummation jets above
+ `resummation jets: min pt`_.
+

File Metadata

Mime Type
text/x-diff
Expires
Wed, May 14, 11:20 AM (14 h, 33 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
5108301
Default Alt Text
(24 KB)

Event Timeline