HepMC3 event record library
Namespaces
LHEF - Handling Les Houches Event Files

Namespaces

 LHEF
 Les Houches event file classes.
 

Detailed Description

This module contains helper classes and Reader and Writer classes for handling Les Houches event files - LHEF.

Introduction

The Les Houches accord on an event file format (LHEF) to be used for passing events from a matrix element generator program (MEG) to an event generator program (EG) implementing parton showers, underlying event models, and hadronisation models etc., was not originally included in the HepMC event record format. But as the demand for more information to be included in HepMC, it was decided to allow HepMC to include also the original information from a MEG in the LHEF format (see the run attribute HepMC3::HEPRUPAttribute and event attribute HepMC3::HEPEUPAttribute). A separate /standard/ implementation in C++ of the LHEF format had already been maintained by Leif Lönnblad, and it was decided to include this (header only - LHEF.h) as a part of HepMC3. This will both be used in above mentioned HepMC3::Attribute classes and as a kind of definition of the LHEF format, which so far has not been extremely well documented. From now on these pages will serve as the defining information about the LHEF format.

Background

The original Les Houches accord for communicating between MEGs and EGs was agreed upon in 2001 [arXiv:hep-ph/0109068] and consisted of two simple FORTRAN common blocks. In fact this structure survived in the LHEF format, which was introduced in 2006 [arXiv:hep-ph/0609017], and is still there after the updated versions 2 in 2009 [arXiv:1003.1643], and 3 in 2013 [arXiv:1405.1067], and in the current proposal developed at the Les Houches workshop on TeV Colliders 2015 .

As the methods for combining MEGs and EGs has advanced since the first accord, from the tree-level merging methods and NLO matching at the turn of the millennium, to the multi-jet (N)NLO matching and merging methods being perfeted to day, the LHEF format has developed and a lot of optional information can be passed beyond the original common block structures. In the following all features included will be described, also those that were added a bit prematurely and later became deprecated.

The basic structure

The LHEF format is based on XML, but has some oddities that goes beyond pure XML. As the name indicates, XML is extensible, and anyone writing a LHEF file can add whatever information she or he wants, however the following basic stucture must be observed.

<LesHouchesEvents version="3.0">
<!--
# optional information in completely free format,
# except for the reserved end tag (see next line)
-->
<header>
<!-- individually designed XML tags, in fancy XML style -->
</header>
<init>
compulsory initialization information
# optional initialization information
</init>
<event>
compulsory event information
# optional event information
</event>
<event>
compulsory event information
<!-- more optional information -->
</event>
<!-- and as many events that you want, but ending with -->
</LesHouchesEvents>

This looks like fairly normal XML tags, and indeed they are. The only addition to the structure is that the init and event (and their respective end tags) are required to be alone on a line, and the content of these blocks are required to start with a number of lines on a specific format that follows exactly the structure of the fortran common block in original Les Houches Accord. This means that the first line in the init block must start with a line containing the numbers

IDBMUP(1) IDBMUP(2) EBMUP(1) EBMUP(2) PDFGUP(1) PDFGUP(2) PDFSUP(1) PDFSUP(2) IDWTUP NPRUP

and the following NPRUP lines should be numbers on the form

XSECUP(IPR) XERRUP(IPR) XMAXUP(IPR) LPRUP(IPR)

where the different variable names are defined as follows:

and for each process IPR:

In the LHEF::Reader and LHEF::Writer classes this information is available as the public heprup member of class LHEF::HEPRUP with public members mimicking the Fortran common block variables.

Similarly, every event block must start with a line containing then numbers

NUP IDPRUP XWGTUP SCALUP AQEDUP AQCDUP

and the following NUP lines should be numbers describing each particle on the form

IDUP(I) ISTUP(I) MOTHUP(1,I) MOTHUP(2,I) ICOLUP(1,I) ICOLUP(2,I) PUP(1,I) PUP(2,I) PUP(3,I) PUP(4,I) PUP(5,I) VTIMUP(I) SPINUP(I)

where the different variable names are defined as follows:

and for each particle I:

In the LHEF::Reader and LHEF::Writer classes this information is available as the public hepeup member of class LHEF::HEPEUP with public members mimicking the Fortran common block variables.

Additional information

Over the years several additional XML-tags has been formalised to specify information on top of what is given in the original Les Houches accord common block. These are listed below. In most cases the tag name corresponds to a class with a corresponding name available as suitably named public members in the LHEF::HEPRUP and LHEF::HEPEUP class respectively.

Note that a tag may contain attributes in the following ways:

<tag attribute1="value" attribute2="value">things marked by the tag</tag>
<tag attribute1="value" attribute2="value" attribute3="value" />

where the second case is a tag with only attributes an no contents. In the following an attribute may be described as required (R) or optional with a default value (D).

Standardised tags in the events block.

The <init> block contains information about the full run (similar to the information contained in HepMC3::GenRunInfo). The following tags are defined.

Standardised tags in the events block.

After the init block any number of events can be given. In addition events can be given in separate files declared with eventfile tags in the init block.

The main tag here is simply called event and can (for statistics purposes) have an attribute ntries specifying how many attempts the generator needed to produce the event. Also other attributes can be given (and will be stored in the LHEF::HEPEUP::attributes member variable).

The event tags may be grouped together in a eventgroup tag. This is useful mainly for NLO generators that produces a (number) "real" event(s) accompanied with a number of "counter" events, where these events should be treated together for statistics purposes. For this reason the eventgroup tag can be provided with the optional tags nreal and ncounter to indicate the number of event tags included of each type.

As indicated above the block must start with required information corresponding to the original Les Houches Accord Fortran common block. Here is a list of additional tags that may be provided.