Pythiaclass 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 webpage is a complete survey of all public
Pythiamethods and data members, in a more formal style than the task-oriented descriptions found in the preceding sections. This offers complementary information.
#include "Pythia8/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
Pythiaobject. (But you can use several
Pythiaobjects, which then will be independent of each other.)
Pythiawill be on the
coutstream, but the
listmethods below do allow output to alternative streams or files.
Pythiaconstructor. The default values can then be changed, primarily by one of the two ways below, or by a combination of them. a) You can use the
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.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
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. Changes are made sequentially in the order the commands are encountered during execution, meaning that if a parameter is changed several times it is the last one that counts. The two special
Tune:ppmodes are expanded to change several settings in one go, but these obey the same ordering rules.
ParticleDatadatabases. Specifically the setup of incoming beams and energies is governed by the the beam parameters from the
Beamsgroup of variables. If you don't change any of those you will default to proton-proton collisions at 14 TeV, i.e. the nominal LHC values. A few alternative forms are available, where the arguments of the
init(...)call can be used to set the beam parameters. These alternatives are now deprecated, and will be removed for PYTHIA 8.2. a)
pythia.init( idA, idB, eCM);
pythia.init( idA, idB, eA, eB);
pythia.init( idA, idB, pxA, pyA, pzA, pxB, pyB, pzB);
LHAupclass object, and that a pointer to this object is handed in.
pythia.settings.listChanged(); pythia.settings.listAll(); pythia.particleData.listChanged(); pythia.particleData.listAll();
pythia.next();This method takes no arguments; everything has already been specified. It does return a bool value, however,
falsewhen 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
Pythiato generate an event, or unphysical features in the event record at the end of the generation step. It makes sense to allow a few
falsevalues before a run is aborted, so long as the related faulty events are skipped.
eventobject, 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
info, which offers a set of one-of-a kind pieces of information about the most recent event.
pythia.stat();to get some run statistics, on cross sections and the number of errors and warnings encountered. The alternative
pythia.statistics(...);is equivalent but deprecated.
examplessubdirectory. However, in the general case, you must provide the path of the
xmldocdirectory, where default settings and particle data are found. This can be done in two ways.
PYTHIA8DATAto contain the location of the
xmldocdirectory. In the
tcshshells 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.
.bashrcfiles, respectively, if you want a more permanent assignment.
PYTHIA8DATAis set it takes precedence, else the path in the constructor is used, else one defaults to the
../xmldocdirectory. 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.setPDFptr( pdfAPtr, pdfBPtr);where
pdfBPtrare pointers to two
PythiaPDF objects. Note that
pdfBPtrcannot 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 multiparton interactions.
pythia.setLHAupPtr( lhaUpPtr);where the
lhaUpPtrderives from the LHAup base class.
pythia.setDecayPtr( decayHandlePtr, particles);where the
decayHandlePtrderives from the
DecayHandlerbase class and
particlesis a vector of particle codes to be handled.
rndmEnginePtrderives from the
RndmEnginebase class. The
Pythiadefault random number generator is perfectly good, so this is only intended for consistency in bigger frameworks.
userHooksPtrderives from the
mergingHooksPtrderives from the
beamShapePtrderives from the
SigmaProcess*is an instance of a class derived from one of the
Sigma3Processbase classes in their turn derived from
SigmaProcess. This call can be used repeatedly to hand in several different processes.
ResonanceWidths*is an instance of a class derived from the
ResonanceWidthsbase 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
timesPtrderive from the
TimeShowerbase class, and
Pythiaobject. 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.
pythiaobject for each subrun, in which case they are completely separate. You can also use the same
pythiaobject, 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
istreaminstead 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
subrunnumber 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
Beams:LHEF. However, in that case you will do a complete re-initialization each time around. If you want to avoid this, note that the flag
Beams:newLHEFsameInit = truecan be set for the second and subsequent subruns. 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. Also note that cross sections for processes will be based on the information in the first-read file, when the full initialization is performed.
Pythiamethods and data members.
Pythiaevent generators, and sets initial default values, notably for all settings and particle data. You may use several
Pythiainstances 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.)
default = ../xmldoc) : allows you to choose from which directory the default settings and particle data values are read in. If the
PYTHIA8DATAenvironment 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
xmldocdirectory in the standard distribution.
default = true) : can be set
falseto stop the program from printing a banner. The banner contains useful information, so this option is only intended for runs with multiple
Pythiainstances, where output needs to be restricted. Pythia::~Pythia
argumentline : the string to be interpreted as an instruction.
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.
readStringmethod. All four forms of the
readFilecommand share code for actually reading a file.
argumentfileName : the file from which instructions are read.
argumentinStream : an istream from which instructions are read.
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
warnis omitted it is true.
argumentsubrun : 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
SUBRUNDEFAULTcorresponds to no specific subrun.
argumentpdfAPtr, pdfBPtr : pointers to two
argumentpdfHardAPtr, pdfHardBPtr (
default = 0) : pointers to two further
setPDFPtrwith new arguments before each
Pythia::init(...)call. To revert from external PDF's to the normal internal PDF selection you must call
Pythia::init(...). bool Pythia::setLHAupPtr( LHAup* lhaUpPtrIn)
Beams:frameType = 5has been set.
argumentlhaUpPtrIn : pointer to a
DecayHandlerbase 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.
argumentdecayHandlePtr : pointer to a
DecayHandler-derived object. This object must be instantiated by you in your program.
argumenthandledParticles : 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.
RndmEnginebase class are described here.
argumentrndmEnginePtr : pointer to a
RndmEngine-derived object. This object must be instantiated by you in your program.
UserHooksbase 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.
argumentuserHooksPtr : pointer to a
userHooks-derived object. This object must be instantiated by you in your program.
BeamShapebase class are described here.
argumentBeamShapePtr : pointer to a
BeamShape-derived object. This object must be instantiated by you in your program.
Pythialibrary itself. The rules for constructing your own class from the
SigmaProcessbase class are described here. You may call this routine repeatedly, to add as many new processes as you wish.
argumentsigmaPtr : pointer to a
SigmaProcess-derived object. This object must be instantiated by you in your program.
Pythialibrary 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 modeled here; this is for New Physics resonances. The rules for constructing your own class from the
ResonanceWidthsbase class are described here. You may call this routine repeatedly, to add as many new resonances as you wish.
argumentresonancePtr : pointer to a
ResonanceWidths-derived object. This object must be instantiated by you in your program.
SpaceShowerbase classes are described here. These objects must be instantiated by you in your program.
argumenttimesDecPtr : 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.
default = 0) : pointer to a
TimeShower-derived object for doing all other timelike shower evolution, which is normally interleaved with multiparton 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
timesDecPtrif the same shower can fulfill both tasks.
default = 0) : pointer to a
SpaceShower-derived object for doing all spacelike shower evolution, which is normally interleaved with multiparton interactions and timelike showers. If you retain the default value 0 then the internal shower routine will be used.
initmethod are available for this stage, but only the first one is recommended. bool Pythia::init()
argumentidA, idB : particle identity code for the two incoming beams.
argumenteCM : the CM energy of the collisions.
argumentidA, idB : particle identity code for the two incoming beams.
argumenteA, 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.
argumentidA, idB : particle identity code for the two incoming beams.
argumentpxA, pyA, pzA : the three-momentum vector (p_x, p_y, p_z) of the first incoming beam.
argumentpxB, pyB, pzB : the three-momentum vector (p_x, p_y, p_z) of the second incoming beam.
argumentLesHouchesEventFile : the file name (including path, where required) where the events are stored, including relevant information on beam identities and energies.
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.
LHAupbase class are described here. This class is also required to provide the beam parameters.
argumentlhaUpPtr : 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. int Pythia::forceTimeShower( int iBeg, int iEnd, double pTmax, int nBranchMax = 0)
eventevent record. This could be used for externally provided simple events, or even parts of events, for which a complete generation is not foreseen. Since the mother source of the parton system is not known, one cannot expect as good accuracy as in a normal generation. When two different timelike shower instances are set up, it is the one used for showering in resonance decays that is used here. The
forceTimeShowermethod can be used in conjunction with the
forceHadronLevelone below. Further comments are found here.
argumentiBeg, iEnd : the first and last entry of the event record to be affected by the call.
argumentpTmax : the maximum pT scale of emissions. Additionally, as always, the
scalevariable of each parton sets the maximum pT scale of branchings of this parton. Recall that this scale defaults to 0 if not set, so that no radiation can occur.
default = 0) : when positive, it sets the maximum number of branchings that are allowed to occur in the shower, i.e. the shower may stop evolving before reaching the lower cutoff. The argument has no effect when zero or negative, i.e. then the shower will continue to the lower cutoff.
default = true) : normally this routine will search through the event record and try to figure out if any colour junctions are present. If so, the colour topology of such junctions must be sorted out. In tricky cases this might fail, and then hadronization will not work. A user who is aware of this and knows the intended colour flow can set up the junction information (if any) in the event record, and then call
forceHadronLevel(false)so as not to have this information overwritten. (If the event record contains no unhadronized partons then no junction search will be performed in any case.)
LHAup::listEvent(...). (Other listings are available via the class members below, so this listing is a special case that would not fit elsewhere.)
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.
argumentnSkip : number of events to skip.
default = false) : if true also statistics on multiparton interactions is shown, by default not.
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
resetoption 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
Settingsdatabase 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
Settingsmethods may be convenient. bool Pythia::flag(string key)
argumentkey : the name of the variable to be read. int Pythia::mode(string key)
argumentkey : the name of the variable to be read. double Pythia::parm(string key)
argumentkey : the name of the variable to be read. string Pythia::word(string key)
argumentkey : the name of the variable to be read.
Pythiacontains an number of parton density sets internally, plus an interface to LHAPDF. With the method below, this machinery is also made available for external usage. PDF* getPDFPtr(int id, int sequence = 1)
argumentid : the identity code of the incoming particle.
argumentsequence : should normally be 1, but 2 can be used for protons to let the PDF selection be determined by the special settings for hard processes (
Pythiaclass 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