1 <chapter name="The Event Record">
3 <h2>The Event Record</h2>
5 A <code>Pythia</code> instance contains two members of the
6 <code>Event</code> class. The one called <code>process</code> provides
7 a brief summary of the main steps of the hard process, while the
8 one called <code>event</code> contains the full history. The
9 user would normally interact mainly with the second one, so
10 we will examplify primarily with that one.
13 The <code>Event</code> class to first approximation is a vector of
14 <code>Particle</code>s, so that it can expand to fit the current
15 event size. The index operator is overloaded, so that e.g.
16 <code>event[i]</code> corresponds to the <ei>i</ei>'th particle
17 of the object <code>event</code>. Thus <code>event[i].id()</code>
18 returns the identity of the <ei>i</ei>'th particle, and so on.
19 Therefore the methods of the
20 <code><aloc href="ParticleProperties">Particle</aloc></code> class
21 are at least as essential as those of the <code>Event</code> class
25 As used inside PYTHIA, some conventions are imposed on the structure
26 of the event record. Entry 0 of the <code>vector<Particle></code>
27 is used to represent the event as a whole, with its total four-momentum
28 and invariant mass, but does not form part of the event history.
29 Lines 1 and 2 contains the two incoming beams, and only from here on
30 history tracing works as could be expected. That way unassigned mother
31 and daughter indices can be put 0 without ambiguity. Depending on the
32 task at hand, a loop may therefore start at index 1 rather than 0
33 without any loss. Specifically, for translation to other event record
34 formats such as HepMC <ref>Dob01</ref>, where the first index is 1, the
35 Pythia entry 0 definitely ought to be skipped in order to minimize the
36 danger of indexing errors.
39 In the following we will list the methods available.
40 Only a few of them have a function to fill in normal user code.
42 <h3>Basic output methods</h3>
44 Some methods are available to read out information on the
47 <method name="Particle& Event::operator[](int i)">
49 <methodmore name="const Particle& Event::operator[](int i)">
50 returns a (<code>const</code>) reference to the <ei>i</ei>'th particle
51 in the event record, which can be used to get (or set) all the
52 <aloc href="ParticleProperties">properties</aloc> of this particle.
55 <method name="int Event::size()">
56 The event size, i.e. the sie of the <code>vector<Particle></code>.
57 Thus valid particles, to be accessed by the above indexing operator,
58 are stored in the range <ei>0 <= i < size()</ei>. See comment
59 above about the (ir)relevance of entry 0.
62 <method name="void Event::list()">
64 <methodmore name="void Event::list(ostream& os)">
66 <methodmore name="void Event::list(bool showScaleAndVertex,
67 bool showMothersAndDaughters = false)">
69 <methodmore name="void Event::list(bool showScaleAndVertex,
70 bool showMothersAndDaughters, ostream& os)">
71 Provide a listing of the whole event, i.e. of the
72 <code>vector<Particle></code>. The methods with fewer arguments
73 call the final one with the respective default values, and are
74 non-inlined so they can be used in a debugger. The basic identity
75 code, status, mother, daughter, colour, four-momentum and mass data
76 are always given, but the methods can also be called with a few
77 optional arguments for further information:
78 <argument name="showScaleAndVertex" default="false"> optionally give a
79 second line for each particle, with the production scale (in GeV), the
80 production vertex (in mm or mm/c) and the invariant lifetime
83 <argument name="showMothersAndDaughters" default="false">
84 gives a list of all daughters and mothers of a particle, as defined by
85 the <code>motherList(i)</code> and <code>daughterList(i)</code> methods
86 described below. It is mainly intended for debug purposes.
88 <argument name="os" default="cout"> a reference to the <code>ostream</code>
89 object to which the event listing will be directed.
95 Each <code>Particle</code> has two mother and two daughter indices.
96 These may be used to encode zero, one, two or more mothers/daughters,
97 depending on the combination of values and status code, according to
98 well-defined <aloc href="ParticleProperties">rules</aloc>. The
99 two methods below can do this job easier for you.
101 <method name="vector<int> Event::motherList(int i)">
102 returns a vector of all the mother indices of the particle at index
103 <ei>i</ei>. This list is empty for entries 0, 1 and 2,
104 i.e. the "system" in line 0 is not counted as part of the history.
105 Normally the list contains one or two mothers, but it can also be more,
106 e.g. in string fragmentation the whole fragmenting system is counted
107 as mothers to the primary hadrons. Many particles may have the same
108 <code>motherList</code>. Mothers are listed in ascending order.
111 <method name="vector<int> Event::daughterList(int i)">
112 returns a vector of all the daughter indices of the particle at index
113 <ei>i</ei>. This list is empty for a particle that did
114 not decay (or, if the evolution is stopped early enough, a parton
115 that did not branch), while otherwise it can contain a list of
116 varying length, from one to many. For the two incoming beam particles,
117 all shower initiators and beam remnants are counted as daughters,
118 with the one in slot 0 being the one leading up to the hardest
119 interaction. The "system" in line 0 does not have any daughters,
120 i.e. is not counted as part of the history. Many partons may have the
121 same <code>daughterList</code>. Daughters are listed in ascending order.
124 <method name="int Event::statusHepMC(int i)">
125 returns the status code according to the HepMC conventions agreed in
126 February 2009. This convention does not preserve the full information
127 provided by the internal PYTHIA status code, as obtained by
128 <code>Particle::status()</code>, but comes reasonably close.
129 The allowed output values are:
131 <li>0 : an empty entry, with no meaningful information and therefore
132 to be skipped unconditionally (should not occur in PYTHIA);</li>
133 <li>1 : a final-state particle, i.e. a particle that is not decayed
134 further by the generator (may also include unstable particles that
135 are to be decayed later, as part of the detector simulation);</li>
136 <li>2 : a decayed Standard Model hadron or tau or mu lepton, excepting
137 virtual intermediate states thereof (i.e. the particle must undergo
138 a normal decay, not e.g. a shower branching);</li>
139 <li>3 : a documentation entry (not used in PYTHIA);</li>
140 <li>4 : an incoming beam particle;</li>
141 <li>11 - 200 : an intermediate (decayed/branched/...) particle that does
142 not fulfill the criteria of status code 2, with a generator-dependent
143 classification of its nature; in PYTHIA the absolute value of the normal
144 status code is used.</li>
149 <h3>Further output methods</h3>
151 The above methods are the main ones that a normal user would make
152 frequent use of. There are some further methods that also could come
153 in handy, in the exploration of the history of an event, but where
154 the outcome is not always obvious if one is not familiar with the
155 detailed structure of an event record.
157 <method name="int Event::iTopCopy(int i)">
159 <methodmore name="int Event::iBotCopy(int i)">
160 are used to trace carbon copies of the particle at index <ei>i</ei> up
161 to its top mother or down to its bottom daughter. If there are no such
162 carbon copies, <ei>i</ei> itself will be returned. A carbon copy is
163 when the "same" particle appears several times in the event record, but
164 with changed momentum owing to recoil effects.
167 <method name="int Event::iTopCopyId(int i)">
169 <methodmore name="int Event::iBotCopyId(int i)">
170 also trace top mother and bottom daughter, but do not require carbon
171 copies, only that one can find an unbroken chain, of mothers or daughters,
172 with the same flavour <code>id</code> code. When it encounters ambiguities,
173 say a <ei>g -> g g</ei> branching or a <ei>u u -> u u</ei> hard scattering,
174 it will stop the tracing and return the current position. It can be confused
175 by nontrivial flavour changes, e.g. a hard process <ei>u d -> d u</ei>
176 by <ei>W^+-</ei> exchange will give the wrong answer. These methods
177 therefore are of limited use for common particles, in particular for the
178 gluon, but should work well for "rare" particles.
181 <method name="vector<int> Event::sisterList(int i)">
182 returns a vector of all the sister indices of the particle at index
183 <ei>i</ei>, i.e. all the daughters of the first mother, except the
187 <method name="vector<int> Event::sisterListTopBot(int i,
188 bool widenSearch = true)">
189 returns a vector of all the sister indices of the particle at index
190 <ei>i</ei>, tracking up and back down through carbon copies
191 if required. That is, the particle is first traced up with
192 <code>iTopCopy()</code> before its mother is found, and then all
193 the particles in the <code>daughterList()</code> of this mother are
194 traced down with <code>iBotCopy()</code>, omitting the original
195 particle itself. Any non-final particles are removed from the list.
196 Should this make the list empty the search criterion is widened so that
197 all final daughters are allowed, not only carbon-copy ones. A second
198 argument <code>false</code> inhibits the second step, and increases
199 the risk that an empty list is returned. A typical example of this
200 is for ISR cascades, e.g. <ei>e -> e gamma</ei> where the photon
201 may not have any obvious sister in the final state if the bottom copy
202 of the photon is an electron that annihilates and thus is not part of
206 <method name="bool Event::isAncestor(int i, int iAncestor)">
207 traces the particle <ei>i</ei> upwards through mother, grandmother,
208 and so on, until either <ei>iAncestor</ei> is found or the top of
209 the record is reached. Normally one unique mother is required,
210 as is the case e.g. in decay chains or in parton showers, so that
211 e.g. the tracing through a hard scattering would not work. For
212 hadronization, first-rank hadrons are identified with the respective
213 string endpoint quark, which may be useful e.g. for <ei>b</ei> physics,
214 while higher-rank hadrons give <code>false</code>. Currently also
215 ministrings that collapsed to one single hadron and junction topologies
216 give <code>false</code>.
220 One data member in an <code>Event</code> object is used to keep track
221 of the largest <code>col()</code> or <code>acol()</code> colour tag set
222 so far, so that new ones do not clash.
224 <modeopen name="Event:startColTag" default="100" min="0" max="1000">
225 This sets the initial colour tag value used, so that the first one
226 assigned is <code>startColTag + 1</code>, etc. The Les Houches accord
227 <ref>Boo01</ref> suggests this number to be 500, but 100 works equally
231 <method name="void Event::initColTag(int colTag = 0)">
232 forces the current colour tag value to be the larger of the input
233 <code>colTag</code> and the above <code>Event:startColTag</code>
237 <method name="int Event::lastColTag()">
238 returns the current maximum colour tag.
241 <method name="int Event::nextColTag()">
242 increases the current maximum colour tag by one and returns this
243 new value. This method is used whenever a new colour tag is needed.
247 Many event properties are accessible via the <code>Info</code> class,
248 <aloc href="EventInformation">see here</aloc>. Since they are used
249 directly in the event generation, a few are stored directly in the
250 <code>Event</code> class, however.
252 <method name="void Event::scale( double scaleIn)">
254 <methodmore name="double Event::scale()">
255 set or get the scale (in GeV) of the hardest process in the event.
256 Matches the function of the <code>scale</code> variable in the
257 <aloc href="LesHouchesAccord">Les Houches Accord</aloc>.
260 <method name="void Event::scaleSecond( double scaleSecondIn)">
262 <methodmore name="double Event::scaleSecond()">
263 set or get the scale (in GeV) of a second hard process in the event,
264 in those cases where such a one
265 <aloc href="SecondHardProcess">has been requested</aloc>.
268 <h3>Constructors and modifications of the event record</h3>
270 Although you would not normally need to create your own
271 <code>Event</code> instance, there may be times where that
272 could be convenient. The typical exampel would be if you want to
273 create a new event record that is the sum of a few different ones,
274 e.g. if you want to simulate pileup events. There may also be cases
275 where you want to add one or a few particles to an existing event
278 <method name="Event::Event(int capacity = 100)">
279 creates an empty event record, but with a reserved size
280 <ei>capacity</ei> for the <code>Particle</code> vector.
283 <method name="Event& Event::operator=(const Event& oldEvent)">
284 copies the input event record.
287 <method name="Event& Event::operator+=(const Event& addEvent)">
288 appends an event to an existing one. For the appended particles
289 mother, daughter and colour tags are shifted to make a consistent
290 record. The zeroth particle of the appended event is not copied,
291 but the zeroth particle of the combined event is updated to the
292 full energy-momentum content.
295 <method name="void Event::init(string headerIn = "",
296 ParticleData* particleDataPtrIn = 0, int startColTagIn = 100)">
297 initializes colour, the pointer to the particle database, and the
298 header specification used for the event listing. We remind that a
299 <code>Pythia</code> object contains two event records
300 <code>process</code> and <code>event</code>. Thus one may e.g.
301 call either <code>pythia.process.list()</code> or
302 <code>pythia.event.list()</code>. To distinguish those two rapidly
303 at visual inspection, the <code>"Pythia Event Listing"</code> header
304 is printed out differently, in one case adding
305 <code>"(hard process)"</code> and in the other
306 <code>"(complete event)"</code>. When <code>+=</code> is used to
307 append an event, the modified event is printed with
308 <code>"(combination of several events)"</code> as a reminder.
311 <method name="void Event::clear()">
312 empties event record. Specifically the <code>Particle</code> vector
313 size is reset to zero.
316 <method name="void Event::reset()">
317 empties the event record, as <code>clear()</code> above, but then
318 fills the zero entry of the <code>Particle</code> vector with the
319 pseudoparticle used to represent the event as a whole. At this point
320 the pseudoparticle is not assigned any momentum or mass.
323 <method name="void Event::popBack(int n = 1)">
324 removes the last <ei>n</ei> particle entries; must be a positive
328 <method name="int Event::append(Particle entryIn)">
329 appends a particle to the bottom of the event record and
330 returns the index of this position.
333 <method name="int Event::append(int id, int status, int mother1,
334 int mother2, int daughter1, int daughter2, int col, int acol,
335 double px, double py, double pz, double e, double m = 0.,
337 appends a particle to the bottom of the event record and
338 returns the index of this position;
339 <aloc href="ParticleProperties">see here</aloc> for the meaning
340 of the various particle properties.
343 <method name="int Event::append(int id, int status, int mother1,
344 int mother2, int daughter1, int daughter2, int col, int acol,
345 Vec4 p, double m = 0., double scale = 0.)">
346 appends a particle to the bottom of the event record and
347 returns the index of this position, as above but with four-momentum
348 as a <code>Vec4</code>.
351 <method name="int Event::append(int id, int status, int col, int acol,
352 double px, double py, double pz, double e, double m = 0.)">
354 <methodmore name="int Event::append(int id, int status, int col,
355 int acol, Vec4 p, double m = 0.)">
356 appends a particle to the bottom of the event record and
357 returns the index of this position, as above but with vanishing
358 (i.e. zero) mother and daughter indices.
361 <method name="int Event::setPDTPtr(int iSet = -1)">
362 send in a pointer to the <code>ParticleData</code> database for
363 particle <code>iSet</iset>, by default the most recently appended
364 particle. Also generates a pointer to the
365 <code>ParticleDataEntry</code> object of the identity code
369 <method name="int Event::copy(int iCopy, int newStatus = 0)">
370 copies the existing particle in entry <code>iCopy</code> to the
371 bottom of the event record and returns the index of this position.
372 By default, i.e. with <code>newStatus = 0</code>, everything is
373 copied precisely as it is, which means that history information
374 has to be modified further by hand to make sense. With a positive
375 <code>newStatus</code>, the new copy is set up to be the daughter of
376 the old, with status code <code>newStatus</code>, while the status
377 code of <code>iCopy</code> is negated. With a negative
378 <code>newStatus</code>, the new copy is instead set up to be the
379 mother of <code>iCopy</code>.
382 <method name="Particle& Event::back()">
383 returns a reference to the last particle in the event record.
386 <method name="void Event::restorePtrs()">
387 each particle in the event record has a pointer to the whole database
388 and another to the particle species itself, used to find some particle
389 properties. The latter pointer is automatically set/changed whenever
390 the particle identity is set/changed by one of the normal methods.
391 (It is the "changed" part that prompts the inclusion of a pointer
392 to the whole database.) Of course the pointer values are specific to
393 the memory locations of the current run, and so it has no sense to
394 save them if events are written to file. Should you use some
395 persistency scheme that bypasses the normal methods when the event is
396 read back in, you can use <code>restorePtrs()</code> afterwards to set
397 these pointers appropriately.
401 A few methods exist to rotate and boost events. These derive from the
402 <aloc href="FourVectors">Vec4</aloc> methods, and affect both the
403 momentum and the vertex (position) components of all particles.
405 <method name="void Event::rot(double theta, double phi)">
406 rotate all particles in the event by this polar and azimuthal angle
407 (expressed in radians).
410 <method name="void Event::bst(double betaX, double betaY, double betaZ)">
412 <methodmore name="void Event::bst(double betaX, double betaY,
413 double betaZ, double gamma)">
415 <methodmore name="void Event::bst(const Vec4& vec)">
416 boost all particles in the event by this three-vector.
417 Optionally you may provide the <ei>gamma</ei> value as a fourth argument,
418 which may help avoid roundoff errors for big boosts. You may alternatively
419 supply a <code>Vec4</code> four-vector, in which case the boost vector
420 becomes <ei>beta = p/E</ei>.
423 <method name="void Event::rotbst(const RotBstMatrix& M)">
424 rotate and boost by the combined action encoded in the
425 <code><aloc href="FourVectors">RotBstMatrix</aloc> M</code>.
428 <h3>The Junction Class</h3>
430 The event record also contains a vector of junctions, which often
431 is empty or else contains only a very few per event. Methods are
432 available to add further junctions or query the current junction list.
433 This is only for the expert user, however, and is not discussed
434 further here, but only the main points.
437 A junction stores the properites associated with a baryon number that
438 is fully resolved, i.e. where three different colour indices are
439 involved. There are two main applications,
441 <li>baryon beams, where at least two valence quarks are kicked out,
442 and so the motion of the baryon number is notrivial;</li>
443 <li>baryon-number violating processes, e.g. in SUSY with broken
444 <ei>R</ei>-parity.</li>
446 Information on junctions is set, partly in the process generation,
447 partly in the beam remnants machinery, and used by the fragmentation
448 routines, but the normal user does not have to know the details.
451 For each junction, information is stored on the kind of junction, and
452 on the three (anti)colour indices that are involved in the junction.
453 The possibilities foreseen are:
455 <li><code>kind = 1</code> : incoming colourless particle to three
456 outgoing colours (e.g. baryon beam remnant or
457 <ei>neutralino -> q q q</ei>);</li>
458 <li><code>kind = 2</code> : incoming colourless particle to three
459 outgoing anticolours;</li>
460 <li><code>kind = 3</code> : one incoming anticolor (stored first)
461 and two outgoing colours (e.g. antisquark decaying to quark);</li>
462 <li><code>kind = 4</code> : one incoming color (stored first) and two
463 outgoing anticolours;</li>
464 <li><code>kind = 5</code> : incoming colour octet to three colours,
465 where the incoming colour passes through unchanged and so need not
466 be bokkept here, while the incoming anticolor (stored first) and the
467 two outgoing colours are (e.g. gluino decay to three quarks);</li>
468 <li><code>kind = 6</code> : incoming colour octet to three anticolours,
469 where the incoming anticolour passes through unchanged and so need not
470 be bookkept here, while the incoming color (stored first) and the two
471 outgoing colours are.</li>
473 The odd (even) <code>kind</code> codes corresponds to a +1 (-1) change in
474 baryon number across the junction.
475 <note>Warning:</note> Currently only <code>kind = 1, 2</code> are
479 The kind and colour information in the list of junctions can be set
480 or read with methods of the <code>Event</code> class, but are not of
481 common interest and so not described here.
484 A listing of current junctions can be obtained with the
485 <code>listJunctions()</code> method.
489 Separate from the event record as such, but closely tied to it is the
490 <code><aloc href="AdvancedUsage">PartonSystems</aloc></code> class,
491 which mainly stores the parton indices of incoming and outgoing partons,
492 classified by collision subsystem. Such information is needed to
493 interleave multiple interactions, initial-state showers and final-state
494 showers, and append beam remnants. It could also be used in other places.
495 It is intended to be accessed only by experts, such as implementors of
496 <aloc href="ImplementNewShowers">new showering models</aloc>.
500 <!-- Copyright (C) 2010 Torbjorn Sjostrand -->