Program Flow

Normal usage
Advanced usage, mainly for initialization
The Pythia class methods and members

Recall that, to first order, the event generation process can be subdivided into three stages:

Initialization.
The event loop.
Finishing.

This is reflected in how the top-level 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 webpage 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.

Normal usage

Initialization

Already at the top of the main program file, you need to include the proper header file
```
 
    #include "Pythia8/Pythia.h" 
```
To simplify typing, it also makes sense to declare
```
 
    using namespace Pythia8; 
```

The first step is to create a generator object, e.g. with
```
 
     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.)
By default all output from Pythia will be on the cout stream, but a few methods do allow output to alternative streams or files.

You next want to set up the character of the run. The pages under the "Setup Run Tasks" heading in the index describe all the options available (with some very few exceptions, found on the other pages). The default values and your modifications are stored in two databases, one for generic settings and one for particle data. Both of these are initialized with their default values by the Pythia constructor. 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
(i) if the first nonblank character of the string is a letter it is assumed to contain a setting, and is sent on to pythia.settings.readString(string);
(ii) if instead the string begins with a digit it is assumed to contain particle data updates, and so sent on to pythia.particleData.readString(string);
(iii) if none of the above, the string is assumed to be a comment, i.e. nothing will be done.
In the former two cases, a warning is issued whenever a string cannot be recognized (maybe because of a spelling mistake).
Some examples would be
```
 
    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.

b) You can read in a file containing a list of those variables you want to see changed, with a
```
 
    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.
This approach is better suited for more extensive changes than a direct usage of readString(string), and can also avoid having to recompile and relink your main program between runs.
It is also possible to read input from an 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:ee and Tune:pp modes are expanded to change several settings in one go, but these obey the same ordering rules.

Next comes the initialization stage, where all remaining details of the generation are to be specified. There is one standard method to use for this
pythia.init();
with no arguments will read all relevant information from the Settings and ParticleData databases. Specifically the setup of incoming beams and energies is governed by the the beam parameters from the Beams group 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.

If you want to have a list of the generator and particle data used, either only what has been changed or everything, you can use

 
    pythia.settings.listChanged(); 
    pythia.settings.listAll(); 
    pythia.particleData.listChanged(); 
    pythia.particleData.listAll();

The event loop

Inside the event generation loop you generate the next event using the 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.

The generated event is now stored in the 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.
The hard process - roughly the information normally stored in the Les Houches Accord event record - is available as a second object, process, also of type Event.
A third useful public object is info, which offers a set of one-of-a kind pieces of information about the most recent event.

Finishing

At the end of the generation process, you can call
```
 
    pythia.stat(); 
```
to get some run statistics, on cross sections and the number of errors and warnings encountered.

Advanced usage, mainly for initialization

A) Necessary data are automatically loaded when you use the default PYTHIA installation directory structure and run the main programs in the 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 several ways.

You can set the environment variable PYTHIA8DATA to contain the location of the xmldoc directory. In the csh and tcsh shells this could e.g. be
```
 
     setenv PYTHIA8DATA /home/myname/pythia82xx/share/Pythia8/xmldoc 
```
while in other shells it could be
```
 
     export PYTHIA8DATA=/home/myname/pythia82xx/share/Pythia8/xmldoc 
```
where xx is the subversion number.
Recall that environment variables set locally are only defined in the current instance of the shell. The above lines should go into your .cshrc and .bashrc files, respectively, if you want a more permanent assignment.

You can provide the path as argument to the Pythia constructor, e.g.
```
 
     Pythia pythia("/home/myname/pythia82xx/share/Pythia8/xmldoc"); 
```
where again xx is the subversion number.
When PYTHIA8DATA is set it takes precedence, else the path in the constructor is used, else one defaults to the ../share/Pythia8/xmldoc directory.
You can provide references to existing Settings and ParticleData (useful if several identical copies of Pythia8 are constructed):
```
 
     Pythia(Settings& settingsIn, ParticleData& particleDataIn); 
```
You can take input from streams of Settings and ParticleData information (which requires the user to create the streams with the appropriate information):
```
 
     Pythia(istream& settingsStrings, istream& particleDataStrings); 
