Les Houches Accord

The Les Houches Accord (LHA) for user processes [Boo01] is the standard way to input parton-level information from a matrix-elements-based generator into PYTHIA. The conventions for which information should be stored has been defined in a Fortran context, as two commonblocks. Here a C++ equivalent is defined, as two separate classes.

The LHAinit and LHAevnt classes are base classes, containing reading and printout functions, plus a pure virtual function each. Derived classes have to provide these two virtual functions to do the actual work. The existing derived classes are for reading information from a Les Houches Event File (LHEF) or from the respective Fortran commonblock.

Normally, pointers to objects of the derived classes should be handed in with the pythia.init( LHAinit*, LHAevnt*) method. However, with the LHEF format a filename can replace the two pointers, see below.

Initialization

The LHAinit class stores information equivalent to the /HEPRUP/ commonblock, as required to initialize the event generation chain. The main difference is that the vector container now allows a flexible number of subprocesses to be defined. For the rest, names have been modified, since the 6-character-limit does not apply, and variables have been regrouped for clarity, but nothing fundamental is changed.

The pure virtual function set() has to be implemented in the derived class, to set relevant information when called. It should return false if it fails to set the info.

Inside set(), such information can be set by the following methods:

method  beamA( identity, energy, pdfGroup, pdfSet)  
sets the properties of the first incoming beam (cf. the Fortran IDBMUP(1), EBMUP(1), PDFGUP(1), PDFSUP(1)), and similarly a beamB method exists. The parton distribution information defaults to zero, meaning that internal sets are used.

method  strategy( strategyIn)  
sets the event weighting and cross section strategy. The default, provided in the class constructor, is 3.
argument strategyIn : chosen strategy (cf. IDWTUP; see [Sjo06] section 9.9.1 for extensive comments).
argumentoption 1 : events come with non-negative weight, given in units of pb, with an average that converges towards the cross section of the process. PYTHIA is in charge of the event mixing, i.e. for each new try decides which process should be generated, and then decides whether is should be kept based on a comparison with xMax. Accepted events therefore have unit weight.
argumentoption -1 : as option 1, except that cross sections can now be negative and events after unweighting have weight +-1. You can use pythia.info.weight() to find the weight of the current event. A correct event mixing requires that a process that can take both signs should be split in two, one limited to positive or zero and the other to negative or zero values, with xMax chosen appropriately for the two.
argumentoption 2 : events come with non-negative weight, in unspecified units, but such that xMax can be used to unweight the events to unit weight. Again PYTHIA is in charge of the event mixing. The total cross section of a process is stored in xSec.
argumentoption -2 : as option 2, except that cross sections can now be negative and events after unweighting have weight +-1. As for option -1 processes with indeterminate sign should be split in two.
argumentoption 3 : events come with unit weight, and are thus accepted as is. The total cross section of the process is stored in xSec.
argumentoption -3 : as option 3, except that events now come with weight +-1. Unlike options -1 and -2 processes with indeterminate sign need not be split in two, unless you intend to mix with internal PYTHIA processes (see below).
argumentoption 4 : events come with non-negative weight, given in units of pb, with an average that converges towards the cross section of the process, like for option 1. No attempt is made to unweight the events, however, but all are generated in full, and retain their original weight. For consistency with normal PYTHIA units, the weight stored in pythia.info.weight() has been converted to mb, however.
argumentoption -4 : as option 4, except that events now can come either with positive or negative weights.
Note 1: if several processes have already been mixed and stored in a common event file, either LHEF or some private format, it would be problematical to read back events in a different order. Since it is then not feasible to let PYTHIA pick the next process type, strategies +-1 and +-2 would not work. Instead strategy 3 would be the recommended choice, or -3 if negative-weight events are required.
Note 2: it is possible to switch on internally implemented processes and have PYTHIA mix these with LHA ones according to their relative cross sections for strategies +-1, +-2 and 3. It does not work for strategy -3 unless the positive and negative sectors of the cross sections are in separate subprocesses (as must always be the case for -1 and -2), since otherwise the overall mixture of PYTHIA and LHA processes will be off. Mixing is not possible for strategies +-4, since the weighting strategy is unspecified.

