The Particle Data Scheme


Warning: The handling of particle data has yet to reach its final form. This is of course true for the whole program, but in terms of user interaction probably more so here than elsewhere.

Introduction

The management of particle data is based on the four classes: These files together form a database that is continuously being used as the program has to assign particle masses, decay modes etc.

The ParticleDataTable class is purely static, i.e. you can interact with it directly by ParticleDataTable::command(argument). However, a particleData object of the ParticleDataTable class is a public member of the Pythia class, so an alternative notation would be pythia.particleData.command(argument), assuming that pythia is an instance of the Pythia class. Further, for some of the most frequent user tasks, Pythia methods have been defined, so that pythia.command(argument) would work, see further below.

A fundamental difference between the ParticleData classes and the Settings ones is that the former are accessed regularly during the event generation process, as a new particle is produced and its mass need to be set, e.g., while Settings is mainly/only used at the initialization stage. Nevertheless, it is not a good idea to change data in either of them in mid-run, since this may lead to inconsistencies.

Stored properties

Currently the following particle properties are stored in the ParticleDataTable for a given PDG particle identity code id, here presented by the name used to access this property:

method name="hasAnti(id)"
bool whether a distinct antiparticle exists or not;

method name="name(id)"
particle and antiparticle names are stored separately, the sign of id determines which of the two is returned, with void used to indicate the absence of an antiparticle;

method name="charge3(id)"
three times the charge (to make it an integer), alternatively charge(id), which is a double equal to charge3(id)/3.;

method name="colType(id)"
the colour type, with 0 uncoloured, 1 triplet, -1 antitriplet and 2 octet;

method name="m0(id)"
the nominal mass m_0 (in GeV);

method name="constituentMass(id)"
is the constituent mass for a quark, hardcoded as m_u = m_d = 0.325, m_s = 0.50, m_c = 1.60 and m_b = 5.0 GeV, for a diquark the sum of quark constituent masses, and for everything else the same as the ordinary mass

method name="width(id)"
the width Gamma of the Breit-Wigner distribution (in GeV);

method name="range(id)"
the allowed mass range generated by the Breit-Wigner, | m - m_0 | < range (in GeV);

method name="tau0(id)"
the nominal proper lifetime tau_0 (in mm/c);

method name="mayDecay(id)"
a flag telling whether a particle species may decay or not, offering the main user switch (whether a given particle of this kind then actually will decay also depends on other flags in the ParticleDecays class).

method name="externalDecay(id)"
a flag telling whether a particle should be handled by an external decay package or not, with the latter default (further information).

Similar methods can also be used to set these properties.

There are five further methods for output:

method name="particleDataPtr(id)"
returns a pointer to the ParticleDataEntry object;

method name="mass(id)"
returns a mass distributed according to a truncated Breit-Wigner, with parameters as above (see also the ParticleData:modeBreitWigner switch below);

method name="isVisible(), isInvisible()"
particles with/without strong or electromagnetic interactions, which thereby are or are not visible in a normal detector.

method name="spin(id)"
2 * s + 1 where known, else 0.

The following properties are stored for each decay channel:

method name="branchingRatio()"
the branching ratio;

method name="modeME()"
the mode of processing this channel, possibly with matrix elements (see below);

method name="multiplicity()"
the number of decay products in a channel, at most 8;

method name="product(i)"
a list of the decay products, 8 products 0 <= i < 8, with trailing unused ones set to 0.

The decay table also defines a few methods:

method name="addChannel( branchingRatio, modeME, product1, ...)"
adds a decay channel with up to 8 products.

method name="size()"
gives the number of decay channels for a particle;

method name="pick()"
picks one decay channel according to their respective branching ratios;

method name="rescaleBR(newSumBR)"
rescale all branching ratios to the provided new sum, by default unity.

Operation