```

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.

If you are not satisfied with the list of parton density functions that are implemented internally or available via the LHAPDF interface (see the PDF Selection page), you can supply your own by a call to the 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.
If you further wish to use separate PDF's for the hard process of an event than the ones being used for everything else, the extended form
```
 
      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.
There is a further method to set photon fluxes in a similar spirit.

If you want to link to an external generator that feeds in events in the LHA format, you can call the setLHAupPtr(...) method
```
 
      pythia.setLHAupPtr( lhaUpPtr); 
```
where the lhaUpPtr derives from the LHAup base class.

If you want to perform some particle decays with an external generator, you can call the 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.

If you want to use an external random number generator, you can call the 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.

If you want to interrupt the evolution at various stages, to interrogate the event and possibly veto it, or you want to reweight the cross section, you can use
```
 
      pythia.setUserHooksPtr( userHooksPtr); 
```
where userHooksPtr derives from the UserHooks base class.

If you want to use your own merging scale definition for matrix element + parton shower merging, you can call
```
 
      pythia.setMergingHooksPtr( mergingHooksPtr); 
```
where mergingHooksPtr derives from the MergingHooks base class.

If you want to use your own parametrization of beam momentum spread and interaction vertex, rather than the provided simple Gaussian parametrization (off by default), you can call
```
 
      pythia.setBeamShapePtr( beamShapePtr); 
```
where beamShapePtr derives from the BeamShape base class.

If you want to implement a cross section of your own, you can use
```
 
      pythia.addSigmaPtr( sigmaPtr ); 
```
or, optionally,
```
 
      pythia.addSigmaPtr( sigmaPtr, phaseSpacePtr ); 
```
where sigmaPtr is a shared pointer of type SigmaProcess and phaseSpacePtr is a shared pointer of type PhaseSpace. When only the cross-section expression is provided, the built-in phase-space selection machinery will be used. Then sigmaPtr must be an instance of a class derived from one of the Sigma1Process, Sigma2Process and Sigma3Process classes for 1-, 2- and 3- particle production, in their turn derived from SigmaProcess. When you supply your own phase-space generator there is no fundamental limit on the complexity of the process. This call can be used repeatedly to hand in several different processes, mixing ones with and without their own phase-space generators. To reset the user provided cross sections to a single cross section, the setSigmaPtr method can be called, using the same arguments as addSigmaPtr.

If your cross section contains the production of a new resonance with known analytical expression for all the relevant partial widths, you can make this resonance available to the program with
```
 
      pythia.addResonancePtr( resonancePtr); 
```
where resonancePtr is a shared pointer of type ResonanceWidths, and 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. To reset the user provided resonance widths to a single pointer, the method setResonancePtr can be used instead, with the same arguments as addResonancePtr.

If you are a real expert and want to replace the PYTHIA initial- and final-state showers, you can use
```
 
      pythia.setShowerModelPtr( showerModelPtr); 
```
where the showerModelPtr is a shared ShowerModel pointer which stores the following shared pointers: timesPtr and timesDecPtr of the class TimeShower, spacePtr of the class SpaceShower, mergingPtr of the class Merging, and mergingHooksPtr of the class MergingHooks. It is also possible to get back a pointer to the parton shower machinery and perform diagnostics.
```
 
      pythia.getShowerModelPtr(); 
```

With even bigger expertise you can plug in your own Heavy Ions generator, to replace the default Angantyr one, with
```
 
      pythia.setHeavyIonsPtr( heavyIonsPtr); 
```
Maybe more useful is the possibility to get back a pointer to the generator used, e.g. to probe various quantities that are not available with the normal Pythia methods:
```
 
      pythia.getHeavyIonsPtr(); 
```

C) Some comments on collecting several tasks in the same run.

PYTHIA has not been written for threadsafe execution on multicore processors. If you want to use all cores, the most efficient way presumably is to start correspondingly many jobs, with different random number seeds, and add the statistics at the end. However, note that several instances can be set up in the same main program, since instances are completely independent of each other, so each instance could be run inside a separate thread.

In some cases it is convenient to use more than one Pythia object. The key example would be the simultaneous generation of signal and pileup events, see main324.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.

