Pythia
class should
be used in the user-supplied main program, further outlined in the
following. Since the nature of the run is defined at the initialization
stage, this is where most of the PYTHIA user code has to be written.
So as not to confuse the reader unduly, the description of initialization
options has been subdivided into what would normally be used and what is
intended for more special applications.
At the bottom of this webpge is a complete survey of all public
Pythia
methods and data members, in a more formal style
than the task-oriented descriptions found in the preceding sections.
This offers complementary information.
#include "Pythia.h"To simplify typing, it also makes sense to declare
using namespace Pythia8;
Pythia pythia;It is this object that we will use from now on. Normally a run will only contain one
Pythia
object. (But you can
use several Pythia
objects, which then will be
independent of each other.)Pythia
will be on the
cout
stream, but the list
methods below do
allow output to alternative streams or files.
Pythia
constructor. The default values can then be
changed, primarily by one of the two ways below, or by a combination
of them.pythia.readString(string);method repeatedly to do a change of a property at a time. The information in the string is case-insensitive, but upper- and lowercase can be combined for clarity. The rules are that
pythia.settings.readString(string)
;pythia.particleData.readString(string)
;pythia.readString("TimeShower:pTmin = 1.0"); pythia.readString("111:mayDecay = false");The
readString(string)
method is intended primarily for
a few changes. It can also be useful if you want to construct a
parser for input files that contain commands both to PYTHIA and to
other libraries.pythia.readFile(fileName);Each line in this file with be processes by the
readString(string)
method introduced above. You can thus
freely mix comment lines and lines handed on to Settings
or to ParticleData
.readString(string)
, and can also avoid having to
recompile and relink your main program between runs.istream
, by
default cin
, rather than from a file. This may be convenient
if information is generated on-the-fly, within the same run.
init(...)
method allows a few different input formats,
so you can pick the one convenient for you:
a) pythia.init( idA, idB, eCM);
pythia.init( idA, idB, eA, eB);
pythia.init( idA, idB, pxA, pyA, pzA, pxB, pyB, pzB);
pythia.init(fileName);
pythia.init();
Main
group of variables, which provides you with the same possibilities as
the above options a, b, c and d. If you don't change any of those you will
default to proton-proton collisions at 14 TeV, i.e. the nominal LHC
values.
f) pythia.init( LHAup*);
LHAup
class object, and that a pointer to this object is handed in.
pythia.settings.listChanged(); pythia.settings.listAll(); pythia.particleData.listChanged(); pythia.particleData.listAll();
next()
method,
pythia.next();This method takes no arguments; everything has already been specified. It does return a bool value, however,
false
when the
generation failed. This can be a "programmed death" when the
supply of input parton-level configurations on file is exhausted.
It can alternatively signal a failure of Pythia
to
generate an event, or unphysical features in the event record at the
end of the generation step. It makes sense to allow a few false
values before a run is aborted, so long as the related faulty
events are skipped.
event
object, of type Event
,
which is a public member of pythia
. You therefore have
access to all the tools described on the pages under the "Study Output"
header in the index. For instance, an event can be listed with
pythia.event.list()
, the identity of the i'th
particle is given by
pythia.event[i].id()
, and so on.process
, also of type Event
.info
, which offers
a set of one-of-a kind pieces of information about the most recent
event.
pythia.statistics();to get some run statistics, on cross sections and the number of errors and warnings encountered.
examples
subdirectory. However, in the
general case, you must provide the path of the xmldoc
directory, where default settings and particle data are found.
This can be done in two ways.
PYTHIA8DATA
to
contain the location of the xmldoc
directory. In the
csh
and tcsh
shells this could e.g. be
setenv PYTHIA8DATA /home/myname/pythia81xx/xmldocwhile in other shells it could be
export PYTHIA8DATA=/home/myname/pythia81xx/xmldocwhere xx is the subversion number.
.cshrc
and .bashrc
files, respectively,
if you want a more permanant assignment.
Pythia
constructor, e.g.
Pythia pythia("/home/myname/pythia81xx/xmldoc");
PYTHIA8DATA
is set it takes precedence, else
the path in the constructor is used, else one defaults to the
../xmldoc
directory.
B) You can override the default behaviour of PYTHIA not only by the
settings and particle data, but also by replacing some of the
PYTHIA standard routines by ones of your own. Of course, this is only
possible if your routines fit into the general PYTHIA framework.
Therefore they must be coded according to the the rules relevant
in each case, as a derived class of a PYTHIA base class, and a pointer
to such an object must be handed in by one of the methods below.
These calls must be made before the pythia.init(...)
call.
setPDFPtr(...)
method
pythia.setPDFptr( pdfAPtr, pdfBPtr);where
pdfAPtr
and pdfBPtr
are pointers to
two Pythia
PDF
objects. Note that pdfAPtr
and pdfBPtr
cannot point to the same object; even if the PDF set is the same,
two copies are needed to keep track of two separate sets of x
and density values.pythia.setPDFptr( pdfAPtr, pdfBPtr, pdfHardAPtr, pdfHardBPtr);allows you to specify those separately, and then the first two sets would only be used for the showers and for multiple interactions.
setDecayPtr(...)
method
pythia.setDecayPtr( decayHandlePtr, particles);where the
decayHandlePtr
derives from the
DecayHandler
base
class and particles
is a vector of particle codes to be
handled.
setRndmEnginePtr(...)
method
pythia.setRndmEnginePtr( rndmEnginePtr);where
rndmEnginePtr
derives from the
RndmEngine
base class.
The Pythia
default random number generator is perfectly
good, so this is only intended for consistency in bigger frameworks.
pythia.setUserHooksPtr( userHooksPtr);where
userHooksPtr
derives from the
UserHooks
base class.
pythia.setBeamShapePtr( beamShapePtr);where
beamShapePtr
derives from the
BeamShape
base class.
pythia.setSigmaPtr( sigmaPtr);where
sigmaPtr
of type SigmaProcess*
is an
instance of a class derived from one of the Sigma1Process
,
Sigma2Process
and Sigma3Process
base classes
in their turn derived from
SigmaProcess
.
This call can be used repeatedly to hand in several different processes.
pythia.setResonancePtr( resonancePtr);where
resonancePtr
of type ResonanceWidths*
is an instance of a class derived from the
ResonanceWidths
base class. In addition you need to add the particle to the normal
particle and decay database.
This procedure can be used repeatedly to hand in several different
resonances.
pythia.setShowerPtr( timesDecPtr, timesPtr, spacePtr);where
timesDecPtr
and timesPtr
derive from the TimeShower
base class, and
spacePtr
from SpaceShower
.
initTunes(...)
method allows you to initialize the settings
of a specific tune at an early stage, so that you can change some of the
tune values between the initTunes(...)
and the
init(...)
calls. This method should not be used if you want
to use an existing tune as is, or make your own changes altogether.
See the initTunes(...)
description below for more details.
Pythia
object. The key example would be the simultaneous generation of signal
and pileup events, see main19.cc
. The two objects are then
set up and initialized separately, and generate events completely
independently of each other. It is only afterwards that the event records
are combined into one single super-event per beam crossing.
pythia
object for each subrun, in which case they are
completely separate. You can also use the same pythia
object,
only doing a new init(...)
call for each subrun. In that
case, the settings and particle databases remain as they were in the
previous subrun, only affected by the specific changes you introduced in
the meantime. You can put those changes in the main program, with
pythia.readString(string)
, using your own logic to decide
which ones to execute in which subrun. A corresponding possibility
exists with pythia.readFile(fileName, subrun)
(or an
istream
instead of a fileName
), which as second
argument can take a non-negative subrun number. Then only those
sections of the file before any Main:subrun = ...
line
or with matching subrun
number will be read. That is, the
file could have a structure like
( lines always read, i.e. "default values" always (re)set ) Main:subrun = 1 ( lines only read with readFile(fileName, 1) ) Main:subrun = 2 ( lines only read with readFile(fileName, 2) )Both of these possibilities are illustrated in
main08.cc
.
pythia.init(fileName, skipInit)
.
Alternatively, the tag Main:LHEFskipInit
can be put
in a file of commands to obtain the same effect.
Here skipInit
defaults to false
,
but if set true
then the new file will be simulated
with the same initialization data as already set in a previous
pythia.init(...)
call. The burden rests on you to ensure
that this is indeed correct, e.g. that the two event samples have not
been generated for different beam energies.
Pythia
methods and data members.
Pythia
event generators,
and sets initial default values, notably for all settings and
particle data. You may use several Pythia
instances
in the same run; only when you want to access external static
libraries could this cause problems. (This includes in particular
Fortran libraries such as LHAPDF.)
argument
xmlDir (default = ../xmldoc
) : allows you to choose
from which directory the default settings and particle data values
are read in. If the PYTHIA8DATA
environment variable
has been set it takes precedence. Else this optional argument allows
you to choose another directory location than the default one. Note
that it is only the directory location you can change, its contents
must be the ones of the xmldoc
directory in the
standard distribution.
Pythia::~Pythia argument
line :
the string to be interpreted as an instruction.
argument
warn (default = true
) :
write a warning message or not whenever the instruction does not make
sense, e.g. if the variable does not exist in the databases.
readString
method. All four forms of the
readFile
command share code for actually reading a file.
argument
fileName :
the file from which instructions are read.
argument
inStream :
an istream from which instructions are read.
argument
warn (default = true
) :
write a warning message or not whenever the instruction does not make
sense, e.g. if the variable does not exist in the databases. In the
command forms where warn
is omitted it is true.
argument
subrun :
allows you have several optional sets of commands within the same file.
Only those sections of the file before any Main:subrun = ...
line or following such a line with matching subrun number will be read.
The subrun number should not be negative; negative codes like
SUBRUNDEFAULT
corresponds to no specific subrun.
PDF
base class are described
here.
argument
pdfAPtr, pdfBPtr :
pointers to two PDF
-derived objects, one for each of
the incoming beams. The two objects have to be instantiated by you
in your program. Even if the two beam particles are the same
(protons, say) two separate instances are required, since current
information is cached in the objects. If both arguments are zero
then any previous linkage to external PDF's is disconnected,
see further Note 2 below.
argument
pdfHardAPtr, pdfHardBPtr (default = 0
) :
pointers to two further PDF
-derived objects, one for each
of the incoming beams. Normally only the first two arguments above would
be used, and then the same PDF sets would be invoked everywhere. If you
provide these two further pointers then two different sets of PDF's are
used. This second set is then exclusively for the generation of the hard
process from the process matrix elements library. The first set above
is for everything else, notably parton showers and multiple interactions.
setPDFPtr
with new arguments before each
Pythia::init(...)
call. To revert from external PDF's
to the normal internal PDF selection you must call
setPDFPtr(0, 0)
before Pythia::init(...)
.
bool Pythia::setDecayPtr( DecayHandler* decayHandlePtr, vector<int> handledParticles) DecayHandler
base class are described
here. Note that you can only
provide one external object, but this object in its turn could
very well hand on different particles to separate decay libraries.
argument
decayHandlePtr :
pointer to a DecayHandler
-derived object. This object
must be instantiated by you in your program.
argument
handledParticles : vector with the PDG identity codes
of the particles that should be handled by the external decay package.
You should only give the particle (positive) codes; the respective
antiparticle is always included as well.
RndmEngine
base class are described
here.
argument
rndmEnginePtr :
pointer to a RndmEngine
-derived object. This object
must be instantiated by you in your program.
UserHooks
base class are described
here. You can only hand in one such
pointer, but this may be to a class that implements several of the
different allowed possibilities.
argument
userHooksPtr :
pointer to a userHooks
-derived object. This object
must be instantiated by you in your program.
BeamShape
base class are described
here.
argument
BeamShapePtr :
pointer to a BeamShape
-derived object. This object
must be instantiated by you in your program.
Pythia
library itself. The rules for constructing your
own class from the SigmaProcess
base class are described
here. You may call this
routine repeatedly, to add as many new processes as you wish.
argument
sigmaPtr :
pointer to a SigmaProcess
-derived object. This object
must be instantiated by you in your program.
Pythia
library itself. This allows the decay of new
resonances to be handled internally, when combined with new particle
data. Note that the decay of normal hadrons cannot be modelled here;
this is for New Physics resonances. The rules for constructing your
own class from the ResonanceWidths
base class are described
here. You may call this
routine repeatedly, to add as many new resonances as you wish.
argument
resonancePtr :
pointer to a ResonanceWidths
-derived object. This object
must be instantiated by you in your program.
TimeShower
and SpaceShower
base classes
are described here. These
objects must be instantiated by you in your program.
argument
timesDecPtr :
pointer to a TimeShower
-derived object for doing
timelike shower evolution in resonance decays, e.g. of a
Z^0. This is decoupled from beam remnants and parton
distributions, and is therefore the simplest kind of shower
to write. If you provide a value 0 then the internal shower
routine will be used.
argument
timesPtr (default = 0
) :
pointer to a TimeShower
-derived object for doing
all other timelike shower evolution, which is normally interleaved
with multiple interactions and spacelike showers, introducing
both further physics and further technical issues. If you retain
the default value 0 then the internal shower routine will be used.
You are allowed to use the same pointer as above for the
timesDecPtr
if the same shower can fulfill both tasks.
argument
spacePtr (default = 0
) :
pointer to a SpaceShower
-derived object for doing
all spacelike shower evolution, which is normally interleaved
with multiple interactions and timelike showers. If you retain
the default value 0 then the internal shower routine will be used.
readString(...)
and readFile(...)
methods can be used to set the parameters of some already
existing tune, one by one, this is time-consuming and error-prone.
Therefore the initTunes(...)
method provides a set of
tunes, hopefully growing with time, that can be selected by the
two switches Tune:ee
and
Tune:pp
. Default is 0,
meaning no changes. Nornally initTunes(...)
is
automatically called from inside the init(...)
method,
so you would not call it yourself. This can be constraining if you
want to use almost, but not quite, an existing tune. Specifically,
any attempts to set one or a few of the parameters differently by
readString(...)
or readFile(...)
calls
before initialization would not work, since they would be overwritten
during init(...)
. This is where the possibility to call
initTunes(...)
directly comes to the rescue. You could
then by hand pick the desired tune, afterwards change whatever settings
you wish, and retain these changes during initialization by having
Tune:ee = Tune:pp = 0
.
argument
eeTune (default = 0
) : the settings obtained from
e^+e^- data, see Tune:ee
for a list of valid values. If you call initTunes(...)
with this option nonzero you would want to keep Tune:ee
equal to zero, or else the whole point is lost.
argument
eeTune (default = 0
) : the additional settings that
can only be extracted from pp/ppbar data see
Tune:pp
for a list of valid
values. Comment as above.
init
method
are available for this stage; pick the one most convenient.
bool Pythia::init( int idA, int idB, double eCM) argument
idA, idB :
particle identity code for the two incoming beams.
argument
eCM :
the CM energy of the collisions.
argument
idA, idB :
particle identity code for the two incoming beams.
argument
eA, eB :
the energies of the two beams. If an energy is set to be below
the mass of the respective beam particle that particle is taken to
be at rest. This offers a simple possibility to simulate
fixed-target collisions.
argument
idA, idB :
particle identity code for the two incoming beams.
argument
pxA, pyA, pzA :
the three-momntum vector (p_x, p_y, p_z) of the first
incoming beam.
argument
pxB, pyB, pzB :
the three-momntum vector (p_x, p_y, p_z) of the second
incoming beam.
argument
LesHouchesEventFile :
the file name (including path, where required) where the
events are stored, including relevant information on beam
identities and energies.
argument
skipInit (default = false
) :
By default this method does a complete reinitialization of the
generation process. If you set this argument to true then
no reinitialization will occur, only the pointer to the event
file is updated. This may come in handy if the full event sample
is split across several files generated under the same conditions
(except random numbers, of course). You then do the first
initialization with the default, and all subsequent ones with
true. Note that things may go wrong if the files are not created
under the same conditions.
LHAup
base class are described here.
This class is also required to provide the beam parameters.
argument
lhaUpPtr :
pointer to a LHAup
-derived object. This object
must be instantiated by you in your program.
next()
method is the main one to generate events.
In this section we also put a few other specialized methods that
may be useful in some circumstances.
bool Pythia::next() Info::atEndOfFile()
method.
bool Pythia::forceHadronLevel() LHAup::listEvent(...)
.
(Other listings are available via the class members below, so this
listing is a special case that would not fit elsewhere.)
argument
os (default = cout
) :
output stream where the listing occurs.
bool Pythia::LHAeventSkip(int nSkip) LHAup::skipEvent(nSkip)
.
Mainly intended for debug purposes, e.g. when an event at a known
location in a Les Houches Event File is causing problems.
argument
nSkip :
number of events to skip.
next()
above.
argument
all (default = false
) :
if true also statistics on multiple interactions is shown, by default not.
argument
reset (default = false
) : if true then all counters,
e.g on events generated and errors experienced, are reset to zero
whenever the routine is called. The default instead is that
all stored statistics information is unaffected by the call. Counters
are automatically reset in each new Pythia::init(...)
call, however, so the only time the reset
option makes a
difference is if statistics(...)
is called several times
in a (sub)run.
Pythia::readFile(...)
method.
There is no strict need for a user to interact with the
Settings
database in any other way. However, as an option,
some settings variables have been left free for the user to set in
such a file, and then use in the main program to directly affect the
performance of that program, see
here. A typical example would
be the number of events to generate. For such applications the
following shortcuts to some Settings
methods may be
convenient.
bool Pythia::flag(string key) Settings
database.
argument
key :
the name of the variable to be read.
int Pythia::mode(string key) Settings
database.
argument
key :
the name of the variable to be read.
double Pythia::parm(string key) Settings
database.
argument
key :
the name of the variable to be read.
string Pythia::word(string key) Settings
database.
argument
key :
the name of the variable to be read.
Pythia
class contains a few public data members,
several of which play a central role. We list them here, with
links to the places where they are further described.
Event Pythia::process