method  process( idProcess, xSec, xErr, xMax)  
sets info on an allowed process (cf. LPRUP, XSECUP, XERRUP, XMAXUP). Each new call will append one more entry to the list of processes. The choice of strategy determines which quantities are mandatory: xSec for strategies +-2 and +-3, xErr never, and xMax for strategies +-1 and +-2.
Note: PYTHIA does not make active use of the (optional) xErr values, but calculates a statistical cross section error based on the spread of event-to-event weights. This should work fine for strategy options +-1, but not for the others. Specifically, for options +-2 and +-3 the weight spread may well vanish, and anyway is likely to be an underestimate of the true error. If the author of the LHA input information does provide error information you may use that - this information is displayed at initialization. If not, then a relative error decreasing like 1/sqrt(n_acc), where n_acc is the number of accepted events, should offer a reasonable estimate.

Information is handed back by the following methods:

method  idBeamA(), eBeamA(), pdfGroupBeamA(), pdfSetBeamA()  
and similarly with A -> B, for the two beam particles.

method  strategy()  
for the strategy choice.

method  size()  
for the number of subprocesses.

method  idProcess(i), xSec(i), xErr(i), xMax(i)  
for process i in the range 0 <= i < size().

The information can also be printed using the list() method, e.g. LHAinitObject->list(). This is automatically done by the pythia.init call.

Event input

The LHAevnt class stores information equivalent to the /HEPEUP/ commonblock, as required to hand in the next parton-level configuration for complete event generation. The main difference is that the vector container now allows a flexible number of partons to be defined. For the rest, names have been modified, since the 6-character-limit does not apply, and variables have been regrouped for clarity, but nothing fundamental is changed.

The LHA standard is based on Fortran arrays beginning with index 1, and mother information is defined accordingly. In order to be compatible with this convention, the zeroth line of the C++ particle array is kept empty, so that index 1 also here corresponds to the first particle. One small incompatibility is that the size() method returns the full size of the particle array, including the empty zeroth line, and thus is one larger than the true number of particles (NUP).

The pure virtual function set(idProcess) has to be implemented in the derived class, to set relevant information when called. For strategy options +-1 and +-2 the input idProcess value specifies which process that should be generated by set(...), while idProcess is irrelevant for strategies +-3 and +-4. The set(...) function should return false if it fails to set the info, i.e. normally that the supply of events in a file is exhausted. If so, no event is generated, and pythia.next() returns false. You can then interrogate pythia.info.atEndOfFile() to confirm that indeed the failure is caused in the set(...) function, and decide to break out of the event generation loop.

Inside a normal set(...) call, information can be set by the following methods:

method  process( idProcess, weight, scale, alphaQED, alphaQCD)  
tells which kind of process occured, with what weight, at what scale, and which alpha_EM and alpha_strong were used (cf. IDPRUP, XWTGUP, SCALUP, AQEDUP, AQCDUP). This method also resets the size of the particle list, and adds the empty zeroth line, so it has to be called before the particle method below.

method  particle( id, status, mother1, mother2, colourTag1, colourTag2, p_x, p_y, p_z, e, m, tau, spin)  
gives the properties of the next particle handed in (cf. IDUP, ISTUP, MOTHUP(1,..), MOTHUP(2,..), ICOLUP(1,..), ICOLUP(2,..), PUP(J,..), VTIMUP, SPINUP) .

Information is handed back by the following methods:

method  idProcess(), weight(), scale(), alphaQED(), alphaQCD()  
Note that the weight stored in pythia.info.weight() as a rule is not the same as the above weight(): the method here gives the value before unweighting while the one in info gives the one after unweighting and thus normally is 1 or -1. Only with strategy options +-4 would the value in info be the same as here, except for a conversion from pb to mb.

method  size()  
for the size of the particle array, which is one larger than the number of particles in the event, since the zeroth entry is kept empty (see above).