When time is not an issue, it may be that you want to perform several separate subruns sequentially inside a run, e.g. to combine results for several kinematical regions or to compare results for some different tunes of the underlying event. One way to go is to create (and destroy) one 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 main322.cc.

When working with Les Houches Event Files, it may well be that your intended input event sample is spread over several files, that you all want to turn into complete events in one and the same run. There is no problem with looping over several subruns, where each new subrun is initialized with a new file, with name set 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 = true can 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.

The Pythia class methods and members

Here follows the complete survey of all public Pythia methods and data members.

Constructors and destructor

Pythia::Pythia(string xmlDir = "../share/Pythia8/xmldoc", bool printBanner = true)
creates an instance of the 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 LHAPDF5.)
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.
argument printBanner (default = on) : can be set false to stop the program from printing a banner. The banner contains useful information, so this option is only intended for runs with multiple Pythia instances, where output needs to be restricted.

Pythia::Pythia(Settings& settingsIn, ParticleData& particleDataIn, bool printBanner = true)
creates an instance of the Pythia event generators, and sets initial default values, notably for all settings and particle data. This option is intended for runs with multiple Pythia instances, where only the first one needs to read the xmldoc files, while subsequent ones can "inherit" this information.
argument printBanner (default = on) : can be set false to stop the program from printing a banner. The banner contains useful information, so this option is only intended for runs with multiple Pythia instances, where output needs to be restricted.

Pythia::Pythia( istream& settingsStrings, istream& particleDataStrings, bool printBanner = true)
creates an instance of the Pythia event generators, and sets initial default values, notably for all settings and particle data. This option is intended for runs with multiple Pythia instances, where input streams can avoid file read congestion.
argument printBanner (default = on) : can be set false to stop the program from printing a banner. The banner contains useful information, so this option is only intended for runs with multiple Pythia instances, where output needs to be restricted.

Pythia::~Pythia
the destructor deletes the objects created by the constructor.

void Pythia::initPtrs()
bool Pythia::checkVersion()
helper methods, that collects common tasks of the two constructors.

Set up run

bool Pythia::readString(string line, bool warn = true)
reads in a single string, that is interpreted as an instruction to modify the value of a setting or particle data, as already described above.
argument line : the string to be interpreted as an instruction.
argument warn (default = on) : write a warning message or not whenever the instruction does not make sense, e.g. if the variable does not exist in the databases.
Note: the method returns false if it fails to make sense out of the string.

bool Pythia::readFile(string fileName, bool warn = true, int subrun = SUBRUNDEFAULT)
bool Pythia::readFile(string fileName, int subrun = SUBRUNDEFAULT)
bool Pythia::readFile(istream& inStream = cin, bool warn = true, int subrun = SUBRUNDEFAULT)
bool Pythia::readFile(istream& inStream = cin, int subrun = SUBRUNDEFAULT)
reads in a whole file, where each line is interpreted as an instruction to modify the value of a setting or particle data, cf. the above 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 = on) : 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.
Note: the method returns false if it fails to make sense out of any one line.

