Between the creation of the Pythia object and the
init call for it, you may use the methods of the
ParticleData 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.
The particle id (> 0) and the property to be changed must be given,
separated by a colon.
The allowed properties are: 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.
Strings beginning with a non-alphanumeric character, like # or !,
are assumed to be comments and are not processed at all. 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).
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
doForceWidth are (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. (Thus the
multiplicity of a decay channel need not be input; it is automatically
calculated from the products list.) 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,
depending on whether the string begins with a digit or a letter.
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 ParticleData class, one for each. These are
further described below. 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") (or an istream
instead of a fileName). Each line is processed as
described for the string in 2a). This file can freely mix commands to
the Settings and ParticleData classes.