LHAup
class is a base class, containing reading and
printout functions, plus two pure virtual functions, one to set
initialization information and one to set information on each new event.
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), from the respective Fortran
commonblocks, or from PYTHIA 8 itself.
You are free to write your own derived classes, using the rules and
methods to be described below. Normally, pointers to objects of such
derived classes should be handed in with the
Pythia::init( LHAup*)
method. However, with the LHEF format a filename can replace the
pointer, see further below.
Let us now describe the methods at your disposal to do the job.
setStrategy
,
see below. It also reserves some space for processes and particles.
Pythia::init(...)
.
LHAup
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.
setInit()
, such information can be set by the following
methods:
IDBMUP(1), EBMUP(i), PDFGUP(i), PDFSUP(i)
,
with i
1 or 2). The parton distribution information
defaults to zero. These numbers can be used to tell which PDF sets were
used when the hard process was generated, while the normal
IDWTUP
; see Sjo06
section 9.9.1 for extensive comments).
xMax
.
Accepted events therefore have unit weight.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.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
.xSec
.Info::weight()
has been converted to mb, however.
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.
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 xSec
value of the i
'th process
added with addProcess
method (i.e. i
runs
from 0 through sizeProc() - 1
, see below).
xErr
value of the i
'th process
added with addProcess
method.
xMax
value of the i
'th process
added with addProcess
method.
key
to have value val
.
This is a wrapper function to the
i
in the range 0 <= i <
sizeProc()
.
Pythia::init(...)
,
so would normally not need to be called directly by the user.
LHAup
class also 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 sizePart()
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
).
idProcess
value specifies which process
that should be generated, while idProcess
is irrelevant
for strategies +-3 and +-4. The method 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
Info::atEndOfFile()
to confirm that indeed the failure is caused in this method, and decide
to break out of the event generation loop.
Inside a normal setEvent(...)
call, information can be set
by the following methods:
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 addParticle
method below.
IDUP, ISTUP,
MOTHUP(1,..), MOTHUP(2,..), ICOLUP(1,..), ICOLUP(2,..), PUP(J,..),
VTIMUP, SPINUP
) .
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 +-3 and +-4 would the value in info
be the same as
here, except for a conversion from pb to mb for +-4.
i
in the range
0 <= i < sizePart()
. (But again note that
i = 0
is an empty line, so the true range begins at 1.)
true
.
setPdf(...)
must be called after the
setProcess(...)
call of the event for this to work.)
Note that the flavour and pdf
in their names, see explanation in the
LHAup
object is not available to the user, the
Pythia::LHAeventList(ostream& os = cout)
method can
be used, which is a wrapper for the above.
nSkip
events in the Les Houches generation
sequence, without doing anything further with them. Mainly
intended for debug purposes, e.g. when an event at a known
location in a Les Houches Event File is causing problems.
Will return false if operation fails, specifically if the
end of an LHEF has been reached. The implementation in the base class
simply executes setEvent()
the requested number of times.
The derived LHAupLHEF
class (see below) only uses the
setNewEventLHEF(...)
part of its setEvent()
method, and other derived classes could choose other shortcuts.
Pythia::init(fileName)
initialization option exists, where the LHEF name is provided as input.
Internally this name is then used to create an instance of the derived
class LHAupLHEF
, which can do the job of reading an LHEF.
The LHEF reader can also read in and store header blocks. By default
this option is switched on, but may be controlled through the
<header> BaseA <hblock1> 1A <hblock11> 11A <hblock111> </hblock111> 11B </hblock11> 1B </hblock1> <hblock2> 2A <!-- 2B --> </hblock2> BaseB </header>which would lead to the following information being stored in the
Key | Value |
---|---|
base | BaseA BaseB |
hblock1 | 1A 1B |
hblock1.hblock11 | 11A <hblock111> </hblock111> 11B |
hblock2 | 2A <!-- 2B --> |
README
file in the main directory for details
on how to do this.
An example how to generate events from an LHEF is found in
main11.cc
. Note the use of
Info::atEndOfFile()
to find out when the whole
LHEF has been processed.
To allow the sequential use of several event files the
Pythia::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 LHAupLHEF
class
instance 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
main12.cc
. A variant, based on input in a command file,
is given in main13.cc
.
In C++, real numbers are printed with an 'E' to denote the exponent part,
e.g. 1.23E+04, and are read in accordingly. Other languges may use other
letters, e.g. Fortran allows either 'E' or 'D'. A file using
the latter convention would not be readable by the standard routines.
In case you have such an "incorrectly formatted" file, a conversion to
a new corrected file could be done e.g. using sed
, as a
one-line command
sed -e 's/\([0-9]\.\{0,1\}\)[dD]\([+-]\{0,1\}[0-9]\)/\1E\2/g' old.lhe > new.lheThis replaces a 'd' or 'D' with an 'E' only when it occurs in the combination
<header>...</header>
block. For conversion only
inside the <init>...</init>
and
<event>...</event>
blocks, create a file
convert.sed
containing
/<init>/,/<\/init>/bconv /<event>/,/<\/event>/bconv b :conv s/\([0-9]\.\{0,1\}\)[dD]\([+-]\{0,1\}[0-9]\)/\1E\2/gand run it with
sed -f convert.sed old.lhe > new.lheThe workhorses of the
LHAupLHEF
class are three methods
found in the base class, so as to allow them to be reused in other
contexts. Specifically, it allows derived classes where one parton-level
configuration can be reused several times, e.g. in the context of
matrix-element-to-parton-shower matching (example in preparation).
Also two small utility routines.
setOldEventLHEF
.
setNewEventLHEF
call can be
followed by several setOldEventLHEF
ones, so as to
process the same configuration several times. This method currently
only returns true, i.e. any errors should be caught by the preceding
setNewEventLHEF
call.
LHAupLHEF
it returns false if the LHEF provided in the constructor is not
found and opened correctly.
Info
class.
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 LHAupFortran
class derives from LHAup
.
It reads initialization and event information from the LHA standard
Fortran commonblocks, assuming these commonblocks behave like two
extern "C" struct
named heprup_
and
hepeup_
. (Note the final underscore, to match how the
gcc compiler internally names Fortran files.)
The instantiation does not require any arguments.
The user has to supply implementations of the fillHepRup()
and fillHepEup()
methods, that is to do the actual calling
of the external Fortran routines that fill the HEPRUP
and
HEPEUP
commonblocks. The translation of this information to
the C++ structure is provided by the existing setInit()
and
setEvent()
code.
Up to and including version 8.125 the LHAupFortran
class
was used to construct a runtime interface to PYTHIA 6.4. This was
convenient in the early days of PYTHIA 8 evolution, when this program
did not yet contain hard-process generation, and the LHEF standard
did not yet exist. Nowadays it is more of a bother, since a full
cross-platform support leads to many possible combinations. Therefore
the support has been reduced in the current version. Only the
main91.cc
example remains as an illustration, where the
previously separate interface code
(include/Pythia6Interface.h
) has been inserted in the
beginning. You also need to modify the examples/Makefile
to link main91.cc
properly also to a PYTHIA 6.4 library
version, see commented-out section for ideas how to to this.
LHAup
class is to feed information
from an external program into PYTHIA. It can be used to export information
as well, however. Specifically, there are four routines in the base class
that can be called to write a Les Houches Event File. These should be
called in sequence in order to build up the proper file structure.
verbose = false
only
leaves a single blank between the information fields.
updateInit = true
, this routine will reopen the file from
the beginning, rewrite the same header as openLHEF()
did,
and then call initLHEF()
again to overwrite the old
information. This is especially geared towards programs, such as PYTHIA
itself, where the cross section information is not available at the
beginning of the run, but only is obtained by Monte Carlo integration
in parallel with the event generation itself. Then the
setXSec( i, xSec)
, setXErr( i, xSec)
and
setXMax( i, xSec)
can be used to update the relevant
information before closeLHEF
is called.
LHAupFromPYTHIA8
. In order for it to do its job,
it must gain access to the information produced by PYTHIA,
specifically the process
event record and the
generic information stored in info
. Therefore, if you
are working with an instance pythia
of the
Pythia
class, you have to instantiate
LHAupFromPYTHIA8
with pointers to the
process
and info
objects of
pythia
:
LHAupFromPYTHIA8 myLHA(&pythia.process, &pythia.info);
The method setInit()
should be called to store the
pythia
initialization information in the LHA object,
and setEvent()
to store event information.
Furthermore, updateSigma()
can be used at the end
of the run to update cross-section information, cf.
closeLHEF(true)
above. An example how the
generation, translation and writing methods should be ordered is
found in main20.cc
.
Currently there are some limitations, that could be overcome if
necessary. Firstly, you may mix many processes in the same run,
but the cross-section information stored in info
only
refers to the sum of them all, and therefore they are all classified
as a common process 9999. Secondly, you should generate your events
in the CM frame of the collision, since this is the assumed frame of
stored Les Houches events, and no boosts have been implemented
for the case that Pythia::process
is not in this frame.
The LHEF standard is the agreed format to store the particles of a
hard process, as input to generators, whereas output of final states
is normally handled using the LHAupFromPYTHIA8 myLHA(&pythia.event, &pythia.info);
process
is replaced by event
.
In addition, the PartonLevel:all = off
command found in
main20.cc
obviously must be removed if one wants to
obtain complete events.