]>
Commit | Line | Data |
---|---|---|
5ad4eb21 | 1 | <chapter name="Program Flow"> |
2 | ||
3 | <h2>Program Flow</h2> | |
4 | ||
5 | Recall that, to first order, the event generation process can be | |
6 | subdivided into three stages: | |
7 | <ol> | |
8 | <li>Initialization.</li> | |
9 | <li>The event loop.</li> | |
10 | <li>Finishing.</li> | |
11 | </ol> | |
12 | This is reflected in how the top-level <code>Pythia</code> class should | |
13 | be used in the user-supplied main program, further outlined in the | |
14 | following. Since the nature of the run is defined at the initialization | |
15 | stage, this is where most of the PYTHIA user code has to be written. | |
16 | So as not to confuse the reader unduly, the description of initialization | |
17 | options has been subdivided into what would normally be used and what is | |
18 | intended for more special applications. | |
19 | ||
20 | <h3>Initialization - normal usage</h3> | |
21 | ||
22 | <ol> | |
23 | ||
24 | <li> | |
25 | Already at the top of the main program file, you need to include the proper | |
26 | header file | |
27 | <pre> | |
28 | #include "Pythia.h" | |
29 | </pre> | |
30 | To simplify typing, it also makes sense to declare | |
31 | <pre> | |
32 | using namespace Pythia8; | |
33 | </pre> | |
34 | </li> | |
35 | ||
36 | <p/> | |
37 | <li> | |
38 | The first step is to create a generator object, | |
39 | e.g. with | |
40 | <pre> | |
41 | Pythia pythia; | |
42 | </pre> | |
43 | It is this object that we will use from now on. Normally a run | |
44 | will only contain one <code>Pythia</code> object. (Hypothetically | |
45 | you could use several <code>Pythia</code> objects sequentially, | |
46 | but if done in parallel the <code>static</code> character of some | |
47 | program elements is likely not to give the desired behaviour.)<br/> | |
48 | By default all output from <code>Pythia</code> will be on the | |
49 | <code>cout</code> stream, but the <code>list</code> methods below do | |
50 | allow output to alternative streams or files (by an optional | |
51 | last argument, a reference to an <code>ostream</code>, usually not | |
52 | explicitly written out here). | |
53 | </li> | |
54 | ||
55 | <p/> | |
56 | <li> | |
57 | You next want to set up the character of the run. | |
58 | The pages under the "Setup Run Tasks" heading in the index | |
59 | describe all the options available (with some very few exceptions, | |
60 | found on the other pages). | |
61 | The default values and your modifications are stored in two databases, | |
62 | one for <aloc href="SettingsScheme">generic settings</aloc> | |
63 | and one for <aloc href="ParticleDataScheme">particle data</aloc>. | |
64 | Both of these are static classes, and are | |
65 | initialized with their default values by the <code>Pythia</code> | |
66 | constructor. The default values can then be changed, primarily | |
67 | by one of the two ways below, or by a combination of them.<br/> | |
68 | ||
69 | <p/> | |
70 | a) You can use the dedicated methods of each class to change the | |
71 | database default values to fit the needs of your current run. However, | |
72 | the | |
73 | <pre> | |
74 | pythia.readString(string); | |
75 | </pre> | |
76 | method provides a covenient uniform interface to all of them. | |
77 | The information in the string is case-insensitive, but upper- and | |
78 | lowercase can be combined for clarity. The rules are that<br/> | |
79 | (i) if the first nonblank character of the string is a letter | |
80 | it is assumed to contain a setting, and is sent on to | |
81 | <code>pythia.settings.readString(string)</code>;<br/> | |
82 | (ii) if instead the string begins with a digit it is assumed to | |
83 | contain particle data updates, and so sent on to | |
84 | <code>pythia.particleData.readString(string)</code>;<br/> | |
85 | (iii) if none of the above, the string is assumed to be a comment, | |
86 | i.e. nothing will be done.<br/> | |
87 | In the former two cases, a warning is issued whenever a string | |
88 | cannot be recognized (maybe because of a spelling mistake), | |
89 | unless an optional second argument <code>false</code> is used to | |
90 | switch off warnings.<br/> | |
91 | Some examples would be | |
92 | <pre> | |
93 | pythia.readString("TimeShower:pTmin = 1.0"); | |
94 | pythia.readString("111:mayDecay = false"); | |
95 | </pre> | |
96 | The <code>readString(string)</code> method is intended primarily for | |
97 | a few changes. It can also be useful if you want to construct a | |
98 | parser of input files that contain commands to several different | |
99 | libraries.<br/> | |
100 | ||
101 | <p/> | |
102 | b) You can read in a file containing a list of those variables | |
103 | you want to see changed, with a | |
104 | <pre> | |
105 | pythia.readFile(fileName); | |
106 | </pre> | |
107 | Each line in this file with be processes by the | |
108 | <code>readString(string)</code> method introduced above. You can thus | |
109 | freely mix comment lines and lines handed on to <code>Settings</code> | |
110 | or to <code>ParticleDataTable</code>. | |
111 | Again, an optional second argument <code>false</code> allows | |
112 | you to switch off warning messages for unknown variables.<br/> | |
113 | This approach is better suited for more extensive changes than a direct | |
114 | usage of <code>readString(string)</code>, and can also avoid having to | |
115 | recompile and relink your main program between runs. | |
116 | </li> | |
117 | ||
118 | <p/> | |
119 | <li> | |
120 | Next comes the initialization stage, where all | |
121 | remaining details of the generation are to be specified. The | |
122 | <code>init(...)</code> method allows a few different input formats, | |
123 | so you can pick the one convenient for you: | |
124 | ||
125 | <p/> | |
126 | a) <code>pythia.init( idA, idB, eCM);</code><br/> | |
127 | lets you specify the identities and the CM energy of the two incoming | |
128 | beam particles, with A (B) assumed moving in the <ei>+z (-z)</ei> | |
129 | direction. | |
130 | ||
131 | <p/> | |
132 | b) <code>pythia.init( idA, idB, eA, eB);</code><br/> | |
133 | is similar, but the two beam energies can be different, so the | |
134 | collisions do not occur in the CM frame. If one of the beam energies | |
135 | is below the particle mass you obtain a fixed-target topology. | |
136 | ||
137 | <p/> | |
138 | c) <code>pythia.init( idA, idB, pxA, pyA, pzA, pxB, pyB, pzB);</code><br/> | |
139 | is similar, but here you provide the three-momenta | |
140 | <ei>(p_x, p_y, p_z)</ei> of the two incoming particles, | |
141 | to allow for arbitrary beam directions. | |
142 | ||
143 | <p/> | |
144 | d) <code>pythia.init(fileName);</code> <br/> | |
145 | assumes a file in the <aloc href="LesHouchesAccord">Les Houches | |
146 | Event File</aloc> format <ref>Alw06</ref> is provided. | |
147 | ||
148 | <p/> | |
149 | e) <code>pythia.init();</code><br/> | |
150 | with no arguments will read the beam parameters from the | |
151 | <aloc href="MainProgramSettings"><code>Main</code></aloc> | |
152 | group of variables, which provides you with the same possibilities as | |
153 | the above options a, b, c and d. If you don't change any of those you will | |
154 | default to proton-proton collisions at 14 TeV, i.e. the nominal LHC | |
155 | values. | |
156 | ||
157 | <p/> | |
158 | f) <code>pythia.init( LHAup*);</code> <br/> | |
159 | assumes <aloc href="LesHouchesAccord">Les Houches Accord</aloc> | |
160 | <ref>Boo01</ref> initialization and event information is available | |
161 | in an <code>LHAup</code> class object, and that a pointer to this object | |
162 | is handed in. | |
163 | ||
164 | <p/> | |
165 | <li> | |
166 | If you want to have a list of the generator and particle data used, | |
167 | either only what has been changed or everything, you can use | |
168 | <pre> | |
169 | pythia.settings.listChanged(); | |
170 | pythia.settings.listAll(); | |
171 | pythia.particleData.listChanged(); | |
172 | pythia.particleData.listAll(); | |
173 | </pre> | |
174 | </li> | |
175 | ||
176 | </ol> | |
177 | ||
178 | <h3>The event loop</h3> | |
179 | ||
180 | <ol> | |
181 | ||
182 | <li> | |
183 | Inside the event generation loop you generate the | |
184 | next event using the <code>next()</code> method, | |
185 | <pre> | |
186 | pythia.next(); | |
187 | </pre> | |
188 | This method takes no arguments; everything has already been specified. | |
189 | It does return a bool value, however, <code>false</code> when the | |
190 | generation failed. This can be a "programmed death" when the | |
191 | supply of input parton-level configurations on file is exhausted, | |
192 | but also caused by a failure of <code>Pythia</code> to generate an event, | |
193 | or that an event was generated but something strange was detected | |
194 | in it. It makes sense to allow a few <code>false</code> | |
195 | values before a run is aborted, so long as the related faulty | |
196 | events are skipped. | |
197 | </li> | |
198 | ||
199 | <p/> | |
200 | <li> | |
201 | The generated event is now stored in the <code>event</code> | |
202 | object, of type <aloc href="EventRecord"><code>Event</code></aloc>, | |
203 | which is a public member of <code>pythia</code>. You therefore have | |
204 | access to all the tools described on the pages under the "Study Output" | |
205 | header in the index. For instance, an event can be listed with | |
206 | <code>pythia.event.list()</code>, the identity of the <ei>i</ei>'th | |
207 | <aloc href="ParticleProperties">particle</aloc> is given by | |
208 | <code>pythia.event[i].id()</code>, and so on.<br/> | |
209 | The hard process - roughly the information normally stored in the | |
210 | Les Houches Accord event record - is available as a second object, | |
211 | <code>process</code>, also of type <code>Event</code>.<br/> | |
212 | A third public object is | |
213 | <aloc href="EventInformation"><code>info</code></aloc>, which offers | |
214 | a set of one-of-a kind pieces of information about the most recent | |
215 | event. | |
216 | </li> | |
217 | ||
218 | </ol> | |
219 | ||
220 | <h3>Finishing</h3> | |
221 | ||
222 | <ol> | |
223 | ||
224 | <li>At the end of the generation process, you can call | |
225 | <pre> | |
226 | pythia.statistics(); | |
227 | </pre> | |
228 | to get some run statistics, on cross sections and the number of errors | |
229 | and warnings encountered. With optional argument <code>true</code> | |
230 | also further statistics is printed. Currently this means the number of | |
231 | different subprocesses generated in the multiple-interactions | |
232 | framework. | |
233 | </li> | |
234 | ||
235 | </ol> | |
236 | ||
237 | <h3>Advanced usage, mainly for initialization</h3> | |
238 | ||
239 | A) Necessary data are automatically loaded when you use the | |
240 | default PYTHIA installation directory structure and run the main | |
241 | programs in the <code>examples</code> subdirectory. However, in the | |
242 | general case, you must provide the path to the <code>.xml</code> files, | |
243 | originally stored in the <code>xmldoc</code> directory, where default | |
244 | settings and particle data are found. This can be done in two ways. | |
245 | ||
246 | <ol> | |
247 | ||
248 | <li> | |
249 | You can set the environment variable <code>PYTHIA8DATA</code> to | |
250 | contain the location of the <code>xmldoc</code> directory. In the | |
251 | <code>csh</code> and <code>tcsh</code> shells this could e.g. be | |
252 | <pre> | |
253 | setenv PYTHIA8DATA /home/myname/pythia81xx/xmldoc | |
254 | </pre> | |
255 | while in other shells it could be | |
256 | <pre> | |
257 | export PYTHIA8DATA=/home/myname/pythia81xx/xmldoc | |
258 | </pre> | |
259 | where xx is the subversion number.<br/> | |
260 | Recall that environment variables set locally are only defined in the | |
261 | current instance of the shell. The above lines should go into your | |
262 | <code>.cshrc</code> and <code>.bashrc</code> files, respectively, | |
263 | if you want a more permanant assignment. | |
264 | </li> | |
265 | ||
266 | <p/> | |
267 | <li> | |
268 | You can provide the path as argument to the <code>Pythia</code> | |
269 | constructor, e.g. | |
270 | <pre> | |
271 | Pythia pythia("/home/myname/pythia81xx/xmldoc"); | |
272 | </pre> | |
273 | </li> | |
274 | </ol> | |
275 | where again xx is the subversion number.<br/> | |
276 | When <code>PYTHIA8DATA</code> is set it takes precedence, else | |
277 | the path in the constructor is used, else one defaults to the | |
278 | <code>../xmldoc</code> directory. | |
279 | ||
280 | <p/> | |
281 | B) You can override the default behaviour of PYTHIA not only by the | |
282 | settings and particle data, but also by replacing some of the | |
283 | PYTHIA standard routines by ones of your own. Of course, this is only | |
284 | possible if your routines fit into the general PYTHIA framework. | |
285 | Therefore they must be coded according to the the rules relevant | |
286 | in each case, as a derived class of a PYTHIA base class, and a pointer | |
287 | to such an object must be handed in by one of the methods below. | |
288 | These calls must be made before the <code>pythia.init(...)</code> call. | |
289 | ||
290 | <ol> | |
291 | ||
292 | <li> | |
293 | If you are not satisfied with the list of parton density functions that | |
294 | are implemented internally or available via the LHAPDF interface | |
295 | (see the <aloc href="PDFSelection">PDF Selection</aloc> page), you | |
296 | can suppy your own by a call to the <code>setPDFPtr(...)</code> method | |
297 | <pre> | |
298 | pythia.setPDFptr( pdfAPtr, pdfBPtr); | |
299 | </pre> | |
300 | where <code>pdfAPtr</code> and <code>pdfBPtr</code> are pointers to | |
301 | two <code>Pythia</code> <aloc href="PartonDistributions">PDF | |
302 | objects</aloc>. Note that <code>pdfAPtr</code> and <code>pdfBPtr</code> | |
303 | cannot point to the same object; even if the PDF set is the same, | |
304 | two copies are needed to keep track of two separate sets of <ei>x</ei> | |
305 | and density values.<br/> | |
306 | If you further wish to use separate PDF's for the hard process of an | |
307 | event than the ones being used for everything else, the extended form | |
308 | <pre> | |
309 | pythia.setPDFptr( pdfAPtr, pdfBPtr, pdfHardAPtr, pdfHardBPtr); | |
310 | </pre> | |
311 | allows you to specify those separately, and then the first two sets | |
312 | would only be used for the showers and for multiple interactions. | |
313 | </li> | |
314 | ||
315 | <p/> | |
316 | <li> | |
317 | If you want to perform some particle decays with an | |
318 | external generator, you can call the <code>setDecayPtr(...)</code> | |
319 | method | |
320 | <pre> | |
321 | pythia.setDecayPtr( decayHandlePtr, particles); | |
322 | </pre> | |
323 | where the <code>decayHandlePtr</code> derives from the | |
324 | <aloc href="ExternalDecays"><code>DecayHandler</code></aloc> base | |
325 | class and <code>particles</code> is a vector of particle codes to be | |
326 | handled. | |
327 | </li> | |
328 | ||
329 | <p/> | |
330 | <li> | |
331 | If you want to use an external random number generator, | |
332 | you can call the <code>setRndmEnginePtr(...)</code> method | |
333 | <pre> | |
334 | pythia.setRndmEnginePtr( rndmEnginePtr); | |
335 | </pre> | |
336 | where <code>rndmEnginePtr</code> derives from the | |
337 | <aloc href="RandomNumbers"><code>RndmEngine</code></aloc> base class. | |
338 | The <code>Pythia</code> default random number generator is perfectly | |
339 | good, so this is only intended for consistency in bigger frameworks. | |
340 | </li> | |
341 | ||
342 | <p/> | |
343 | <li> | |
344 | If you want to interrupt the evolution at various stages, | |
345 | to interrogate the event and possibly veto it, or you want to | |
346 | reweight the cross section, you can use | |
347 | <pre> | |
348 | pythia.setUserHooksPtr( userHooksPtr); | |
349 | </pre> | |
350 | where <code>userHooksPtr</code> derives from the | |
351 | <aloc href="UserHooks"><code>UserHooks</code></aloc> base class. | |
352 | </li> | |
353 | ||
354 | <p/> | |
355 | <li> | |
356 | If you want to use your own parametrization of beam momentum spread and | |
357 | interaction vertex, rather than the provided simple Gaussian | |
358 | parametrization (off by default), you can call | |
359 | <pre> | |
360 | pythia.setBeamShapePtr( beamShapePtr); | |
361 | </pre> | |
362 | where <code>beamShapePtr</code> derives from the | |
363 | <aloc href="BeamShape"><code>BeamShape</code></aloc> base class. | |
364 | </li> | |
365 | ||
366 | <p/> | |
367 | <li> | |
368 | If you want to implement a cross section of your own, but still make use | |
369 | of the built-in phase space selection machinery, you can use | |
370 | <pre> | |
371 | pythia.setSigmaPtr( sigmaPtr); | |
372 | </pre> | |
373 | where <code>sigmaPtr</code> of type <code>SigmaProcess*</code> is an | |
374 | instance of a class derived from one of the <code>Sigma1Process</code>, | |
375 | <code>Sigma2Process</code> and <code>Sigma3Process</code> base classes | |
376 | in their turn derived from | |
377 | <aloc href="SemiInternalProcesses"><code>SigmaProcess</code></aloc>. | |
378 | This call can be used repeatedly to hand in several different processes. | |
379 | </li> | |
380 | ||
381 | <p/> | |
382 | <li> | |
383 | If your cross section contains the production of a new resonance | |
384 | with known analytical expression for all the relevant partial widths, | |
385 | you can make this resonance available to the program with | |
386 | <pre> | |
387 | pythia.setResonancePtr( resonancePtr); | |
388 | </pre> | |
389 | where <code>resonancePtr</code> of type <code>ResonanceWidths*</code> | |
390 | is an instance of a class derived from the | |
391 | <aloc href="SemiInternalResonances"><code>ResonanceWidths</code></aloc> | |
392 | base class. In addition you need to add the particle to the normal | |
393 | <aloc href="ParticleDataScheme">particle and decay database</aloc>. | |
394 | This procedure can be used repeatedly to hand in several different | |
395 | resonances. | |
396 | </li> | |
397 | ||
398 | <p/> | |
399 | <li> | |
400 | If you are a real expert and want to replace the PYTHIA initial- and | |
401 | final-state showers, you can use | |
402 | <pre> | |
403 | pythia.setShowerPtr( timesDecPtr, timesPtr, spacePtr); | |
404 | </pre> | |
405 | where <code>timesDecPtr</code> and <code>timesPtr</code> | |
406 | derive from the <code>TimeShower</code> base class, and | |
407 | <code>spacePtr</code> from <code>SpaceShower</code> | |
408 | (<aloc href="ImplementNewShowers">further instructions</aloc>). | |
409 | </li> | |
410 | ||
411 | </ol> | |
412 | ||
413 | <p/> | |
414 | C) Some comments on collecting several tasks in the same run. | |
415 | <ol> | |
416 | ||
417 | <li> | |
418 | PYTHIA has not been written for threadsafe execution. As a rule, you | |
419 | should not have more than one <code>Pythia</code> object in an executable | |
420 | at any time. For multicore processors, if you want to use all cores, | |
421 | the most efficient way presumably is to start correspondingly many jobs, | |
422 | with different random number seeds, and add the statistics at the end. | |
423 | ||
424 | <p/> | |
425 | In some cases it is possible to use more than one <code>Pythia</code> | |
426 | object. The key example would be the simultaneous generation of signal | |
427 | and pileup events, see <code>main19.cc</code>. Here all signal processes | |
428 | must be switched on before the first initialization, and then switched | |
429 | off and replaced by the background ones before the second initialization. | |
430 | Also most other settings can be changed consistently in between the two | |
431 | initializations, but in a few cases the last value will be used. Particle | |
432 | data is always based on the latest information. As a rule, however, it is | |
433 | safer to use two separate runs to store events on disk, in two separate | |
434 | files, and mix afterwards. | |
435 | </li> | |
436 | ||
437 | <p/> | |
438 | <li> | |
439 | When time is not an issue, it may be that you want to perform several | |
440 | separate subruns sequentially inside a run, e.g. to combine results for | |
441 | several kinematical regions or to compare results for some different | |
442 | tunes of the underlying event. One way to go is to create and destroy a | |
443 | <code>pythia</code> object once for each subrun, in which case they are | |
444 | completely separate. You can also use the same <code>pythia</code> object, | |
445 | only doing a new <code>init(...)</code> call for each subrun. In that | |
446 | case, the settings and particle databases remain as they were in the | |
447 | previous subrun, only affected by the specific changes you introduced in | |
448 | the meantime. You can put those changes in the main program, with | |
449 | <code>pythia.readString(string)</code>, using your own logic to decide | |
450 | which ones to execute in which subrun. A corresponding possibility | |
451 | exists with <code>pythia.readFile(fileName, subrun)</code>, which | |
452 | as second argument can take a non-negative subrun number. (Or, | |
453 | alternatively use the longer form | |
454 | <code>pythia.readFile(fileName, warn, subrun)</code>.) Then only those | |
455 | sections of the file before any <code>Main:subrun = ...</code> line | |
456 | or with matching <code>subrun</code> number will be read. That is, the | |
457 | file could have a structure like | |
458 | <pre> | |
459 | ( lines always read, i.e. "default values" always (re)set ) | |
460 | Main:subrun = 1 | |
461 | ( lines only read with readFile(fileName, 1) ) | |
462 | Main:subrun = 2 | |
463 | ( lines only read with readFile(fileName, 2) ) | |
464 | </pre> | |
465 | Both of these possibilities are illustrated in <code>main08.cc</code>. | |
466 | </li> | |
467 | ||
468 | <p/> | |
469 | <li> | |
470 | When working with Les Houches Event Files, it may well be that your | |
471 | intended input event sample is spread over several files, that you all | |
472 | want to turn into complete events in one and the same run. There is no | |
473 | problem with looping over several subruns, where each new subrun | |
474 | is initialized with a new file. However, in that case you will do | |
475 | a complete re-initialization each time around. If you want to avoid | |
476 | this, note that there is an optional second argument for LHEF | |
477 | initialization: <code>pythia.init(fileName, skipInit)</code>. | |
478 | Alternatively, the tag <code>Main:LHEFskipInit</code> can be put | |
479 | in a file of commands to obtain the same effect. | |
480 | Here <code>skipInit</code> defaults to <code>false</code>, | |
481 | but if set <code>true</code> then the new file will be simulated | |
482 | with the same initialization data as already set in a previous | |
483 | <code>pythia.init(...)</code> call. The burden rests on you to ensure | |
484 | that this is indeed correct, e.g. that the two event samples have not | |
485 | been generated for different beam energies. | |
486 | </li> | |
487 | ||
488 | </ol> | |
489 | ||
490 | </chapter> | |
491 | ||
492 | <!-- Copyright (C) 2008 Torbjorn Sjostrand --> |