The Les Houches Accord
The Les Houches Accord 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. Currently the only derived classes are for reading
information from the respective Fortran commonblock or for reading
it from PYTHIA 6.4-produced files.
Normally, pointers to objects of the derived classes should be handed
in with the pythia.init()
method. (If you use the LHA
interface to PYTHIA 6.4, this is taken care of
internally, so no pointers need to be handed in.)
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.
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 name="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 name="strategy( choice)"
sets the event weighting and cross section strategy
(cf. IDWTUP
).
method name="process( idProcess, crossSection, crossSectionError,
crossSectionMaximum)"
sets info on an allowed process (cf. LPRUP, XSECUP, XERRUP,
XMAXUP
).
Each new call will append one more entry to the list of processes.
Information is handed back by the following methods:
method name="idBeamA(), eBeamA(), pdfGroupBeamA(), pdfSetBeamA()"
and similarly with A -> B, for the two beam particles.
method name="strategy()"
for the strategy choice.
method name="size()"
for the number of subprocesses.
method name="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 overloaded
<< operator, e.g. cout << LHAinitObject
.
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.
The Les Houches 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()
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, e.g. if the
supply of events in a file is exhausted.
Inside set()
, cuch information can be set by the following
methods:
method name="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 name="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 name="idProc(), weight(), scale(), alphaQED(), alphaQCD()".
method name="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 name="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.)
The information can also be printed using the overloaded
<< operator, e.g. cout << LHAevntObject
.
A runtime Fortran interface
The LHAinitFortran
class derives from LHAinit
.
It reads initialization information from the Les Houches 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 LHAevntFortran
class derives from LHAevnt
.
It reads information on the next event, stored in the Les Houches
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.
See further the page on "Accessing PYTHIA 6 Processes" for information
how PYTHIA 6.4 can be linked to make use of this facility.
Several of the example main programs illustrate how it can be used.
An interface to PYTHIA 6 files
The LHAinitPythia6
class derives from LHAinit
.
It reads initialization information, written from PYTHIA 6.4
with the PYUPIN
routine, from a given file. The file name
should be given as argument at the instantiation, e.g.
LHAinitPythia6 lhaInit("ttsample.init");
Thw LHAevntPythia6
class derives from LHAevnt
.
It reads information on the next event, written from PYTHIA 6.4 with
the PYUPEV
routine, from a given file. The file name should be
given as argument at the instantiation, e.g.
LHAevntPythia6 lhaEvnt("ttsample.evnt");
The PYUPEV
routine writes mother indices using the Fortran
(and Les Houches) convention of the first particle being number 1,
and so matches the C++ "fix" of an empty zeroth particle.
An example how to use events in such exernal files is found in
main02.cc
.
Other examples
A special strategy = 10
(not present in the IDWTUP
specification) has been added. It takes a given partonic input,
no questions asked, and hadronizes it, i.e. does string fragmentation
and decay. Thereby the normal process-level and parton-level machineries
are bypassed, to the largest extent possible. (Some parts are used,
e.g. first to translate the Les Houches event to the process record
and later to the event record.) Such an option can therefore be used
to feed in ready-made parton-level configurations, without needing to
specify where these come from, i.e. there need be no beams or any such
explicit information, but of course the user must have taken care of it
beforehand.
An example how this can be used for toy studies is found in
main03.cc
.