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. 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.

Initialization - normal usage

  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. 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. (Hypothetically you could use several Pythia objects sequentially, but if done in parallel the static character of some program elements is likely not to give the desired behaviour.)
    By default all output from Pythia will be on the cout stream, but the list methods below do allow output to alternative streams or files (by an optional last argument, a reference to an ostream, usually not explicitly written out here).
  3. 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 static classes, and 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 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 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 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 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("111:mayDecay = false");
        pythia.readString("TimeShower:pTmin = 1.0");
    
    The readString(...) method is intended primarily for a few changes. It can also be useful if you want to construct a parser of input files that contain commands to several different 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(...) method introduced above. You can thus freely mix comment lines and lines handed on to Settings or to ParticleDataTable. Again, an optional second argument false allows you to switch off warning messages for unknown variables.
    This approach is better suited for more extensive changes than a direct usage of readString(...), and can also avoid having to recompile and relink your main program between runs.
  4. 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.

    c) pythia.init( idA, idB, eCM);
    is similar, but you specify the CM energy, and you are assumed in the rest frame.

    d) pythia.init();
    with no arguments will read the beam parameters from the Main 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.

    e) pythia.init( LHAinit*, LHAevnt*);
    assumes Les Houches Accord [Boo01] initialization information is available in an LHAinit class object, and that LHA event information will be provided by the LHAevnt class object, and that pointers to these objects are handed in (further instructions).

    d) pythia.init( "filename");
    assumes a file in the Les Houches Event File format [Alw06] is provided (further instructions).

  5. 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(); 
    

Initialization - advanced usage

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 to the .xml files, originally stored in the xmldoc directory, where default settings and particle data are found. This can be done in two ways.
  1. 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/pythia8090/xmldoc
    
    while in other shells it could be
         export PYTHIA8DATA=/home/myname/pythia8090/xmldoc
    
    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 permanant assignment.
  2. You can provide the path as argument to the Pythia constructor, e.g.
         Pythia pythia("/home/myname/pythia8090/xmldoc");
    
When 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.

  1. If you are not satisfied with the list of parton density functions that are implemented internally or available via the LHAPDF interface (see PDF Selection page), you can suppy your own by a call to the setPDFPtr(...) method
          pythia.setPDFptr( pdfAPtr, pdfBPtr); 
    
    where pdfAPtr and pdfBPtr are pointers to two Pythia PDF objects (further instructions). 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 multiple interactions.
  2. 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 (further instructions).
  3. 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 (further instructions). The Pythia default random number generator is perfectly good, so this is only intended for consistency in bigger frameworks.
  4. 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 (further instructions).
  5. If you want to implement a cross section of your own, but still make use of the built-in phase space selection machinery, you can use
          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 (further instructions). This call can be used repeatedly to hand in several different processes.
  6. If you are a real expert and want to replace the PYTHIA initial- and final-state showers, you can use
          pythia.setShowerPtr( timesDecPtr, timesPtr, spacePtr);
    
    where timesDecPtr and timesPtr derive from the TimeShower base class, and spacePtr from SpaceShower (further instructions).

The event loop

  1. 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. It makes sense to allow a few false values before a run is aborted, so long as the related faulty events are skipped.
  2. 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 public object is info, which offers a set of one-of-a kind pieces of information about the most recent event (further information).

Finishing

  1. 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. With optional argument true also further statistics is printed. Currently this means the number of different subprocesses generated in the multiple-interactions framework.