bool Pythia::setPDFPtr( PDF* pdfAPtr, PDF* pdfBPtr, PDF* pdfHardAPtr = 0, PDF* pdfHardBPtr = 0, PDF* pdfPomAPtr = 0, PDF* pdfPomBPtr = 0, PDF* pdfGamAPtr = 0, PDF* pdfGamBPtr = 0, PDF* pdfHardGamAPtr = 0, PDF* pdfHardGamBPtr = 0, PDF* pdfUnresAPtr = 0, PDF* pdfUnresBPtr = 0, PDF* pdfUnresGamAPtr = 0, PDF* pdfUnresGamBPtrIn = 0)
offers the possibility to link in external PDF sets for usage inside the program. The rules for constructing your own class from the 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 multiparton interactions.
argument pdfPomAPtr, pdfPomBPtr (default = 0) : pointers to two further PDF-derived objects, one for each of the incoming beams. These define the pomeron PDFs used in hard diffraction.
argument pdfGamAPtr, pdfGamBPtr (default = 0) : pointers to two further PDF-derived objects, one for each of the incoming beams. These define the photon PDFs when photons are emitted from lepton beams. With resolved photon beams some additional methods are required for initial state radiation and multiparton interactions and to sample valence content.
argument pdfHardGamAPtr, pdfHardGamBPtr (default = 0) : pointers to two further PDF-derived objects, one for each of the incoming beams. As above, but now these are used for hard-process generation only, the parton showers and multiparton interactions uses the pdfGamAPtr and pdfGamBPtr PDFs. Unlike above, no additional methods are needed for these.
argument pdfUnresAPtr, pdfUnresBPtr (default = 0) : pointers to two further PDF-derived objects, one for each of the incoming beams. Additional PDF pointers when the beam particle has also unresolved PDFs in addition to usual resolved one. Currently used only when mixing direct and resolved photon-initiated processes.
argument pdfUnresGamAPtr, pdfUnresGamBPtr (default = 0) : pointers to two further PDF-derived objects, one for each of the incoming beams. Additional PDF pointers when having resolved and unresolved photons coming from lepton beams. Currently used only when mixing direct and resolved photon-initiated processes in lepton-lepton or lepton-hadron collisions.
Note 1: The method returns false if the input is obviously incorrect, e.g. if two (nonzero) pointers agree.
Note 2: If you want to combine several subruns you can call 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::setPhotonFluxPtr( PDF* photonFluxAIn, PDF* photonFluxBIn)
offers the possibility to link in external photon fluxes for usage inside the program. The rules for constructing your own class from the PDF base class are described here.
argument photonFluxAIn, photonFluxBIn : 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.

bool Pythia::setLHAupPtr( LHAup* lhaUpPtrIn)
offers linkage to an external generator that feeds in events in the LHA format, see Les Houches Accord, assuming that Beams:frameType = 5 has been set.
argument lhaUpPtrIn : pointer to a LHAup-derived object.
Note: The method currently always returns true.

bool Pythia::setDecayPtr( DecayHandler* decayHandlePtr, vector<int> handledParticles)
offers the possibility to link to an external program that can do some of the particle decays, instead of using the internal decay machinery. With particles we here mean the normal hadrons and leptons, not top quarks, electroweak bosons or new particles in BSM scenarios. The rules for constructing your own class from the 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.
Note: The method currently always returns true.

bool Pythia::setRndmEnginePtr( RndmEngine* rndmEnginePtr)
offers the possibility to link to an external random number generator. The rules for constructing your own class from the RndmEngine base class are described here.
argument rndmEnginePtr : pointer to a RndmEngine-derived object. This object must be instantiated by you in your program.
Note: The method returns true if the pointer is different from 0.

bool Pythia::setUserHooksPtr( UserHooks* userHooksPtr)
offers the possibility to interact with the generation process at a few different specified points, e.g. to reject undesirable events at an early stage to save computer time. The rules for constructing your own class from the 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.
Note: The method currently always returns true.

bool Pythia::addUserHooksPtr( UserHooks* userHooksPtr)
offers the possibility to add further user hooks, see setUserHooksPtr above for further information.
Note: The method currently always returns true.
Warning: usually it is meaningful to combine several requirements, but there are examples where not. It is the responsibility of the user to check that a particular combination works as intended. Also see here.

bool Pythia::setBeamShapePtr( BeamShape* beamShapePtr)
offers the possibility to provide your own shape of the momentum and space-time spread of the incoming beams. The rules for constructing your own class from the BeamShape base class are described here.
argument BeamShapePtr : pointer to a BeamShape-derived object. This object must be instantiated by you in your program.
Note: The method currently always returns true.

bool Pythia::setSigmaPtr( SigmaProcessPtr sigmaPtr, PhaseSpacePtr phaseSpacePtrIn = 0)
offers the possibility to link your own implementation of a process and its cross section, to make it a part of the normal process generation machinery, without having to recompile the Pythia library itself. The rules for constructing your own class from the SigmaProcess base class are described here. Calling this method removes any previously user provided processes. To add multiple processes, use addSigmaPtr.
argument sigmaPtr : shared pointer to a SigmaProcess-derived object.
argument phaseSpacePtr : shared pointer to a PhaseSpace-derived object. When not provided the internal phase-space selection machinery will be used. Then sigmaPtr should be an instance of a class derived from one of the Sigma1Process, Sigma2Process and Sigma3Process classes for 1-, 2- and 3- particle production, in their turn derived from SigmaProcess.
Note: The method currently always returns true.

