using option '-treename HLTesdTree' for EsdCollector, adding default parameter for...
[u/mrichter/AliRoot.git] / PYTHIA8 / pythia8130 / xmldoc / EventRecord.xml
1 <chapter name="The Event Record">
2
3 <h2>The Event Record</h2>
4
5 The <code>Event</code> class for event records basically is a vector of 
6 <code>Particle</code>s, so that it can expand to fit the event size.
7 The index operator is overloaded, so that <code>event[i]</code> 
8 corresponds to the <code>i</code>'th particle of an <code>Event</code> 
9 object <code>event</code>. Thus <code>event[i].id()</code> returns the 
10 identity of the <code>i</code>'th particle. References to the first, 
11 <code>i</code>'th and last particle are obtained with 
12 <code>event.front()</code>, <code>event.at(i)</code> and 
13 <code>event.back()</code>, respectively.
14
15 <p/>
16 The event size can be found with <code>size()</code>, i.e. valid 
17 particles are stored in <code>0 &lt;= i &lt; event.size()</code>.
18
19 <p/>
20 Line 0 is used to represent the event as a whole, with its total
21 four-momentum and invariant mass, but does not form part of the
22 event history. Lines 1 and 2 contains the two incoming beams, and 
23 only from here on history tracing works as could be expected. That 
24 way unassigned mother and daughter indices can be put 0 without 
25 ambiguity. Depending on the task at hand, a loop may therefore start 
26 at an index 1 without any loss. Specifically, for translation to other 
27 event record formats such as HepMC <ref>Dob01</ref>, where the first 
28 index is 1, the Pythia entry 0 definitely ought to be skipped in order 
29 to minimize the danger of errors. 
30
31 <p/>
32 New particles can be added to the end of the current event record
33 with <code>append(Particle)</code>, or 
34 <code>append(id, status, mother1, mother2, daughter1, daughter2, 
35 col, acol, p, m, scale)</code>
36 where <code>p</code> is the four-momentum vector, and everything except 
37 <code>id</code> defaults to 0. The <code>append</code> method returns 
38 the index of the new particle position. 
39   
40 <p/>
41 The existing particle at index <code>iCopy</code> can be copied to the end 
42 with <code>copy(iCopy, newStatus = 0)</code>. By default, i.e. with 
43 <code>newStatus = 0</code>, everything is copied precisely as it is, 
44 which means that history information has to be modified further by hand 
45 to make sense. With a positive <code>newStatus</code>, the new copy is set 
46 up to be the daughter of the old, with status code <code>newStatus</code>, 
47 and the status code of <code>iCopy</code> is negated. With a negative 
48 <code>newStatus</code>, the new copy is instead set up to be the mother 
49 of <code>iCopy</code>.
50
51 <p/>
52 The event record can be emptied for the next event by a 
53 <code>clear()</code>. The last <code>n</code> entries can be removed by 
54 <code>popBack(n)</code>, where <code>n = 1</code> by default. 
55 The <code>=</code> operator is overloaded to allow a copying of 
56 an event record, and <code>+=</code> to append an event to an 
57 existing one. In the latter case mother, daughter and colour tags are
58 shifted to make a consistent record. The zeroth particle of the 
59 appended event is not copied, but the zeroth particle of the combined
60 event is updated to the full energy-momentum content.
61
62 <p/>
63 A listing of the whole event is obtained with <code>list()</code>.
64 The basic id, status, mother, daughter, colour, four-momentum
65 and mass data are always given, but the method can also be called with 
66 a few optional arguments for further information:
67 <method name="list(showScaleAndVertex, showMothersAndDaughters, os)">
68 where
69 <argument name="showScaleAndVertex" default="false"> optionally give a 
70 second line for each particle, with the production scale (in GeV), the
71 production vertex (in mm or mm/c) and the invariant lifetime
72 (also in mm/c).
73 </argument>
74 <argument name="showMothersAndDaughters" default="false">
75 gives a list of all daughters and mothers of a particle, as defined by 
76 the <code>motherList(i)</code> and <code>daughterList(i)</code> methods 
77 described below. It is mainly intended for debug purposes. 
78 </argument>
79 <argument name="os" default="cout"> a reference to the <code>ostream</code>
80 object to which the event listing will be directed.
81 </argument>
82 </method>
83
84 <p/>
85 Each particle in the event record has a pointer to the corresponding
86 particle species in the particle database, used to find some particle
87 properties. This pointer is automatically set whenever the particle
88 identity is set by one of the normal methods. Of course its value is 
89 specific to the memory location of the current run, and so it has no
90 sense to save it if events are written to file. Should you use some
91 persistency scheme that bypasses the normal methods when the event is 
92 read back in, you can use <code>restorePtrs()</code> afterwards to set 
93 these pointers appropriately.
94
95 <p/>
96 The user would normally be concerned with the <code>Event</code> object 
97 that is a public member <code>event</code> of the <code>Pythia</code> class. 
98 Thus, having declared a <code>Pythia</code> object <code>pythia</code>, 
99 <code>pythia.event[i].id()</code> would be used to return the identity 
100 of the <code>i</code>'th particle, and <code>pythia.event.size()</code> to 
101 give the size of the event record. 
102
103 <p/>
104 A <code>Pythia</code> object contains a second event record for the 
105 hard process alone, called <code>process</code>, used as input for the 
106 generation of the complete event. Thus one may e.g. call either 
107 <code>pythia.process.list()</code> or <code>pythia.event.list()</code>. 
108 To distinguish those two rapidly at visual inspection, the 
109 <code>"Pythia Event Listing"</code> header is printed out differently, 
110 in one case adding <code>"(hard process)"</code> and in the other 
111 <code>"(complete event)"</code>. When <code>+=</code> is used to 
112 append an event, the modified event is printed with 
113 <code>"(combination of several events)"</code> as a reminder.
114
115 <p/>
116 One data member in an <code>Event</code> object is used to keep track of the  
117 largest <code>col()</code> or <code>acol()</code> tag set so far, so that 
118 new ones do not clash. The <code>lastcolTag()</code> method returns the 
119 last tag assigned, i.e. largest value in the current event, and 
120 <code>nextColTag()</code> ups it by one before returing the value. The 
121 latter method thus is used when a new colour tag is needed.  
122
123 <modeopen name="Event:startColTag" default="100" min="0" max="1000">
124 This sets the initial value used, so that the first one assigned is
125 <code>startColTag+1</code>, etc. The Les Houches accord <ref>Boo01</ref> 
126 suggests this number to be 500, but 100 works equally well.
127 </modeopen>
128
129 <p/>
130 The <code>scale()</code> methods can be used to set or get the scale 
131 (in GeV) of the event as a whole. Further methods for event properties 
132 may be added in the future.
133
134 <p/>
135 A few methods exist to rotate and boost events. These derive from the
136 <aloc href="FourVectors">Vec4</aloc> methods, and affect both the 
137 momentum and the vertex (position) components of all particles. 
138
139 <method name="rot(theta, phi)"> 
140 rotate by this polar and azimuthal angle (expressed in radians). 
141 </method>
142
143 <method name="bst(betaX, betaY, betaZ)"> 
144 boost by this vector. Optionally you may provide the <ei>gamma</ei> 
145 value as a fourth argument, if you deem this may help avoid roundoff 
146 errors for big boosts. You may alternatively supply a <code>Vec4</code> 
147 four-vector, in which case the boost vector <ei>beta = p/E</ei>.
148 </method>
149
150 <method name="rotbst(M)"> 
151 rotate and boost by the combined action encoded in the 
152 <aloc href="FourVectors"><code>RotBstMatrix</code></aloc> <code>M</code>.
153 </method>
154
155 <p/>
156 There are also a few methods with an individual particle index 
157 <code>i</code> as input, but requiring some search operations in 
158 the event record, and therefore not possible to define inside the 
159 <code>Particle</code> class:
160
161 <method name="motherList(i)"> 
162 returns a <code>vector&lt;int></code> containing a list of all the
163 mothers of a particle. This list is empty for entries 0, 1 and 2,
164 i.e. the "system" in line 0 is not counted as part of the history. 
165 Normally the list contains one or two mothers, but it can also be more, 
166 e.g. in string fragmentation the whole fragmenting system is counted 
167 as mothers to the primary hadrons. Mothers are listed in ascending order.
168 </method>
169
170 <method name="daughterList(i)">
171 returns a <code>vector&lt;int></code> containing a list of all the
172 daughters of a particle. This list is empty for a particle that did 
173 not decay (or, if the evolution is stopped early enough, a parton
174 that did not branch), while otherwise it can contain a list of 
175 varying length, from one to many. Many partons may have the same 
176 <code>daughterList</code>, e.g. in the hard process and fragmentation 
177 steps. For the two incoming beam particles, all shower initiators and
178 beam remnants are counted as daughters, with the one in slot 0 being
179 the one leading up to the hardest interaction. The "system" in line 0
180 does not have any daughters, i.e. is not counted as part of the history. 
181 </method>
182
183 <method name="iTopCopy(i), iBotCopy(i)"> 
184 are used to trace carbon copies of the particle at index <code>i</code> up 
185 to its top mother or down to its bottom daughter. If there are no such 
186 carbon copies, <code>i</code> itself will be returned.
187 </method>
188
189 <method name="iTopCopyId(i), iBotCopyId(i)"> 
190 also trace top mother and bottom daughter, but do not require carbon 
191 copies, only that one can find an unbroken chain, of mothers or daughters, 
192 with the same flavour <code>id</code> code. When it encounters ambiguities,
193 say a <ei>g -> g g</ei> branching or a <ei>u u -> u u</ei> hard scattering,
194 it will stop the tracing and return the current position. It can be confused
195 by nontrivial flavour changes, e.g. a hard process <ei>u d -> d u</ei>  
196 by <ei>W^+-</ei> exchange will give the wrong answer. These methods
197 therefore are of limited use for common particles, in particular for the
198 gluon, but should work well for "rare" particles. 
199 </method>
200
201 <method name="sisterList(i)"> 
202 returns a <code>vector&lt;int></code> containing a list of all the 
203 sisters of a particle, i.e. all the daughters of the first mother,
204 except the particle itself. 
205 </method>
206
207 <method name="sisterListTopBot(i)">
208 returns a <code>vector&lt;int></code> containing a list of all the 
209 sisters of a particle, tracking up and back down through carbon copies 
210 if required. That is, the particle is first traced up with 
211 <code>iTopCopy()</code> before its mother is found, and then all 
212 the particles in the <code>daughterList()</code> of this mother are 
213 traced down with <code>iBotCopy()</code>, omitting the original 
214 particle itself. Any non-final particles are removed from the list.
215 Should this make the list empty the search criterion is widened so that
216 all final daughters are allowed, not only carbon-copy ones. A second
217 argument <code>false</code> inhibits the second step, and increases 
218 the risk that an empty list is returned. A typical example of this
219 is for ISR cascades, e.g. <ei>e -> e gamma</ei> where the photon 
220 may not have any obvious sister in the final state if the bottom copy 
221 of the photon is an electron that annihilates and thus is not part of 
222 the final state.  
223 </method>
224
225 <method name="isAncestor(i, iAncestor)"> 
226 traces the particle <code>i</code> upwards through mother, grandmother, 
227 and so on, until either <code>iAncestor</code> is found or the top of 
228 the record is reached. Normally one unique mother is required,
229 as is the case e.g. in decay chains or in parton showers, so that
230 e.g. the tracing through a hard scattering would not work. For
231 hadronization, first-rank hadrons are identified with the respective 
232 string endpoint quark, which may be useful e.g. for <ei>b</ei> physics, 
233 while higher-rank hadrons give <code>false</code>. Currently also 
234 ministrings that collapsed to one single hadron and junction topologies 
235 give <code>false</code>.  
236 </method>
237  
238 <h3>The Junction Class</h3>
239
240 The event record also contains a vector of junctions, which often
241 is empty or else contains only a very few per event. Methods are
242 available to add further junctions or query the current junction list.
243 This is only for the expert user, however, and is not discussed
244 further here, but only the main points.  
245
246 <p/>
247 A junction stores the properites associated with a baryon number that
248 is fully resolved, i.e. where three different colour indices are 
249 involved. There are two main applications,
250 <ol> 
251 <li>baryon beams, where at least two valence quarks are kicked out,
252 and so the motion of the baryon number is notrivial;</li>
253 <li>baryon-number violating processes, e.g. in SUSY with broken
254 <ei>R</ei>-parity.</li>
255 </ol>
256 Information on junctions is set, partly in the process generation,
257 partly in the beam remnants machinery, and used by the fragmentation 
258 routines, but the normal user does not have to know the details. 
259
260 <p/>
261 For each junction, information is stored on the kind of junction, and 
262 on the three (anti)colour indices that are involved in the junction.
263 The possibilities foreseen are:
264 <ul>
265 <li><code>kind = 1</code> : incoming colourless particle to three 
266 outgoing colours (e.g. baryon beam remnant or 
267 <ei>neutralino -> q q q</ei>);</li>
268 <li><code>kind = 2</code> : incoming colourless particle to three 
269 outgoing anticolours;</li>
270 <li><code>kind = 3</code> : one incoming anticolor (stored first) 
271 and two outgoing  colours (e.g. antisquark decaying to quark);</li>
272 <li><code>kind = 4</code> : one incoming color (stored first) and two 
273 outgoing anticolours;</li>
274 <li><code>kind = 5</code> : incoming colour octet to three colours, 
275 where the incoming colour passes through unchanged and so need not 
276 be bokkept here, while the incoming anticolor (stored first) and the 
277 two outgoing colours are (e.g. gluino decay to three quarks);</li>
278 <li><code>kind = 6</code> : incoming colour octet to three anticolours, 
279 where the incoming anticolour passes through unchanged and so need not 
280 be bookkept here, while the incoming color (stored first) and the two 
281 outgoing colours are.</li>
282 </ul>
283 The odd (even) <code>kind</code> codes corresponds to a +1 (-1) change in 
284 baryon number across the junction.
285 <note>Warning:</note> Currently only <code>kind = 1, 2</code> are 
286 implemented.
287
288 <p/>
289 The kind and colour information in the list of junctions can be set 
290 or read with methods of the <code>Event</code> class, but are not of 
291 common interest and so not described here.
292
293 <p/>
294 A listing of current junctions can be obtained with the 
295 <code>listJunctions()</code> method.
296  
297 <h3>Subsystems</h3>
298
299 The event record also contains a few vectors where parton indices can be 
300 stored, classified by subsystem. Such information is needed to interleave
301 multiple interactions, initial-state showers, final-state showers 
302 and beam remnants. It could also be used in other places. It is intended
303 to be accessed only by experts, such as implementors of 
304 <aloc href="ImplementNewShowers">new showering models</aloc>.
305
306 <p/>
307 A listing of current subsystems can be obtained with the 
308 <code>listSystems()</code> method.
309
310 </chapter>
311
312 <!-- Copyright (C) 2008 Torbjorn Sjostrand -->