ALPGEN Event Interface

This manual page describes the ALPGEN [Man03] event interface for PYTHIA8. While future versions of ALPGEN will be able to write out events in LHEF format, previous versions always output events in an ALPGEN native format (a combination of a ".unw" and a "_unw.par" file). The ALPGEN component of this code contains a reader for this native format (for unweighted events), as well as parameter reading for both ALPGEN native and LHE file formats. The reader was designed to work together with an implementation of the ALPGEN-style parton-jet matching JetMatchingAlpgen described on the Jet Matching page. However, it will also work with a implementation of the Madgraph-style [Alw11] parton-jet matching JetMatchingMadgraph also described on the Jet Matching page. A sensible choice of JetMatching parameters is needed when using ALPGEN files with Madgraph-style matching and vice versa.

It should be noted that all the functionality described here is provided through external routines, and therefore the presence of these features is dependent on the main program being used. This structure allows for the easy extensibility of the merging scheme. The files of interest are located in the include/Pythia8Plugins/ subdirectory:

GeneratorInput.h : provides three classes for the reading of ALPGEN event and parameter files. LHAupAlpgen is an LHAup derived class for reading in ALPGEN native format event files. AlpgenPar is a class for the parsing of ALPGEN parameter files, making the information available through a simple interface. AlpgenHooks is a UserHooks derived class that provides the Alpgen:* options, described below. Further technical details of these classes are given at the end of this manual page.
main32.cc, main32.cmnd : a sample main program and card file showing the usage of previous file and an MLM UserHooks class. In combination, it reads in a sample ALPGEN (or Madgraph) event file while performing the MLM merging procedure as implemented in ALPGEN (or as in Madgraph). Some commented-out sets of options are provided in the card file, which can be activated to try different merging setups.
main32.unw, main32_unw.par : an ALPGEN format event and parameter file containing 100 W + 3 jet events. It is not feasible to package large event files with the PYTHIA distribution, but this sample is enough to show the different components in action.

ALPGEN main options

These following options are provided by the AlpgenHooks class, which must be loaded for this functionality to be present

ALPGEN event files that have been written out in LHEF format should be read in through the normal LHEF machinery (see Beam Parameters). Files in ALPGEN's native format, instead, may be processed using the Alpgen:file option below. When using this option, the ALPGEN parameter file is stored in the PYTHIA Info object under the key AlpgenPar, see the "Header information" section of the Event Information manual page for more details. Processes not implemented by the PYTHIA 6 interface supplied with ALPGEN are also not implemented here.

When reading in ALPGEN native event files, some momenta are shifted by the file reader to ensure energy-momentum conservation. The magnitude of these shifts should be small (around the MeV level in the worst case) and warnings will be produced if they are above a set threshold. A large number of warnings may signify unexpected behaviour and should potentially be investigated. It is also known that certain event classes, for example an event with both light and heavy b quarks may give rise to these warnings.

The ALPGEN file reader supports the reading of the event and parameter files in gzip format with file extensions ".unw.gz" and "_unw.par.gz" respectively. This requires the use of external libraries, however, and the README file in the main directory contains instructions on how to enable this.

All other Alpgen:* options apply to both LHE and native file formats, and include options to guide the MLM merging procedure based on the parameters that are read in with the events file.

word Alpgen:file (default = void)
This option is used to read in ALPGEN format event files. Using this option overrides any previously set beam options inside PYTHIA. The path to the files, not including any file extension, should be provided e.g. for input files input_unw.par and input.unw, the value input should be used.

flag Alpgen:setLightMasses (default = off)
When switched on, c and b quark masses provided by ALPGEN are set in the PYTHIA particle database. Since ALPGEN may set these two masses to vanish, the parton shower programs have been provided with some protection, but other parts of the code may not be as fortunate. You should therefore only switch on this option if you know what you are doing.

flag Alpgen:setHeavyMasses (default = on)
When switched on, t, Z, W and H masses provided by ALPGEN are set in the PYTHIA particle database.

flag Alpgen:setMLM (default = on)
When switched on, the merging parameters (see below) are set according to the ALPGEN hard process cuts:

JetMatching:eTjetMin = min(ptjmin + 5., 1.2 * ptjmin),
JetMatching:coneRadius = drjmin,
JetMatching:etaJetMax = etajmax.