bool Pythia::addSigmaPtr( SigmaProcessPtr sigmaPtr, PhaseSpacePtr phaseSpacePtrIn = 0)
offers the possibility to add further processes, see setSigmaPtr above for further information.
Note: The method currently always returns true.

bool Pythia::setResonancePtr( ResonanceWidthsPtr resonancePtr)
offers the possibility to link your own implementation of the calculation of partial resonance widths, to make it a part of the normal process generation machinery, without having to recompile the 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 modeled here; this is for New Physics resonances. The rules for constructing your own class from the ResonanceWidths base class are described here. Calling this method removes any previously user provided resonances. To add as many new resonances as you wish, instead call addResonancePtr repeatedly.
argument resonancePtr : shared pointer to a ResonanceWidths-derived object.
Note: The method currently always returns true.

bool Pythia::addResonancePtr( ResonanceWidthsPtr resonancePtr)
offers the possibility to add further resonances, see setResonancePtr above for further information.
Note: The method currently always returns true.

bool Pythia::setShowerModelPtr( ShowerModelPtr showerModelPtr)
offers the possibility to link your own parton shower routines as replacements for the default ones. This is much more complicated since the showers are so central and are so interlinked with other parts of the program. Therefore it is also possible to do the replacement in stages, from the more independent to the more intertwined. The rules for constructing your own shower from the ShowerModel class is described here. This model, which includes TimeShower and SpaceShower derived objects, must be instantiated by you in your program.
argument showerModelPtr : shared pointer to a ShowerModel-derived object. This includes a decay time shower, time shower, space shower, merging pointer, and merging user hooks.
Note: The method currently always returns true.

ShowerModelPtr Pythia::getShowerModelPtr()
gives access to the current parton shower model, either one the default internal Pythia models or an external one fed in by the method above this. This way a number of further shower properties can be interrogated.

bool Pythia::setHeavyIonsPtr( HeavyIonsPtr heavyIonsPtr)
offers the possibility to feed in an external Heavy Ion generator that can use the internal Pythia machinery for its tasks, see further here.
argument heavyIonsPtr : pointer to a HeavyIons-derived object for doing Heavy Ions collisions.
Note: The method currently always returns true.

HeavyIons* Pythia::getHeavyIonsPtr()
gives access to the current Heavy Ions generator, either the default internal Angantyr one or an external one fed in by the method above this. This way a number of further event properties can be interrogated.

bool Pythia::setPartonVertexPtr( PartonVertexPtr partonVertexPtrIn)
offers the possibility to set production vertices for the MPI, FSR and ISR parton-level evolution, instead of the default framework, see further here. This part of the program is still in the early stages, and is likely to evolve further. Currently it is only used for the Rope Hadronization framework.
Note: The method currently always returns true.

Initialize

At the initialization stage all the information provided above is processed, and the stage is set up for the subsequent generation of events. Currently only one init method is available for this stage.

bool Pythia::init()
initialize for collisions. The beams are not specified by input arguments, but instead by the settings in the Beam Parameters section. This allows the beams to be specified in the same file as other run instructions. The default settings give pp collisions at 14 TeV.
Note: The method returns false if the initialization fails. It is then not possible to generate any events.

Generate events

The 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()
generate the next event. No input parameters are required; all instructions have already been set up in the initialization stage.
Note: The method returns false if the event generation fails. The event record is then not consistent and should not be studied. When reading in hard collisions from a Les Houches Event File the problem may be that the end of the file has been reached. This can be checked with the Info::atEndOfFile() method.

