Program Flow

Recall that, to first order, the event generation process can be subdivided into three stages:
  1. Initialization.
  2. The event loop.
  3. 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.

Initialization

  1. Already at the top of the main program file, you need to include the proper header file
        #include "Pythia.h"
    
    To simplify typing, it also makes sense to declare
        using namespace Pythia8; 
    
  2. (compulsory) 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 hypothetically you could use several.
    All output from Pythia will be on the cout stream. If this is not convenient, you can give a reference to another stream as an optional argument
        Pythia pythia(ostream);
    
    but this does not work so far! (??)
  3. (compulsory, or to be replaced by next point) You next want to set up the character of the run. The pages under the "Setup Run Parameters" heading in the index describe all the options available. The default values and your modifications are stored in two databases, one for generic settings and one for particle data. Both of these are static classes, and are initialized with their default values by the Pythia constructor. A third static class, eventually to disappear, is the interface to the old Fortran 77 PYTHIA 6, currently used for generating hard processes.
    You can use the dedicated methods of each class to change the database default values to fit the needs of your current run. However, the
        pythia.readString(string)
    
    method provides a covenient uniform interface to all three of them. 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 not a letter or a digit nothing will be done;
    (ii) if the string begins with Pythia6:, this part is peeled off, and the rest is sent on to Fortran PYTHIA 6, using the pygive method in that package;
    (iii) if the string begins with a digit it is assumed to contain particle data updates, and so sent on to pythia.particleData.readString(string);
    (iv) if none of the above, the string is assumed to contain a setting, and is sent on to pythia.settings.readString(string).
    In the latter two cases, a warning is issued whenever a string cannot be recognized (maybe because of a spelling mistake), unless an optional second argument false is used to switch off warnings.
    Some examples would be
        pythia.readString("Pythia6:msel = 6");
        pythia.readString("111:mayDecay = false");
        pythia.readString("TimeShower:pTmin = 1.0");
    
    The methods in this paragraph are intended for small changes; for more extensive ones it is better to store all the changes in a file, see next.
  4. (alternative to previous point) 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 pythia.readString() method introduced above. You can thus freely mix comment lines and lines handed on to Settings, ParticleDataTable and Pythia6. This would be the normal way to set up what a run is supposed to do. Again, an optional second argument false allows you to switch off warning messages for unknown variables.
    Of course, if your file is also supposed to contain commands to other libraries, so you have to build your own parser, the readString method above may be more appropriate.
  5. (optional) If you are not satisfied with the (short) list of parton density functions that are implemented internally in Pythia, you can suppy your own by a call to the PDFptr method
          pythia.PDFptr( pdfA, pdfB); 
    
    where pdfA and pdfB are pointers to two Pythia PDF objects (further instructions). Note that pdfA and pdfB 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.
  6. (optional) If you want to perform some particle decays with an external generator, you can call the decayPtr method
          pythia.decayPtr( decayHandler, particles)
    
    where the decayHandler derives from the DecayHandler base class and particles is a vector of particle codes to be handled (further instructions).
  7. (optional) If you want to use an external random number generator, you can call the rndmEnginePtr method
          pythia.rndmEnginePtr( rndmEngine) 
    
    where rndmEngine derives from the RndmEngine base class (further instructions). The Pythia default random number generator is perfectly good, so this is only intended for consistency in bigger frameworks.
  8. (compulsory) Next comes the initialization stage, where all remaining details of the generation are to be specified. The init method allows a few different input formats, so you can pick the one convenient for you:
    a) pythia.init( idA, idB, eA, eB);
    lets you specify the identities and energies of the two incoming beam particles, with A (B) assumed moving in the +z (-z) direction.
    b) pythia.init( idA, idB, eCM);
    is similar, but you specify the CM energy, and you are assumed in the rest frame.
    c) pythia.init( LHAinit*, LHAevnt*);
    assumes Les Houches Accord initialization information is available in an LHAinit class object, and that LHA event information will be provided by the LHAevnt class object (further instructions).
  9. (optional) 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

  1. (compulsory) 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, but also caused by a failure of Pythia to generate an event, or that an event was generated but something strange was detected in it.
  2. (optional) 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.
    Furthermore, 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.

Finishing

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