The normal flow of the particle data operations is:
  1. When a Pythia object pythia is created, the ParticleDataTable member pythia.particleData is asked to scan the ParticleData.xml file.
  2. All lines beginning with <particle> are scanned for information on a particle species, and all lines beginning with <channel> are assumed to contain a decay channel of the most recent particle. The information stored in a <particle> line is: id, name, antiparticle name, 3*charge, colour type, nominal mass, width, range, nominal proper lifetime, and whether the particle may decay. The information stored in a <channel> is: branching ratio, mode, and decay products.
    Important: the values in the .xml file should not be changed, except by the PYTHIA authors. Any changes should be done with the help of the methods described below.
  3. Between the creation of the Pythia object and the init call for it, you may use the methods of the ParticleDataTable class to modify some of the default values. Several different approaches can be chosen for this.

    a) Inside your main program you can directly set values with

        pythia.particleData.readString(string)
    
    where both the variable name and the value are contained inside the character string, separated by blanks and/or a =, e.g.
        pythia.particleData.readString("111:mayDecay = off"); 
    
    switches off the decays of the pi^0.
    The particle id (> 0) and the property to be changed must be given, separated by a colon.
    The allowed properties are: name, antiName, charge3, colType, m0, width, range, tau0 and mayDecay. All of these names are case-insensitive. Names that do not match an existing variable are ignored. A warning is printed, however, unless an optional second argument false is used. For bool values, the following notation may be used interchangeably: true = on = yes = ok = 1, while everything else gives false (including but not limited to false, off, no and 0).
    A further command is rescaleBR, which rescales each of the existing branching ratios with a common factor, such that their new sum is the provided value. This may be a first step towards adding new decay channels, see further below.
    Particle data often comes in sets of closely related information. Therefore some properties expect the value to consist of several numbers. These can then be separated either by blanks and/or by commas. A simple example is names, which expects both the name and antiname to be given. A more interesting one is the all property,
      
        id:all = name antiName charge3 colType m0 width range tau0 mayDecay
    
    where all the current information on the particle itself is replaced, but any decay channels are kept unchanged. Using new instead of all also removes any previous decay channels.

    Alternatively the id code may be followed by another integer, which then gives the decay channel number. This then has to be followed by the property specific to this channel, either branchingRatio, modeME or products. In the latter case all the products of the channel should be given:

        id:channel:products =  product1 product2 ....  
    
    The line will be scanned until the end of the line, or until a non-number word is encountered, or until the maximum allowed number of eight products is encountered, whichever happens first. It is also possible to replace all the properties of a channel in a similar way:
        id:channel:all = branchingRatio modeME product1 product2 ....  
    
    To add a new channel at the end, use
        id:addChannel = branchingRatio modeME product1 product2 ....
    
    It is currently not possible to remove a channel selectively, but setting its branching ratio vanishing is as effective.
    When adding new channels or changing branching ratios is general, note that, once a particle is to be decayed, the sum of branching ratios is always rescaled to unity. Beforehand, rescaleBR may be used to rescale an existing branching ratio by the given factor.

    The Pythia class contains a readString method that hand on to this method, or to corresponding methods in Settings or Pythia6, and therefore may offer the most convenient form, i.e. more compactly:

        pythia.readString("111:mayDecay = off"); 
        pythia.readString("15:2:products = 16 -211"); 
    

    b) Underlying this are commands for all the individual properties in the ParticleDataTable class, one for each. Thus, an example now reads

        pythia.particleData.mayDecay(111, false);
    
    Boolean values should here be given as true or false.

    c) A simpler and more useful way is to collect all your changes in a separate file, with one line per change, e.g.

        111:mayDecay = off
    
    Each line is process as described for the string in 3a). Since names that do not match an existing variable are ignored, you can easily comment out lines. The recommended way would be to add a special character like # or ! in the first column.
    The file can be read by the
        pythia.particleData.readFile("filename") 
    
    method, alternatively by the
        pythia.readFile("filename") 
    
    method. The latter has the advantage that it allows you to freely mix commands to the Settings, ParticleData and Pythia6 classes, and so is preferable.
  4. A routine reInit("filename") is provided, and can be used to zero the particle data table and reinitialize from scratch. Such a call might be required if several Pythia objects are created in the same run, and requested to have different values - by default the init() call is only made the first time. Several pythia with different values would have to run sequentially and not in parallel, though; recall that there is only one instance of the particle data table.
  5. You may at any time obtain a listing of all the particle data by calling
        pythia.particleData.listAll();
    
    The listing is by increasing id number. To list only those particles that were changed (one way or another, the listing will not tell what property or decay channel was changed), instead use
        pythia.particleData.listChanged();
    
    To list only one particle, give its id code as argument to the list(...) function.. To list a restricted set of particles, give in their id codes to list(...) as a vector<int>.

References

  1. Particle Data Group, S. Eidelman et al., Phys. Lett. B592 (2004) 1