bool Pythia::next(int procType)
By default all initialized processes are generated, properly mixed. By specifying a procType, it possible to force a specific process type, assuming that you start out e.g. from SoftQCD:all = on. The possible interaction procTypes are (1) inelastic nondiffractive, (2) elastic, (3, 4) single diffractive where either the first or second hadron is broken up, (5) double diffractive, and (6) central diffraction. This matches the order of the SoftQCD process codes 101 - 106.
If the collision energy can be so low that the LowEnergyQCD processes are used, then also the options (7) excitation, (8) annihilation and (9) resonant can be used. Then all the input numbers match the order of the LowEnergQCD codes 151 - 159. In the higher-energy description process types 7 - 9 default back to the 0 mixed option.

bool Pythia::setKinematics(double eCM)
bool Pythia::setKinematics(double eA, double eB)
bool Pythia::setKinematics(double pxA, double pyA, double pzA, double pxB, double pyB, double pzB)
bool Pythia::setKinematics(Vec4 pA, Vec4 pB)
When variable energy is set with Beams:allowVariableEnergy change the beam energy.

bool Pythia::setBeamIDs( int idAin, int idBin)
Provides limited support for changing beam particles. Using this method, idA can be changed to any hadron, while idB must be a proton or a neutron when using this feature. This is useful for example in hadronic cascades in a medium. It is here assumed that only the SoftQCD (and LowEnergyQCD if relevant) hadron-nucleon processes are being used.

int Pythia::forceTimeShower( int iBeg, int iEnd, double pTmax, int nBranchMax = 0)
perform a final-state shower evolution on partons in the event event 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 forceTimeShower method can be used in conjunction with the forceHadronLevel one below. Further comments are found here.
argument iBeg, iEnd : the first and last entry of the event record to be affected by the call.
argument pTmax : the maximum pT scale of emissions. Additionally, as always, the scale variable 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.
argument nBranchMax (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.
Note: The method returns the number of branchings that has been generated.

bool Pythia::forceHadronLevel(bool findJunctions = true)
hadronize the existing event record, i.e. perform string fragmentation and particle decays. There are two main applications. Firstly, you can use the same parton-level content as a basis for repeated hadronization attempts, in schemes intended to save computer time. Secondly, you may have an external program that can simulate the full partonic level of the event - hard process, parton showers, multiparton interactions, beam remnants, colour flow, and so on - but not hadronization. Further details are found here.
argument findJunctions (default = on) : 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.)
Note: The method returns false if the hadronization fails. The event record is then not consistent and should not be studied.

bool Pythia::moreDecays()
perform decays of all particles in the event record that have not been decayed but should have been done so. This can be used e.g. for repeated decay attempts, in schemes intended to save computer time. Further details are found here.
Note: The method returns false if the decays fail. The event record is then not consistent and should not be studied.

bool Pythia::moreDecays(int i)
perform decay of the particle at index i of the event record, when possible. Sequential decays are not performed, but have to be taken care of successively, if so desired.

bool Pythia::forceRHadronDecays()
perform decays of R-hadrons that were previously considered stable. This could be if an R-hadron is sufficiently long-lived that it may interact in the detector between production and decay, so that its four-momentum is changed. Further details are found here.
Note: The method returns false if the decays fail. The event record is then not consistent and should not be studied.

bool Pythia::doLowEnergyProcess(int i1, int i2, int procType)
allow two hadrons, located in positions i1 and i2 of the normal event record to interact with each other and give rise to new hadrons by Low-energy QCD Processes. The possible interaction procTypes are (1) inelastic nondiffractive, (2) elastic, (3, 4) single diffractive where either first or second hadron is broken up, (5) double diffractive, (7) excitation, (8) annihilation and (9) resonant. It is also possible to specify the formation of a specific resonance by setting procType to the id of that particle. No perturbative stage is applied in either case, as relevant at low energies. It can be used e.g. to model Hadronic Rescattering in the final state, where partial cross sections are first calculated to provide the relevant mix of different collision types. This method does not itself decay unstable hadrons, but that could be achieved e.g. with a Pythia::moreDecays() call.