method  id(i), status(i), mother1(i), mother2(i), col1(i), col2(i),px(i), py(i), pz(i), e(i), m(i), tau(i), spin(i)  
for particle i in the range 0 <= i < size(). (But again note that i = 0 is an empty line, so the true range begins at 1.)

In the LHEF description [Alw06] an extension to include information on the parton densities of the colliding partons is suggested. This optional further information can be set by

method  pdf( id1, id2, x1, x2, scalePDF, xpdf1, xpdf2)  
which gives the flavours , the x and the Q scale (in GeV) at which the parton densities x*f_i(x, Q) have been evaluated.

This information is returned by the methods

method  pdfIsSet(), id1(), id2(), x1(), x2(), scalePDF(), xpdf1(), xpdf2()  
where the first one tells whether this optional information has been set for the current event. (pdf(...) must be called after the process(...) call of the event for this to work.)

The information can also be printed using the list() method, e.g. LHAevntObject->list(). In cases where the LHAevntObject is not available to the user, the pythia.LHAevntList() method can be used, which is a wrapper for the above.

The LHA expects the decay of resonances to be included as part of the hard process, i.e. if unstable particles are produced in a process then their decays are also described. This includes Z^0, W^+-, H^0 and other short-lived particles in models beyond the Standard Model. Should this not be the case then PYTHIA will perform the decays of all resonances it knows how to do, in the same way as for internal processes. Note that you will be on slippery ground if you then restrict the decay of these resonances to specific allowed channels since, if this is not what was intended, you will obtain the wrong cross section and potentially the wrong mix of different event types. (Since the original intention is unknown, the cross section will not be corrected for the fraction of open channels, i.e. the procedure used for internal processes is not applied in this case.)

An interface to Les Houches Event Files

The LHEF standard [Alw06] specifies a format where a single file packs initialization and event information. This has become the most frequently used procedure to process external parton-level events in Pythia. Therefore a special pythia.init(fileName) initialization option exists, where the LHEF name is provided as single input. Internally this name is then used to create instances of two derived classes, LHAinitLHEF and LHAevntLHEF. Both of them are allowed to read from the same LHEF, first the former and then the latter.

An example how to generate events from a LHEF is found in main12.cc. Note the use of pythia.info.atEndOfFile() to find out when the whole LHEF has been processed.

To allow the sequential use of several event files the init(...) method has an optional second argument: pythia.init(fileName, bool skipInit = false). If called with this argument true then there will be no initialization, except that the existing LHAinitLHEF and LHAevntLHEF classes will be deleted and replaced by ones pointing to the new file. It is assumed (but never checked) that the initialization information is identical, and that the new file simply contains further events of exactly the same kind as the previous one. An example of this possibility, and the option to mix with internal processes, is found in main13.cc.

A runtime Fortran interface

The runtime Fortran interface requires linking to an external Fortran code. In order to avoid problems with unresolved external references when this interface is not used, the code has been put in a separate LHAFortran.h file, that is not included in any of the other library files. Instead it should be included in the user-supplied main program, together with the implementation of two methods below that call the Fortran program to do its part of the job.

The LHAinitFortran class derives from LHAinit. It reads initialization information from the LHA standard Fortran commonblock, assuming this commonblock behaves like an extern "C" struct named heprup_. (Note the final underscore, to match how the gcc compiler internally names Fortran files.)

Initialization is with

    LHAinitFortran lhaInit();
i.e. does not require any arguments.

The user has to supply an implementation of the fillHepRup() method, that is to do the actual calling of the external Fortran routine(s) that fills the HEPRUP commonblock. The translation of this information to the C++ structure is provided by the existing set() code.

The LHAevntFortran class derives from LHAevnt. It reads information on the next event, stored in the LHA standard Fortran commonblock, assuming this commonblock behaves like an extern "C" struct named hepeup_.

Initialization is with

    LHAevntFortran lhaEvnt();
i.e. does not require any arguments.

The user has to supply an implementation of the fillHepEup() method, that is to do the actual calling of the external Fortran routine(s) that fills the HEPEUP commonblock. The translation of this information to the C++ structure is provided by the existing set() code.

See further here for information how PYTHIA 6.4 can be linked to make use of this facility.