1 <chapter name="The Particle Data Scheme">
3 <h2>The Particle Data Scheme</h2>
5 The particle data scheme may take somewhat longer to understand than
6 the settings one. In particular the set of methods to access information
7 is rather more varied, to allow better functionality for advanced usage.
8 However, PYTHIA does come with a sensible default set of particle
9 properties and decay tables. Thus there is no need to learn any of the
10 methods on this page to get going. Only when you perceive a specific need
11 does it make sense to learn the basics.
14 The central section on this page is the Operation one. The preceding
15 sections are mainly there to introduce the basic structure and the set
16 of properties that can be accessed.
20 The management of particle data is based on the four classes:
22 <li><code>ParticleDataEntry</code>, which stores the relevant information
23 on a particle species, and</li>
24 <li><code>ParticleDataTable</code>, which is a map of PDG particle
25 <code>id</code> numbers <ref>Yao06</ref> onto the relevant
26 <code>ParticleDataEntry</code>.</li>
27 <li><code>DecayChannel</code>, which stores info on one particular decay
29 <li><code>DecayTable</code>, which is a vector of
30 <code>DecayChannel</code>'s, containing all the decay modes of a
31 particle, and also methods for picking a decay mode.</li>
33 The objects of these classes together form a database that is
34 continuously being used as the program has to assign particle masses,
38 The <code>ParticleDataTable</code> class is purely static, i.e. you
39 can interact with it directly by
40 <code>ParticleDataTable::command(argument)</code>.
41 However, a <code>particleData</code> object of the
42 <code>ParticleDataTable</code> class is a public member of the
43 <code>Pythia</code> class, so an alternative
44 notation would be <code>pythia.particleData.command(argument)</code>,
45 assuming that <code>pythia</code> is an instance of the
46 <code>Pythia</code> class. Further, for some of the most frequent user
47 tasks, <code>Pythia</code> methods have been defined, so that
48 <code>pythia.command(argument)</code>
49 would work, see further below.
52 A fundamental difference between the <code>ParticleData</code>
53 classes and the <code>Settings</code> ones is that the former
54 are accessed regularly during the event generation process, as a new
55 particle is produced and its mass need to be set, e.g., while
56 <code>Settings</code> is mainly/only used at the initialization stage.
57 Nevertheless, it is not a good idea to change data in either of them
58 in mid-run, since this may lead to inconsistencies.
60 <h3>Stored properties for particles</h3>
62 Currently the following particle properties are stored in the
63 <code>ParticleDataTable</code> for a given PDG particle identity code
64 <code>id</code>, here presented by the name used to access this property:
66 <method name="name(id)">
67 particle and antiparticle names are stored separately, the sign of
68 <code>id</code> determines which of the two is returned, with
69 <code>void</code> used to indicate the absence of an antiparticle.
72 <method name="spinType(id)">
73 the spin type, of the form <ei>2 s + 1</ei>, with special code 0
74 for entries of unknown or indeterminate spin.
77 <method name="chargeType(id)">
78 three times the charge (to make it an integer), taking into account
79 the sign of <code>id</code>.
82 <method name="colType(id)">
83 the colour type, with 0 uncoloured, 1 triplet, -1 antitriplet and 2
84 octet, taking into account the sign of <code>id</code>.
87 <method name="m0(id)">
88 the nominal mass <ei>m_0</ei> (in GeV).
91 <method name="mWidth(id)">
92 the width <ei>Gamma</ei> of the Breit-Wigner distribution (in GeV).
95 <method name="mMin(id), mMax(id)">
96 the lower and upper limit, respectively, of the allowed mass range
97 generated by the Breit-Wigner (in GeV). If <ei>mMax < mMin</ei>
98 then no upper limit is imposed. Have no meanings for particles
99 without width, and would typically be 0 there.
102 <method name="tau0(id)">
103 the nominal proper lifetime <ei>tau_0</ei> (in mm/c).
106 <method name="isResonance(id)">
107 a flag telling whether a particle species are considered as a resonance
108 or not. Here <aloc href="ResonanceDecays">"resonance"</aloc>
109 is used as shorthand for any massive particle
110 where the decay process should be counted as part of the hard process
111 itself, and thus be performed before showers and other event aspects
112 are added. Restrictions on allowed decay channels is also directly
113 reflected in the cross section of simulated processes, while those of
114 normal hadrons and other light particles are not.
115 In practice, it is reserved for states above the <ei>b bbar</ei>
116 bound systems in mass, i.e. for <ei>W, Z, t</ei>, Higgs states,
117 supersymmetric states and (most?) other states in any new theory.
118 All particles with <code>m0</code> above 20 GeV are by default
119 initialized to be considered as resonances.
122 <method name="mayDecay(id)">
123 a flag telling whether a particle species may decay or not, offering
124 the main user switch. Whether a given particle of this kind then actually
125 will decay also depends on it having allowed decay channels, and on
126 other flags for <aloc href="ParticleDecays">particle decays</aloc>.
127 All particles with <code>tau0</code> below 1000 mm are
128 by default initialized to allow decays.
131 <method name="doExternalDecay(id)">
132 a flag telling whether a particle should be handled by an external
133 decay package or not, with the latter default. Can be manipulated as
134 described on this page, but should normally not be. Instead the
135 <aloc href="ExternalDecays"><code>pythia.decayPtr</code></aloc>
136 method should be provided with the list of relevant particles.
139 <method name="isVisible(id)">
140 a flag telling whether a particle species is to be considered as
141 visible in a detector or not, as used e.g. in analysis routines.
142 By default this includes neutrinos and a few BSM particles
143 (gravitino, sneutrinos, neutralinos) that have neither strong nor
144 electromagnetic charge, and are not made up of constituents that
145 have it. The value of this flag is only relevant if a particle is
146 long-lived enough actually to make it to a detector.
149 <method name="doForceWidth(id)">
150 a flag valid only for resonances where PYTHIA contains code to
151 calculate the width of the resonance from encoded matrix-element
152 expressions, i.e. the <ei>Z^0</ei>, <ei>W^+-</ei>, <ei>t</ei>,
153 <ei>h^0</ei>, and a few more. The normal behaviour (<code>false</code>)
154 is then that the width is calculated from the mass, but it is
155 possible to <aloc href="ResonanceDecays">force</aloc> the resonance
156 to retain the nominal width. Branching ratios and the running of the
157 total width are unaffected.
161 Similarly-named methods can also be used to set these properties.
162 We do not provide the details here, since other methods to be
163 introduced below are the ones likely to be used for such tasks.
164 (Normally the correspondence is obvious in the header file, but
165 for the name you either can use two methods to set name and
166 antiparticle name separately, or use one method that takes them
170 There are some further methods for output only, i.e. properties
171 that cannot be set directly:
173 <method name="particleDataPtr(id)">
174 returns a pointer to the <code>ParticleDataEntry</code> object.
177 <method name="hasAnti(id)">
178 bool whether a distinct antiparticle exists or not. Is true if an
179 antiparticle name has been set (and is different from
183 <method name="charge(id)">
184 the electrical charge of a particle, as a <code>double</code> equal
185 to <code>chargeType(id)/3</code>.
187 <method name="mass(id)">
188 returns a mass distributed according to a truncated Breit-Wigner,
189 with parameters as above (see also the
190 <code>ParticleData:modeBreitWigner</code> switch). Is equal to
191 <code>m0(id)</code> for particles without width.
194 <method name="constituentMass(id)">
195 is the constituent mass for a quark, hardcoded as
196 <ei>m_u = m_d = 0.325</ei>, <ei>m_s = 0.50</ei>, <ei>m_c = 1.60</ei>
197 and <ei>m_b = 5.0</ei> GeV, for a diquark the sum of quark constituent
198 masses, and for everything else the same as the ordinary mass.
201 <method name="m0Min(id), m0Max(id)">
202 similar to <code>mMin()</code> and <code>mMax()</code>, except that
203 for particles with no width the <code>m0(id)</code> value is returned.
206 <method name="isLepton(id)">
207 true for a lepton or an antilepton (including neutrinos).
210 <method name="isQuark(id)">
211 true for a quark or an antiquark.
214 <method name="isGluon(id)">
218 <method name="isHadron(id)">
219 true for a hadron (made up out of normal quarks and gluons,
220 i.e. not for R-hadrons and other exotic states).
223 <method name="heaviestQuark(id)">
224 extracts the heaviest quark or antiquark, i.e. one with largest
225 <code>id</code> number, for a hadron.
228 <h3>Stored properties for decays</h3>
230 The following properties are stored for each decay channel:
232 <method name="onMode()">
233 0 if a channel is off,<br/>
235 2 if on for a particle but off for an antiparticle,<br/>
236 3 if on for an antiparticle but off for a particle.<br/>
237 If a particle is its own antiparticle then 2 is on and 3 off
238 but, of course, for such particles it is much simpler and safer
239 to use only 1 and 0.<br/>
240 The 2 and 3 options can be used e.g. to encode CP violation in
241 B decays, or to let the <ei>W</ei>'s in a <ei>q qbar -> W^+ W^-</ei>
242 process decay in different channels.
245 <method name="bRatio()">
249 <method name="meMode()">
250 the mode of processing this channel, possibly with matrix elements
251 (see the <aloc href="ParticleDecays">particle decays</aloc> description);
254 <method name="multiplicity()">
255 the number of decay products in a channel, at most 8.
256 (Is not set as such, but obtained from the products list below.)
259 <method name="product(i)">
260 a list of the decay products, 8 products 0 <= i < 8,
261 with trailing unused ones set to 0.
265 The decay table, a vector of decay channels, also defines a
268 <method name="addChannel( branchingRatio, meMode, product1, ...)">
269 adds a decay channel with up to 8 products.
272 <method name="size()">
273 gives the number of decay channels for a particle.
276 <method name="rescaleBR(newSumBR)">
277 rescale all branching ratios to the provided new sum,
281 <method name="pick()">
282 picks one decay channel according to their respective branching
286 <method name="dynamicPick()">
287 intended for resonances specifically, this picks one decay channel
288 according to the respective partial widths for the specific mass
289 value of the resonance; assumes that the partial widths are input
290 beforehand, using a special <code>dynamicBR()</code> method.
295 The normal flow of the particle data operations is:
300 When a <code>Pythia</code> object <code>pythia</code> is created, the
301 <code>ParticleDataTable</code> member <code>pythia.particleData</code>
302 is asked to scan the <code>ParticleData.xml</code> file.
305 All lines beginning with <code><particle</code> are scanned for
306 information on a particle species, and all lines beginning with
307 <code><channel</code> are assumed to contain a decay channel of the
308 enclosing particle. In both cases XML syntax is used, with attributes
309 used to identify the stored properties, and with omitted properties
310 defaulting back to 0 where meaningful. The particle and channel
311 information may be split over several lines, up to the > endtoken.
312 The format of a <code><particle</code> tag is:
314 <particle id="..." name="..." antiName="..." spinType="..." chargeType="..." colType="..."
315 m0="..." mWidth="..." mMin="..." mMax="..." tau0="...">
318 where the fields are the properties already introduced above.
319 Note that <code>isResonance</code>, <code>mayDecay</code>,
320 <code>doExternalDecay</code>, <code>isVisible</code> and
321 <code>doForceWidth</code> are not set here, but are provided with
322 default values by the rules described above. Once initialized, also
323 these latter properties can be changed, see below.<br/>
325 The format of a <code><channel></code> tag is:
327 <channel onMode="..." bRatio="..." meMode="..." products="..." />
329 again see properties above. The products are given as a blank-separated
330 list of <code>id</code> codes.
331 <note>Important</note>: the values in the <code>.xml</code> file should not
332 be changed, except by the PYTHIA authors. Any changes should be done
333 with the help of the methods described below.
337 Between the creation of the <code>Pythia</code> object and the
338 <code>init</code> call for it, you may use the methods of the
339 <code>ParticleDataTable</code> class to modify some of the default values.
340 Several different approaches can be chosen for this.
343 a) Inside your main program you can directly set values with
345 pythia.readString(string);
347 where both the variable name and the value are contained inside
348 the character string, separated by blanks and/or a =, e.g.
350 pythia.readString("111:mayDecay = off");
352 switches off the decays of the <ei>pi^0</ei>.<br/>
354 The particle id (> 0) and the property to be changed must be given,
355 separated by a colon.<br/>
357 The allowed properties are: <code>name</code>, <code>antiName</code>,
358 <code>spinType</code>, <code>chargeType</code>, <code>colType</code>,
359 <code>m0</code>, <code>mWidth</code>, <code>mMin</code>,
360 <code>mMax</code>, <code>tau0</code>, <code>isResonance</code>,
361 <code>mayDecay</code>, <code>doExternalDecay</code>,
362 <code>isVisible</code> and <code>doForceWidth</code>. All of these names
363 are case-insensitive. Names that do not match an existing variable
364 are ignored. A warning is printed, however, unless an optional
365 second argument <code>false</code> is used.<br/>
366 Strings beginning with a non-alphanumeric character, like # or !,
367 are assumed to be comments and are not processed at all. For
368 <code>bool</code> values, the following notation may be used
369 interchangeably: <code>true = on = yes = ok = 1</code>, while everything
370 else gives <code>false</code> (including but not limited to
371 <code>false</code>, <code>off</code>, <code>no</code> and 0).
374 Particle data often comes in sets of closely related information.
375 Therefore some properties expect the value to consist of several
376 numbers. These can then be separated by blanks (or by commas).
377 A simple example is <code>names</code>, which expects both the
378 name and antiname to be given. A more interesting one is the
379 <code>all</code> property,
381 id:all = name antiName spinType chargeType colType m0 mWidth mMin mMax tau0
383 where all the current information on the particle itself is replaced,
384 but any decay channels are kept unchanged. Using <code>new</code> instead
385 of <code>all</code> also removes any previous decay channels.
386 If the string contains fewer fields than expected the trailing
387 properties are set to vanish ("void", 0 or 0.). Note that such a
388 truncated string should not be followed by a comment, since this
389 comment would then be read in as if it contained the missing properties.
390 The truncation can be done anywhere, specifically a string with only
391 <code>id:new</code> defines a new "empty" particle.
392 As before, <code>isResonance</code>, <code>mayDecay</code>,
393 <code>doExternalDecay</code>, <code>isVisible</code> and
394 <code>doForceWidth</code>are (re)set to their default values, and
395 would have to be changed separately if required.
398 A further command is <code>rescaleBR</code>, which rescales each of the
399 existing branching ratios with a common factor, such that their new
400 sum is the provided value. This may be a first step towards adding
401 new decay channels, see further below.
404 Alternatively the <code>id</code> code may be followed by another integer,
405 which then gives the decay channel number. This then has to be
406 followed by the property specific to this channel, either
407 <code>onMode</code>, <code>bRatio</code>, <code>meMode</code> or
408 <code>products</code>. In the latter case all the products of the channel
411 id:channel:products = product1 product2 ....
413 The line will be scanned until the end of the line, or until a
414 non-number word is encountered, or until the maximum allowed number
415 of eight products is encountered, whichever happens first. It is also
416 possible to replace all the properties of a channel in a similar way:
418 id:channel:all = onMode bRatio meMode product1 product2 ....
420 To add a new channel at the end, use
422 id:addChannel = onMode bRatio meMode product1 product2 ....
426 It is currently not possible to remove a channel selectively, but
427 setting its branching ratio vanishing is as effective. If you want to
428 remove all existing channels and force decays into one new channel
431 id:oneChannel = onMode bRatio meMode product1 product2 ....
433 A first <code>oneChannel</code> command could be followed by
434 several subsequent <code>addChannel</code> ones, to build
435 up a completely new decay table for an existing particle.
438 When adding new channels or changing branching ratios in general,
439 note that, once a particle is to be decayed, the sum of branching
440 ratios is always rescaled to unity. Beforehand, <code>rescaleBR</code>
441 may be used to rescale an existing branching ratio by the given factor.
444 There are a few commands that will study all the decay channels of the
445 given particle, to switch them on or off as desired. The
449 will set the <code>onMode</code> property of all channels to the
452 id:offIfAny = product1 product2 ....
453 id:onIfAny = product1 product2 ....
454 id:onPosIfAny = product1 product2 ....
455 id:onNegIfAny = product1 product2 ....
457 will set the <code>onMode</code> 0, 1, 2 or 3, respectively, for all
458 channels which contain any of the enumerated products, where the matching
459 to these products is done without distinction of particles and
460 antiparticles. Note that "<code>Pos</code>" and "<code>Neg</code>"
461 are slightly misleading since it refers to the particle and antiparticle
462 of the <code>id</code> species rather than charge, but should still be
463 simpler to remember and understand than alternative notations.
466 id:offIfAll = product1 product2 ....
467 id:onIfAll = product1 product2 ....
468 id:onPosIfAll = product1 product2 ....
469 id:onNegIfAll = product1 product2 ....
471 will set the <code>onMode</code> 0, 1, 2 or 3, respectively, for all
472 channels which contain all of the enumerated products, again without
473 distinction of particles and antiparticles. If the same product appears
474 twice in the list it must also appear twice in the decay channel, and
475 so on. The decay channel is allowed to contain further particles,
476 beyond the product list. By contrast,
478 id:offIfMatch = product1 product2 ....
479 id:onIfMatch = product1 product2 ....
480 id:onPosIfMatch = product1 product2 ....
481 id:onPosIfMatch = product1 product2 ....
483 requires the decay-channel multiplicity to agree with that of the product
484 list, but otherwise works as the <code>onIfAll/offIfAll</code> methods.
487 Note that the action of several of the commands depends on the order
488 in which they are executed, as one would logically expect. For instance,
489 <code>id:oneChannel</code> removes all decay channels of <code>id</code>
490 and thus all previous changes in this decay table, while subsequent
491 additions or changes would still take effect. Another example would be that
492 <code>23:onMode = off</code> followed by <code>23:onIfAny = 1 2 3 4 5</code>
493 would let the <ei>Z^0</ei> decay to quarks, while no decays would be
494 allowed if the order were to be reversed.
497 b) The <code>Pythia</code> <code>readString(string)</code> method actually
498 does not do changes itself, but sends on the string either to the
499 <code>ParticleData</code> class or to the <code>Settings</code> one.
500 If desired, it is possible to communicate directly with the corresponding
501 <code>ParticleData</code> method:
503 pythia.particleData.readString("111:mayDecay = off");
504 pythia.particleData.readString("15:2:products = 16 -211");
506 In this case, changes intended for <code>Settings</code> would not be
510 c) Underlying this are commands for all the individual properties in
511 the <code>ParticleDataTable</code> class, one for each. Thus, an example
514 pythia.particleData.mayDecay(111, false);
516 Boolean values should here be given as <code>true</code> or
520 d) A simpler and more useful way is to collect all your changes
521 in a separate file, with one line per change, e.g.
525 The file can be read by the
527 pythia.readFile(fileName);
529 method, where <code>fileName</code> is a string, e.g.
530 <code>pythia.readFile("main.cmnd")</code>. Each line is process as
531 described for the string in 2a). This file can freely mix commands to
532 the <code>Settings</code> and <code>ParticleData</code> classes.
536 A routine <code>reInit(fileName)</code> is provided, and can be used to
537 zero the particle data table and reinitialize from scratch. Such a call
538 might be required if several <code>Pythia</code> objects are created in the
539 same run, and requested to have different values - by default the
540 <code>init()</code> call is only made the first time. Several
541 <code>pythia</code> with different values would have to run sequentially
542 and not in parallel, though; recall that there is only one instance of
543 the particle data table.
547 You may at any time obtain a listing of all the particle data by calling
549 pythia.particleData.listAll();
551 The listing is by increasing <code>id</code> number. It shows the basic
552 quantities introduced above. Some are abbreviated in the header to fit on
553 the lines: <code>spn = spinType</code>, <code>chg = chargeType</code>,
554 <code>col = colType</code>, <code>res = isResonance</code>,
555 <code>dec = mayDecay && canDecay</code> (the latter checks that decay
556 channels have been defined), <code>ext = doExternalDecay</code>,
557 <code>vis = isVisible</code> and <code>wid = doForceWidth</code>.<br/>
559 To list only those particles that were changed (one way or another, the
560 listing will not tell what property or decay channel was changed), instead use
562 pythia.particleData.listChanged();
564 (This info is based on a further <code>hasChanged</code> flag of a particle
565 or a channel, set <code>true</code> whenever any of the changing methods are
566 used. It is possible to manipulate this value, but this is not recommended.)
567 By default the internal initialization of the widths of resonances such as
568 <ei>gamma^*/Z^0, W^+-, t/tbar, H^0</ei> do not count as changes; if you want
569 to list also those changes instead call <code>listChanged(true)</code>.
572 To list only one particle, give its <code>id</code> code as argument to
573 the <code>list(...)</code> function.. To list a restricted set of particles,
574 give in their <code>id</code> codes to <code>list(...)</code> as a
575 <code>vector<int></code>.
579 For wholesale changes of particle properties all available data can be
580 written out, edited, and then read back in again. These methods are
581 mainly intended for expert users. You can choose between two alternative
585 a) XML syntax, using the <code><particle</code> and
586 <code><channel</code> lines already described. You use the method
587 <code>particleData.listXML(fileName)</code> to produce such an XML
588 file and <code>particleData.readXML(fileName)</code> to read it back
592 b) Fixed/free format, using exactly the same information as illustrated
593 for the <code><particle</code> and <code><channel</code> lines
594 above, but now without any tags. This means that all information fields
595 must be provided (if there is no antiparticle then write
596 <code>void</code>), in the correct order (while the order is irrelevant
597 with XML syntax), and all on one line. Information is written out in
598 properly lined-up columns, but the reading is done using free format,
599 so fields need only be separated by at least one blank. Each new particle
600 is supposed to be separated by (at least) one blank line, whereas no
601 blank lines are allowed between the particle line and the subsequent
602 decay channel lines, if any. You use the method
603 <code>particleData.listFF(fileName)</code> to produce such a fixed/free
604 file and <code>particleData.readFF(fileName)</code> to read it back
608 As an alternative to the <code>readXML</code> and <code>readFF</code>
609 methods you can also use the
610 <code>particleData.reInit(fileName, xmlFormat)</code> method, where
611 <code>xmlFormat = true</code> (default) corresponds to reading an XML
612 file and <code>xmlFormat = false</code> to a fixed/free format one.
615 To check that the new particle and decay tables makes sense, you can use
616 the <code>particleData.checkTable()</code> method, either directly or by
617 switching it on among the standard
618 <aloc href="ErrorChecks">error checks</aloc>.
625 <!-- Copyright (C) 2008 Torbjorn Sjostrand -->