double Pythia::getSigmaTotal()
double Pythia::getSigmaTotal(double eCM12, int mixLoHi = 0)
double Pythia::getSigmaTotal(int id1, int id2, double eCM12, int mixLoHi = 0)
double Pythia::getSigmaTotal(int id1, int id2, double eCM12, double m1, double m2, int mixLoHi = 0)
these four methods return a total cross section for two hadrons to collide. It can be useful to have this access for some applications, where one needs to decide whether two hadrons should be allowed to collide or not before calling Pythia. One example is for the already-mentioned Hadronic Rescattering, but it could also involve tracking a particle through a medium. It combines separate low-energy and a high-energy descriptions, with a reasonably transition.
argument id1, id2 : the identity codes of the two colliding hadrons. If unspecified, the ids are taken from the beam configuration of the Pythia object.
argument eCM12 : the collision center-of-mass energy. If unspecified, the beam energy is taken from the beam configuration of the Pythia object.
argument m1, m2 : the masses of the two incoming hadrons. If unspecified, the particles are assumed to be on-shell.
argument mixLoHi : Gives a choice of cross section description.
Option -1 gives the low-energy cross sections implemented for hadronic rescattering in [Sjo20].
Option 1 gives high-energy cross sections based on the SaS/DL setup in TotalCrossSections, as extended in [Sjo21].
Default option 0 gives the former behaviour at low energies and the latter at high, with a mix in between.

double Pythia::getSigmaPartial(int procType)
double Pythia::getSigmaPartial(double eCM, int procType, int mixLoHi = 0)
double Pythia::getSigmaPartial(int id1, int id2, double eCM12, int procType, int mixLoHi = 0)
double Pythia::getSigmaPartial(int id1, int id2, double eCM12, double m1, double m2, int procType, int mixLoHi = 0)
these two methods match the getSigmaTotal ones above, but offers the total cross section split into interaction procType, (1) inelastic nondiffractive, (2) elastic, (3, 4) single diffractive where either first or second hadron is broken up, (5) double diffractive, (7) excitation, (8) annihilation and (9) resonant. You can also get the same total cross sections as in getSigmaTotal for procType = 0, but with a larger time consumption if this is the only number you want.

void Pythia::LHAeventList()
list the Les Houches Accord information on the current event, see LHAup::listEvent(...). (Other listings are available via the class members below, so this listing is a special case that would not fit elsewhere.)

bool Pythia::LHAeventSkip(int nSkip)
skip ahead a number of events in the Les Houches generation sequence, without doing anything further with them, see 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.
Note: The method returns false if the operation fails, specifically if the end of a LHEF has been reached, cf. next() above.

Finalize

There is no required finalization step; you can stop generating events when and how you want. It is still recommended that you make it a routine to call the following method at the end. A second method provides a deprecated alternative.

void Pythia::stat()
list statistics on the event generation, specifically total and partial cross sections and the number of different errors. For more details see here and for available options here.

Interrogate settings

Normally settings are used in the setup and initialization stages to determine the character of a run, e.g. read from a file with the above-described 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)
read in a boolean variable from the Settings database.
argument key : the name of the variable to be read.

int Pythia::mode(string key)
read in an integer variable from the Settings database.
argument key : the name of the variable to be read.

double Pythia::parm(string key)
read in a double-precision variable from the Settings database.
argument key : the name of the variable to be read.

string Pythia::word(string key)
read in a string variable from the Settings database.
argument key : the name of the variable to be read.

Get a PDF set

Pythia contains an number of parton density sets internally, plus an interface to LHAPDF (5 or 6). With the method below, this machinery is also made available for external usage.

PDF* getPDFPtr(int id, int sequence = 1)
get a pointer to a PDF object. Which PDF is returned depends on the PDF Selection settings.
argument id : the identity code of the incoming particle.
argument sequence : 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 (PDF:useHard etc.).

Data members

The 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
the hard-process event record, see here for further details.

Event Pythia::event
the complete event record, see here for further details.

Info Pythia::info
further information on the event-generation process, see here for further details.

Settings Pythia::settings
the settings database, see here for further details.

ParticleData Pythia::particleData
the particle properties and decay tables database, see here for further details.

Rndm Pythia::rndm
the random number generator, see here and here for further details.

CoupSM Pythia::coupSM
Standard Model couplings and mixing matrices, see here for further details.

SusyLesHouches Pythia::slha
parameters and particle data in the context of supersymmetric models, see here for further details.

PartonSystems Pythia::partonSystems
a grouping of the partons in the event record by subsystem, see here for further details.