 <chapter name="ALPGEN Event Interface"> 
 
<h2>ALPGEN Event Interface</h2> 
 
This manual page describes the ALPGEN <ref>Man03</ref> 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 <code>JetMatchingAlpgen</code> 
described on the <aloc href="JetMatching">Jet Matching</aloc> 
page. However, it will also work with a implementation of the 
Madgraph-style <ref>Alw11</ref> parton-jet matching 
<code>JetMatchingMadgraph</code> also described on the 
<aloc href="JetMatching">Jet Matching</aloc> page. 
A sensible choice of <code>JetMatching</code> parameters is needed 
when using ALPGEN files with Madgraph-style matching and vice versa. 
 
<p/> 
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 <code>include/Pythia8Plugins/</code> subdirectory: 
<ul> 
<li> 
<code>GeneratorInput.h</code> : provides three classes for the reading of 
ALPGEN event and parameter files. <code>LHAupAlpgen</code> is an 
<aloc href="LHA"><code>LHAup</code></aloc> derived 
class for reading in ALPGEN native format event files. 
<code>AlpgenPar</code> is a class for the parsing of ALPGEN parameter 
files, making the information available through a simple interface. 
<code>AlpgenHooks</code> is a 
<aloc href="UserHooks"><code>UserHooks</code></aloc> derived class that 
provides the <code>Alpgen:*</code> options, described below. Further 
technical details of these classes are given at the end of this manual 
page. 
</li> 
<li> 
<code>main32.cc, main32.cmnd</code> : a sample main program and card 
file showing the usage of previous file and an MLM <code>UserHooks</code> 
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. 
</li> 
<li> 
<code>main32.unw, main32_unw.par</code> : 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. 
</li> 
</ul> 
 
<h3>ALPGEN main options</h3> 
 
These following options are provided by the AlpgenHooks class, 
which must be loaded for this functionality to be present 
 
<p/> 
ALPGEN event files that have been written out in LHEF format should be 
read in through the normal LHEF machinery 
(see <aloc href="BeamParameters">Beam Parameters</aloc>). Files in 
ALPGEN's native format, instead, may be processed using the 
<code>Alpgen:file</code> option below. When using this option, the 
ALPGEN parameter file is stored in the PYTHIA Info object under the key 
<code>AlpgenPar</code>, see the "Header information" section of the 
<aloc href="EventInformation">Event Information</aloc> manual page for 
more details. Processes not implemented by the PYTHIA 6 interface 
supplied with ALPGEN are also not implemented here. 
 
<p/> 
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 <ei>b</ei> 
quarks may give rise to these warnings. 
 
<p/> 
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 <code>README</code> file in the main directory contains instructions 
on how to enable this. 
 
<p/> 
All other <code>Alpgen:*</code> 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 name="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 <ei>input_unw.par</ei> and <ei>input.unw</ei>, the value 
<ei>input</ei> should be used. 
</word> 
 
<flag name="Alpgen:setLightMasses" default="off"> 
When switched on, <ei>c</ei> and <ei>b</ei> quark masses provided 
by ALPGEN are set in the PYTHIA 
<aloc href="ParticleDataScheme">particle database</aloc>. 
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> 
 
<flag name="Alpgen:setHeavyMasses" default="on"> 
When switched on, <ei>t</ei>, <ei>Z</ei>, <ei>W</ei> and <ei>H</ei> 
masses provided by ALPGEN are set in the PYTHIA 
<aloc href="ParticleDataScheme">particle database</aloc>. 
</flag> 
 
<flag name="Alpgen:setMLM" default="on"> 
When switched on, the merging parameters (see below) are set according to 
the ALPGEN hard process cuts: 
<ul> 
<li> <code>JetMatching:eTjetMin = min(ptjmin + 5., 1.2 * ptjmin)</code>, </li> 
<li> <code>JetMatching:coneRadius = drjmin</code>, </li> 
<li> <code>JetMatching:etaJetMax = etajmax</code>.</li> 
</ul> 
where the <code>ptjmin</code>, <code>drjmin</code> and 
<code>etajmax</code> are the incoming ALPGEN parameters. Note that any 
existing values of these parameters are overwritten. 
</flag> 
 
<flag name="Alpgen:setNjet" default="on"> 
When switched on, the <code>JetMatching:nJet</code> parameter (see below) 
is set to the incoming <code>njet</code> ALPGEN parameter. Note that any 
existing value of this parameter is overwritten. 
</flag> 
 
<h3>Class information</h3> 
 
Some more technical information about the different classes is given 
below. For clarity, some limited information on certain private methods 
is provided. 
 
<h4>LHAupAlpgen</h4> 
 
This class is derived from the 
<aloc href="LHA"><code>LHAup</code></aloc> 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 <code>AlpgenPar</code>. 
 
<method name="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 <code>AlpgenPar</code> 
class, described below, used to parse the parameter file. 
</method> 
 
<method name="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. 
</method> 
 
<method name="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, <ei>pT</ei> is made to balance by splitting any 
imbalance between all outgoing particles with their energies also 
scaled. Second, the <ei>e/pZ</ei> of the two incoming particles are 
scaled to balance the outgoing particles. Finally, any intermediate 
resonances are recalculated from their decay products. 
</method> 
 
<h4>AlpgenPar</h4> 
 
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: 
<pre>  ************** run parameters </pre> 
are ignored, and in the general case, a line e.g. 
<pre>  10   3.00000000000000        ! njets</pre> 
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: 
<pre> 
  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 
</pre> 
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. 
 
<method name="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. 
</method> 
 
<method name="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. 
</method> 
 
<method name="bool AlpgenPar::haveParam(const string &amp;paramIn)"> 
Method to check if a parameter with key <code>paramIn</code> is present. 
Returns true if present, else false. 
</method> 
 
<method name="double AlpgenPar::getParam(const string &amp;paramIn)"> 
</method> 
<methodmore name="int AlpgenPar::getParamAsInt(const string &amp;paramIn)"> 
Return the parameter with key <code>paramIn</code> as a double or 
integer. The presence of a parameter should have already been checked 
using the <code>haveParam()</code> function above. If the parameter is 
not present, 0 is returned. 
</methodmore> 
 
<method name="void AlpgenPar::void printParams()"> 
Method to print a list of stored parameters. 
</method> 
 
<h4>AlpgenHooks</h4> 
 
This <aloc href="UserHooks"><code>UserHooks</code></aloc> derived class 
provides all the <code>Alpgen:*</code> 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. 
 
<method name="AlpgenHooks(Pythia &amp;pythia)"> 
The constructor takes a PYTHIA object as input, so that the beam 
parameter settings can be overridden if the <code>Alpgen:file</code> 
option is given. If this is the case, an <code>LHAupAlpgen</code> 
instance is automatically created and passed to PYTHIA. 
</method> 
 
<method name="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 
<code>AlpgenPar</code> class is used to parse ALPGEN parameters, if 
present, which are then used to set further PYTHIA settings. 
</method> 
 
</chapter> 
 
<!-- Copyright (C) 2020 Torbjorn Sjostrand --> 