where the ptjmin, drjmin and etajmax are the incoming ALPGEN parameters. Note that any existing values of these parameters are overwritten.

flag Alpgen:setNjet (default = on)
When switched on, the JetMatching:nJet parameter (see below) is set to the incoming njet ALPGEN parameter. Note that any existing value of this parameter is overwritten.

Class information

Some more technical information about the different classes is given below. For clarity, some limited information on certain private methods is provided.

LHAupAlpgen

This class is derived from the LHAup base class, and uses the standard machinery to pass initialisation and event data to PYTHIA. These standard functions are not documented here. The complete parameter file is stored in the PYTHIA Info object, if given, under the key AlpgenPar.

LHAupAlpgen::LHAupAlpgen(const char *baseFNin, Info *infoPtrIn = NULL)
The constructor for the class takes the base filename for the ALPGEN format files (without file extensions) and optionally a pointer to a PYTHIA Info class, used for warning/error message printing and for storing the ALPGEN parameter file. The event and parameter files are opened immediately, with the AlpgenPar class, described below, used to parse the parameter file.

bool LHAupAlpgen::addResonances()
This is a private method used when an event is read in. The information read from the event file does not always contain a complete listing of all particles and four-momenta, and so various details must be reconstructed. Exactly which details are filled in can vary based on the ALPGEN process in question.

bool LHAupAlpgen::rescaleMomenta()
This is another private method used when an event is read in. It shuffles and rescales momenta in an event to ensure energy-momentum conservation. First, pT is made to balance by splitting any imbalance between all outgoing particles with their energies also scaled. Second, the e/pZ of the two incoming particles are scaled to balance the outgoing particles. Finally, any intermediate resonances are recalculated from their decay products.

AlpgenPar

This class parses an ALPGEN parameter file and makes the information available through a simple interface. The information is stored internally in key/value (string/double) format. All lines prior to:

  ************** run parameters

are ignored, and in the general case, a line e.g.

  10   3.00000000000000        ! njets

would be stored with key "njets" and value "3.0". The following lines are special cases where the line may be split or the key translated:

 
  3 ! hard process code 
  0.000   4.700 174.300  80.419  91.188 120.000 ! mc,mb,mt,mw,mz,mh 
  912.905 0.0914176   ! Crosssection +- error (pb) 
  100 29787.4  ! unwtd events, lum (pb-1) Njob= 2

In the first line, the key "hard process code" is translated to "hpc". In the second, the mass values are split and each given an entry in the internal store. In the third, the cross section and cross section error are stored under the keys "xsecup" and "xerrup" respectively. Finally, the number of events and luminosity are stored under the keys "nevent" and "lum" respectively. In the event that a duplicate key is present, with differing values, the stored value is overwritten and a warning given.

AlpgenPar::AlpgenPar(Info *infoPtrIn = NULL)
The constructor does nothing except for store the PYTHIA Info pointer, if given. This is used for warning/error message printing.

bool AlpgenPar::parse(const string paramStr)
This method parses an ALPGEN parameter file. The parameter file is passed as a single string, mainly intended to be read out from the PYTHIA Info object using the header information methods.

bool AlpgenPar::haveParam(const string &paramIn)
Method to check if a parameter with key paramIn is present. Returns true if present, else false.

double AlpgenPar::getParam(const string &paramIn)
int AlpgenPar::getParamAsInt(const string &paramIn)
Return the parameter with key paramIn as a double or integer. The presence of a parameter should have already been checked using the haveParam() function above. If the parameter is not present, 0 is returned.

void AlpgenPar::void printParams()
Method to print a list of stored parameters.

AlpgenHooks

This UserHooks derived class provides all the Alpgen:* options. It is provided as a UserHooks class such that the code works regardless of whether ALPGEN native or LHE file formats are used. It is declared with virtual inheritance so that it may be combine with other UserHooks classes, see the "Combining UserHooks" section below.

AlpgenHooks(Pythia &pythia)
The constructor takes a PYTHIA object as input, so that the beam parameter settings can be overridden if the Alpgen:file option is given. If this is the case, an LHAupAlpgen instance is automatically created and passed to PYTHIA.

bool initAfterBeams()
This is the only UserHooks method that is overridden. It is called directly after PYTHIA has initialised the beams, and therefore the header information should be present in the PYTHIA Info object. The AlpgenPar class is used to parse ALPGEN parameters, if present, which are then used to set further PYTHIA settings.