ParticleDataEntry, which stores the relevant information
on a particle species, andParticleDataTable, which is a map of PDG particle
id numbers [Yao06] onto the relevant
ParticleDataEntry.DecayChannel, which stores info on one particular decay
mode.DecayTable, which is a vector of
DecayChannel's, containing all the decay modes of a
particle, and also methods for picking a decay mode.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.
ParticleDataTable for a given PDG particle identity code
id, here presented by the name used to access this property:
method name(id) id determines which of the two is returned, with
void used to indicate the absence of an antiparticle.
method spinType(id) method chargeType(id) id.
method colType(id) id.
method m0(id) method mWidth(id) method mMin(id), mMax(id) method tau0(id) method isResonance(id) m0 above 20 GeV are by default
initialized to be considered as resonances.
method mayDecay(id) tau0 below 1000 mm are
by default initialized to allow decays.
method doExternalDecay(id) pythia.decayPtr
method should be provided with the list of relevant particles.
method isVisible(id) method doForceWidth(id) false)
is then that the width is calculated from the mass, but it is
possible to force the resonance
to retain the nominal width. Branching ratios and the running of the
total width are unaffected.
Similarly-named methods can also be used to set these properties.
We do not provide the details here, since other methods to be
introduced below are the ones likely to be used for such tasks.
(Normally the correspondence is obvious in the header file, but
for the name you either can use two methods to set name and
antiparticle name separately, or use one method that takes them
both as input.)
There are some further methods for output only, i.e. properties
that cannot be set directly:
method particleDataPtr(id) ParticleDataEntry object.
method hasAnti(id) void).
method charge(id) double equal
to chargeType(id)/3.
method mass(id) ParticleData:modeBreitWigner switch). Is equal to
m0(id) for particles without width.
method constituentMass(id) method m0Min(id), m0Max(id) mMin() and mMax(), except that
for particles with no width the m0(id) value is returned.
method isLepton(id) method isQuark(id) method isGluon(id) method isHadron(id) method heaviestQuark(id) id number, for a hadron.
method onMode() method bRatio() method meMode() method multiplicity() method product(i) method addChannel( branchingRatio, meMode, product1, ...) method size() method rescaleBR(newSumBR) method pick() method dynamicPick() dynamicBR() method.
Pythia object pythia is created, the
ParticleDataTable member pythia.particleData
is asked to scan the ParticleData.xml file.
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
enclosing particle. In both cases XML syntax is used, with attributes
used to identify the stored properties, and with omitted properties
defaulting back to 0 where meaningful. The particle and channel
information may be split over several lines, up to the > endtoken.
The format of a <particle tag is:
<particle id="..." name="..." antiName="..." spinType="..." chargeType="..." colType="..."
m0="..." mWidth="..." mMin="..." mMax="..." tau0="...">
</particle>
where the fields are the properties already introduced above.
Note that isResonance, mayDecay,
doExternalDecay, isVisible and
doForceWidth are not set here, but are provided with
default values by the rules described above. Once initialized, also
these latter properties can be changed, see below.<channel> tag is:
<channel onMode="..." bRatio="..." meMode="..." products="..." />
again see properties above. The products are given as a blank-separated
list of id codes.
.xml file should not
be changed, except by the PYTHIA authors. Any changes should be done
with the help of the methods described below.
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.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.readString("111:mayDecay = off");
switches off the decays of the pi^0.name, antiName,
spinType, chargeType, colType,
m0, mWidth, mMin,
mMax, tau0, isResonance,
mayDecay, doExternalDecay,
isVisible and doForceWidth. 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.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).
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 by blanks (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 spinType chargeType colType m0 mWidth mMin mMax tau0
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.
If the string contains fewer fields than expected the trailing
properties are set to vanish ("void", 0 or 0.). Note that such a
truncated string should not be followed by a comment, since this
comment would then be read in as if it contained the missing properties.
The truncation can be done anywhere, specifically a string with only
id:new defines a new "empty" particle.
As before, isResonance, mayDecay,
doExternalDecay, isVisible and
doForceWidthare (re)set to their default values, and
would have to be changed separately if required.
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.
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
onMode, bRatio, meMode 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 = onMode bRatio meMode product1 product2 ....
To add a new channel at the end, use
id:addChannel = onMode bRatio meMode product1 product2 ....
It is currently not possible to remove a channel selectively, but
setting its branching ratio vanishing is as effective. If you want to
remove all existing channels and force decays into one new channel
you can use
id:oneChannel = onMode bRatio meMode product1 product2 ....
A first oneChannel command could be followed by
several subsequent addChannel ones, to build
up a completely new decay table for an existing particle.
When adding new channels or changing branching ratios in 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.
There are a few commands that will study all the decay channels of the
given particle, to switch them on or off as desired. The
id:onMode = onMode
will set the onMode property of all channels to the
desired value. The
id:offIfAny = product1 product2 ....
id:onIfAny = product1 product2 ....
id:onPosIfAny = product1 product2 ....
id:onNegIfAny = product1 product2 ....
will set the onMode 0, 1, 2 or 3, respectively, for all
channels which contain any of the enumerated products, where the matching
to these products is done without distinction of particles and
antiparticles. Note that "Pos" and "Neg"
are slightly misleading since it refers to the particle and antiparticle
of the id species rather than charge, but should still be
simpler to remember and understand than alternative notations.
Correspondingly
id:offIfAll = product1 product2 ....
id:onIfAll = product1 product2 ....
id:onPosIfAll = product1 product2 ....
id:onNegIfAll = product1 product2 ....
will set the onMode 0, 1, 2 or 3, respectively, for all
channels which contain all of the enumerated products, again without
distinction of particles and antiparticles. If the same product appears
twice in the list it must also appear twice in the decay channel, and
so on. The decay channel is allowed to contain further particles,
beyond the product list. By contrast,
id:offIfMatch = product1 product2 ....
id:onIfMatch = product1 product2 ....
id:onPosIfMatch = product1 product2 ....
id:onPosIfMatch = product1 product2 ....
requires the decay-channel multiplicity to agree with that of the product
list, but otherwise works as the onIfAll/offIfAll methods.
Note that the action of several of the commands depends on the order
in which they are executed, as one would logically expect. For instance,
id:oneChannel removes all decay channels of id
and thus all previous changes in this decay table, while subsequent
additions or changes would still take effect. Another example would be that
23:onMode = off followed by 23:onIfAny = 1 2 3 4 5
would let the Z^0 decay to quarks, while no decays would be
allowed if the order were to be reversed.
b) The Pythia readString(string) method actually
does not do changes itself, but sends on the string either to the
ParticleData class or to the Settings one.
If desired, it is possible to communicate directly with the corresponding
ParticleData method:
pythia.particleData.readString("111:mayDecay = off");
pythia.particleData.readString("15:2:products = 16 -211");
In this case, changes intended for Settings would not be
understood.
c) 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.
d) 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
The file can be read by the
pythia.readFile(fileName);
method, where fileName is a string, e.g.
pythia.readFile("main.cmnd"). Each line is process as
described for the string in 2a). This file can freely mix commands to
the Settings and ParticleData classes.
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.
pythia.particleData.listAll();
The listing is by increasing id number. It shows the basic
quantities introduced above. Some are abbreviated in the header to fit on
the lines: spn = spinType, chg = chargeType,
col = colType, res = isResonance,
dec = mayDecay && canDecay (the latter checks that decay
channels have been defined), ext = doExternalDecay,
vis = isVisible and wid = doForceWidth.
pythia.particleData.listChanged();
(This info is based on a further hasChanged flag of a particle
or a channel, set true whenever any of the changing methods are
used. It is possible to manipulate this value, but this is not recommended.)
By default the internal initialization of the widths of resonances such as
gamma^*/Z^0, W^+-, t/tbar, H^0 do not count as changes; if you want
to list also those changes instead call listChanged(true).
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>.
<particle and
<channel lines already described. You use the method
particleData.listXML(fileName) to produce such an XML
file and particleData.readXML(fileName) to read it back
in after editing.
b) Fixed/free format, using exactly the same information as illustrated
for the <particle and <channel lines
above, but now without any tags. This means that all information fields
must be provided (if there is no antiparticle then write
void), in the correct order (while the order is irrelevant
with XML syntax), and all on one line. Information is written out in
properly lined-up columns, but the reading is done using free format,
so fields need only be separated by at least one blank. Each new particle
is supposed to be separated by (at least) one blank line, whereas no
blank lines are allowed between the particle line and the subsequent
decay channel lines, if any. You use the method
particleData.listFF(fileName) to produce such a fixed/free
file and particleData.readFF(fileName) to read it back
in after editing.
As an alternative to the readXML and readFF
methods you can also use the
particleData.reInit(fileName, xmlFormat) method, where
xmlFormat = true (default) corresponds to reading an XML
file and xmlFormat = false to a fixed/free format one.
To check that the new particle and decay tables makes sense, you can use
the particleData.checkTable() method, either directly or by
switching it on among the standard
error checks.