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