]>
Commit | Line | Data |
---|---|---|
63ba5337 | 1 | <html> |
2 | <head> | |
3 | <title>Les Houches Accord</title> | |
4 | <link rel="stylesheet" type="text/css" href="pythia.css"/> | |
5 | <link rel="shortcut icon" href="pythia32.gif"/> | |
6 | </head> | |
7 | <body> | |
8 | ||
9 | <h2>Les Houches Accord</h2> | |
10 | ||
11 | The Les Houches Accord (LHA) for user processes [<a href="Bibliography.html" target="page">Boo01</a>] is the | |
12 | standard way to input parton-level information from a | |
13 | matrix-elements-based generator into PYTHIA. The conventions for | |
14 | which information should be stored has been defined in a Fortran context, | |
15 | as two commonblocks. Here a C++ equivalent is defined, as a single class. | |
16 | ||
17 | <p/> | |
18 | The <code>LHAup</code> class is a base class, containing reading and | |
19 | printout functions, plus two pure virtual functions, one to set | |
20 | initialization information and one to set information on each new event. | |
21 | Derived classes have to provide these two virtual functions to do | |
22 | the actual work. The existing derived classes are for reading information | |
23 | from a Les Houches Event File (LHEF), from the respective Fortran | |
24 | commonblocks, or from PYTHIA 8 itself. | |
25 | ||
26 | <p/> | |
27 | You are free to write your own derived classes, using the rules and | |
28 | methods to be described below. Normally, pointers to objects of such | |
29 | derived classes should be handed in with the | |
30 | <code><a href="ProgramFlow.html" target="page">Pythia::init( LHAup*)</a></code> | |
31 | method. However, with the LHEF format a filename can replace the | |
32 | pointer, see further below. | |
33 | ||
34 | <p/> | |
35 | Let us now describe the methods at your disposal to do the job. | |
36 | ||
37 | <a name="method1"></a> | |
38 | <p/><strong>LHAup::LHAup( int strategy = 3) </strong> <br/> | |
39 | the base class constructor takes the choice of mixing/weighting | |
40 | strategy as optional input argument, and calls <code>setStrategy</code>, | |
41 | see below. It also reserves some space for processes and particles. | |
42 | ||
43 | ||
44 | <a name="method2"></a> | |
45 | <p/><strong>virtual LHAup::~LHAup() </strong> <br/> | |
46 | the destructor does not need to do anything. | |
47 | ||
48 | ||
49 | <a name="method3"></a> | |
50 | <p/><strong>void LHAup::setPtr(Info* infoPtr) </strong> <br/> | |
51 | this method only sets the pointer that allows some information | |
52 | to be accessed, and is automatically called by | |
53 | <code>Pythia::init(...)</code>. | |
54 | ||
55 | ||
56 | <h3>Initialization</h3> | |
57 | ||
58 | The <code>LHAup</code> class stores information equivalent to the | |
59 | <code>/HEPRUP/</code> commonblock, as required to initialize the event | |
60 | generation chain. The main difference is that the vector container | |
61 | now allows a flexible number of subprocesses to be defined. For the | |
62 | rest, names have been modified, since the 6-character-limit does not | |
63 | apply, and variables have been regrouped for clarity, but nothing | |
64 | fundamental is changed. | |
65 | ||
66 | <a name="method4"></a> | |
67 | <p/><strong>virtual bool LHAup::setInit() </strong> <br/> | |
68 | this pure virtual method has to be implemented in the derived class, | |
69 | to set relevant information when called. It should return false if it | |
70 | fails to set the info. | |
71 | ||
72 | ||
73 | <p/> | |
74 | Inside <code>setInit()</code>, such information can be set by the following | |
75 | methods: | |
76 | <a name="method5"></a> | |
77 | <p/><strong>void LHAup::setBeamA( int identity, double energy, int pdfGroup, int pdfSet) </strong> <br/> | |
78 | ||
79 | <strong>void LHAup::setBeamB( int identity, double energy, int pdfGroup, int pdfSet) </strong> <br/> | |
80 | sets the properties of the first and second incoming beam, respectively | |
81 | (cf. the Fortran <code>IDBMUP(1), EBMUP(i), PDFGUP(i), PDFSUP(i)</code>, | |
82 | with <code>i</code> 1 or 2). The parton distribution information | |
83 | defaults to zero. These numbers can be used to tell which PDF sets were | |
84 | used when the hard process was generated, while the normal | |
85 | <a href="PDFSelection.html" target="page">PDF Selection</a> is used for the further | |
86 | event generation in PYTHIA. | |
87 | ||
88 | ||
89 | <a name="method6"></a> | |
90 | <p/><strong>void LHAup::setStrategy( int strategy) </strong> <br/> | |
91 | sets the event weighting and cross section strategy. The default, | |
92 | provided in the class constructor, is 3, which is the natural value | |
93 | e.g. for an LHEF. | |
94 | <br/><code>argument</code><strong> strategy </strong> : | |
95 | chosen strategy (cf. <code>IDWTUP</code>; see [<a href="Bibliography.html" target="page">Sjo06</a>] | |
96 | section 9.9.1 for extensive comments). | |
97 | <br/><code>argumentoption </code><strong> 1</strong> : events come with non-negative weight, given in units | |
98 | of pb, with an average that converges towards the cross section of the | |
99 | process. PYTHIA is in charge of the event mixing, i.e. for each new | |
100 | try decides which process should be generated, and then decides whether | |
101 | is should be kept, based on a comparison with <code>xMax</code>. | |
102 | Accepted events therefore have unit weight. | |
103 | <br/><code>argumentoption </code><strong> -1</strong> : as option 1, except that cross sections can now be | |
104 | negative and events after unweighting have weight +-1. You can use | |
105 | <code><a href="EventInformation.html" target="page">Info::weight()</a></code> | |
106 | to find the weight of the current event. A correct event mixing requires | |
107 | that a process that can take both signs should be split in two, one limited | |
108 | to positive or zero and the other to negative or zero values, with | |
109 | <code>xMax</code> chosen appropriately for the two. | |
110 | <br/><code>argumentoption </code><strong> 2</strong> : events come with non-negative weight, in unspecified | |
111 | units, but such that <code>xMax</code> can be used to unweight the events | |
112 | to unit weight. Again PYTHIA is in charge of the event mixing. | |
113 | The total cross section of a process is stored in | |
114 | <code>xSec</code>. | |
115 | <br/><code>argumentoption </code><strong> -2</strong> : as option 2, except that cross sections can now be | |
116 | negative and events after unweighting have weight +-1. As for option -1 | |
117 | processes with indeterminate sign should be split in two. | |
118 | <br/><code>argumentoption </code><strong> 3</strong> : events come with unit weight, and are thus accepted | |
119 | as is. The total cross section of the process is stored in | |
120 | <code>xSec</code>. | |
121 | <br/><code>argumentoption </code><strong> -3</strong> : as option 3, except that events now come with weight | |
122 | +-1. Unlike options -1 and -2 processes with indeterminate sign need not be | |
123 | split in two, unless you intend to mix with internal PYTHIA processes | |
124 | (see below). | |
125 | <br/><code>argumentoption </code><strong> 4</strong> : events come with non-negative weight, given in units | |
126 | of pb, with an average that converges towards the cross section of the | |
127 | process, like for option 1. No attempt is made to unweight the events, | |
128 | however, but all are generated in full, and retain their original weight. | |
129 | For consistency with normal PYTHIA units, the weight stored in | |
130 | <code>Info::weight()</code> has been converted to mb, however. | |
131 | ||
132 | <br/><code>argumentoption </code><strong> -4</strong> : as option 4, except that events now can come | |
133 | either with positive or negative weights. | |
134 | <br/><b>Note 1</b>: if several processes have already been mixed and | |
135 | stored in a common event file, either LHEF or some private format, it | |
136 | would be problematical to read back events in a different order. Since it | |
137 | is then not feasible to let PYTHIA pick the next process type, strategies | |
138 | +-1 and +-2 would not work. Instead strategy 3 would be the recommended | |
139 | choice, or -3 if negative-weight events are required. | |
140 | <br/><b>Note 2</b>: it is possible to switch on internally implemented | |
141 | processes and have PYTHIA mix these with LHA ones according to their relative | |
142 | cross sections for strategies +-1, +-2 and 3. It does not work for strategy | |
143 | -3 unless the positive and negative sectors of the cross sections are in | |
144 | separate subprocesses (as must always be the case for -1 and -2), since | |
145 | otherwise the overall mixture of PYTHIA and LHA processes will be off. | |
146 | Mixing is not possible for strategies +-4, since the weighting procedure | |
147 | is not specified by the standard. (For instance, the intention may be to | |
148 | have events biased towards larger <i>pT</i> values in some particular | |
149 | functional form.) | |
150 | ||
151 | ||
152 | ||
153 | <a name="method7"></a> | |
154 | <p/><strong>void LHAup::addProcess( int idProcess, double xSec, double xErr, double xMax) </strong> <br/> | |
155 | sets info on an allowed process (cf. <code>LPRUP, XSECUP, XERRUP, | |
156 | XMAXUP</code>). | |
157 | Each new call will append one more entry to the list of processes. | |
158 | The choice of strategy determines which quantities are mandatory: | |
159 | <code>xSec</code> for strategies +-2 and +-3, | |
160 | <code>xErr</code> never, and | |
161 | <code>xMax</code> for strategies +-1 and +-2. | |
162 | ||
163 | ||
164 | <br/><b>Note</b>: PYTHIA does not make active use of the (optional) | |
165 | <code>xErr</code> values, but calculates a statistical cross section | |
166 | error based on the spread of event-to-event weights. This should work | |
167 | fine for strategy options +-1, but not for the others. Specifically, | |
168 | for options +-2 and +-3 the weight spread may well vanish, and anyway | |
169 | is likely to be an underestimate of the true error. If the author of the | |
170 | LHA input information does provide error information you may use that - | |
171 | this information is displayed at initialization. If not, then a relative | |
172 | error decreasing like <i>1/sqrt(n_acc)</i>, where <i>n_acc</i> | |
173 | is the number of accepted events, should offer a reasonable estimate. | |
174 | ||
175 | <a name="method8"></a> | |
176 | <p/><strong>void LHAup::setXSec( int i, double xSec) </strong> <br/> | |
177 | update the <code>xSec</code> value of the <code>i</code>'th process | |
178 | added with <code>addProcess</code> method (i.e. <code>i</code> runs | |
179 | from 0 through <code>sizeProc() - 1</code>, see below). | |
180 | ||
181 | ||
182 | <a name="method9"></a> | |
183 | <p/><strong>void LHAup::setXErr( int i, double xErr) </strong> <br/> | |
184 | update the <code>xErr</code> value of the <code>i</code>'th process | |
185 | added with <code>addProcess</code> method. | |
186 | ||
187 | ||
188 | <a name="method10"></a> | |
189 | <p/><strong>void LHAup::setXMax( int i, double xMax) </strong> <br/> | |
190 | update the <code>xMax</code> value of the <code>i</code>'th process | |
191 | added with <code>addProcess</code> method. | |
192 | ||
193 | ||
194 | <a name="method11"></a> | |
195 | <p/><strong>void LHAup::setInfoHeader(string &key, string &val) </strong> <br/> | |
196 | set the header <code>key</code> to have value <code>val</code>. | |
197 | This is a wrapper function to the | |
198 | <a href="EventInformation.html" target="page">Info::setHeader</a> function that | |
199 | should be used in any classes derived from LHAup. | |
200 | ||
201 | ||
202 | <p/> | |
203 | Information is handed back by the following methods | |
204 | (that normally you would not need to touch): | |
205 | <a name="method12"></a> | |
206 | <p/><strong>int LHAup::idBeamA() </strong> <br/> | |
207 | ||
208 | <strong>int LHAup::idBeamB() </strong> <br/> | |
209 | ||
210 | <strong>double LHAup::eBeamA() </strong> <br/> | |
211 | ||
212 | <strong>double LHAup::eBeamB() </strong> <br/> | |
213 | ||
214 | <strong>int LHAup::pdfGroupBeamA() </strong> <br/> | |
215 | ||
216 | <strong>int LHAup::pdfGroupBeamB() </strong> <br/> | |
217 | ||
218 | <strong>int LHAup::pdfSetBeamA() </strong> <br/> | |
219 | ||
220 | <strong>int LHAup::pdfSetBeamB() </strong> <br/> | |
221 | for the beam properties. | |
222 | ||
223 | <a name="method13"></a> | |
224 | <p/><strong>int LHAup::strategy() </strong> <br/> | |
225 | for the strategy choice. | |
226 | ||
227 | <a name="method14"></a> | |
228 | <p/><strong>int LHAup::sizeProc() </strong> <br/> | |
229 | for the number of subprocesses. | |
230 | ||
231 | <a name="method15"></a> | |
232 | <p/><strong>int LHAup::idProcess(i) </strong> <br/> | |
233 | ||
234 | <strong>double LHAup::xSec(i) </strong> <br/> | |
235 | ||
236 | <strong>double LHAup::xErr(i) </strong> <br/> | |
237 | ||
238 | <strong>double LHAup::xMax(i) </strong> <br/> | |
239 | for process <code>i</code> in the range <code>0 <= i < | |
240 | sizeProc()</code>. | |
241 | ||
242 | ||
243 | <a name="method16"></a> | |
244 | <p/><strong>double LHAup::xSecSum() </strong> <br/> | |
245 | ||
246 | <strong>double LHAup::xErrSum() </strong> <br/> | |
247 | the sum of the cross sections and errors (the latter added quadratically). | |
248 | Note that cross section errors are only meaningful for strategies +-3. | |
249 | ||
250 | ||
251 | <a name="method17"></a> | |
252 | <p/><strong>void LHAup::listInit(ostream& os = cout) </strong> <br/> | |
253 | prints the above initialization information. This method is | |
254 | automatically called from <code>Pythia::init(...)</code>, | |
255 | so would normally not need to be called directly by the user. | |
256 | ||
257 | ||
258 | <p/> | |
259 | ||
260 | ||
261 | <h3>Event input</h3> | |
262 | ||
263 | The <code>LHAup</code> class also stores information equivalent to the | |
264 | <code>/HEPEUP/</code> commonblock, as required to hand in the next | |
265 | parton-level configuration for complete event generation. The main | |
266 | difference is that the vector container now allows a flexible number | |
267 | of partons to be defined. For the rest, names have been modified, | |
268 | since the 6-character-limit does not apply, and variables have been | |
269 | regrouped for clarity, but nothing fundamental is changed. | |
270 | ||
271 | <p/> | |
272 | The LHA standard is based on Fortran arrays beginning with | |
273 | index 1, and mother information is defined accordingly. In order to | |
274 | be compatible with this convention, the zeroth line of the C++ particle | |
275 | array is kept empty, so that index 1 also here corresponds to the first | |
276 | particle. One small incompatibility is that the <code>sizePart()</code> | |
277 | method returns the full size of the particle array, including the | |
278 | empty zeroth line, and thus is one larger than the true number of | |
279 | particles (<code>NUP</code>). | |
280 | ||
281 | <a name="method18"></a> | |
282 | <p/><strong>virtual bool LHAup::setEvent(int idProcess = 0) </strong> <br/> | |
283 | this pure virtual method has to be implemented in the derived class, | |
284 | to set relevant information when called. For strategy options +-1 | |
285 | and +-2 the input <code>idProcess</code> value specifies which process | |
286 | that should be generated, while <code>idProcess</code> is irrelevant | |
287 | for strategies +-3 and +-4. The method should return false if it fails | |
288 | to set the info, i.e. normally that the supply of events in a file is | |
289 | exhausted. If so, no event is generated, and <code>Pythia::next()</code> | |
290 | returns false. You can then interrogate | |
291 | <code><a href="EventInformation.html" target="page">Info::atEndOfFile()</a></code> | |
292 | to confirm that indeed the failure is caused in this method, and decide | |
293 | to break out of the event generation loop. | |
294 | ||
295 | <p/> | |
296 | Inside a normal <code>setEvent(...)</code> call, information can be set | |
297 | by the following methods: | |
298 | <a name="method19"></a> | |
299 | <p/><strong>void LHAup::setProcess( int idProcess, double weight, double scale, double alphaQED, double alphaQCD) </strong> <br/> | |
300 | tells which kind of process occured, with what weight, at what scale, | |
301 | and which <i>alpha_EM</i> and <i>alpha_strong</i> were used | |
302 | (cf. <code>IDPRUP, XWTGUP, SCALUP, AQEDUP, AQCDUP</code>). This method | |
303 | also resets the size of the particle list, and adds the empty zeroth | |
304 | line, so it has to be called before the <code>addParticle</code> method below. | |
305 | ||
306 | <a name="method20"></a> | |
307 | <p/><strong>void LHAup::addParticle( int id, int status, int mother1, int mother2, int colourTag1, int colourTag2, double p_x, double p_y, double p_z, double e, double m, double tau, double spin) </strong> <br/> | |
308 | gives the properties of the next particle handed in (cf. <code>IDUP, ISTUP, | |
309 | MOTHUP(1,..), MOTHUP(2,..), ICOLUP(1,..), ICOLUP(2,..), PUP(J,..), | |
310 | VTIMUP, SPINUP</code>) . | |
311 | ||
312 | ||
313 | <p/> | |
314 | Information is handed back by the following methods: | |
315 | <a name="method21"></a> | |
316 | <p/><strong>int LHAup::idProcess() </strong> <br/> | |
317 | process number. | |
318 | ||
319 | ||
320 | <a name="method22"></a> | |
321 | <p/><strong>double LHAup::weight() </strong> <br/> | |
322 | Note that the weight stored in <code>Info::weight()</code> as a rule | |
323 | is not the same as the above <code>weight()</code>: the method here gives | |
324 | the value before unweighting while the one in <code>info</code> gives | |
325 | the one after unweighting and thus normally is 1 or -1. Only with strategy | |
326 | options +-3 and +-4 would the value in <code>info</code> be the same as | |
327 | here, except for a conversion from pb to mb for +-4. | |
328 | ||
329 | ||
330 | <a name="method23"></a> | |
331 | <p/><strong>double LHAup::scale() </strong> <br/> | |
332 | ||
333 | <strong>double LHAup::alphaQED() </strong> <br/> | |
334 | ||
335 | <strong>double LHAup::alphaQCD() </strong> <br/> | |
336 | scale and couplings at that scale. | |
337 | ||
338 | ||
339 | <a name="method24"></a> | |
340 | <p/><strong>int LHAup::sizePart() </strong> <br/> | |
341 | the size of the particle array, which is one larger than the number | |
342 | of particles in the event, since the zeroth entry is kept empty | |
343 | (see above). | |
344 | ||
345 | ||
346 | <a name="method25"></a> | |
347 | <p/><strong>int LHAup::id(int i) </strong> <br/> | |
348 | ||
349 | <strong>int LHAup::status(int i) </strong> <br/> | |
350 | ||
351 | <strong>int LHAup::mother1(int i) </strong> <br/> | |
352 | ||
353 | <strong>int LHAup::mother2(int i) </strong> <br/> | |
354 | ||
355 | <strong>int LHAup::col1(int i) </strong> <br/> | |
356 | ||
357 | <strong>int LHAup::col2(int i) </strong> <br/> | |
358 | ||
359 | <strong>double LHAup::px(int i) </strong> <br/> | |
360 | ||
361 | <strong>double LHAup::py(int i) </strong> <br/> | |
362 | ||
363 | <strong>double LHAup::pz(int i) </strong> <br/> | |
364 | ||
365 | <strong>double LHAup::e(int i) </strong> <br/> | |
366 | ||
367 | <strong>double LHAup::m(int i) </strong> <br/> | |
368 | ||
369 | <strong>double LHAup::tau(int i) </strong> <br/> | |
370 | ||
371 | <strong>double LHAup::spin(int i) </strong> <br/> | |
372 | for particle <code>i</code> in the range | |
373 | <code>0 <= i < sizePart()</code>. (But again note that | |
374 | <code>i = 0</code> is an empty line, so the true range begins at 1.) | |
375 | ||
376 | ||
377 | <p/> | |
378 | From the information in the event record it is possible to set | |
379 | the flavour and <i>x</i> values of the initiators | |
380 | <a name="method26"></a> | |
381 | <p/><strong>void LHAup::setIdX(int id1, int id2, double x1, double x2) </strong> <br/> | |
382 | ||
383 | ||
384 | <p/> | |
385 | This information is returned by the methods | |
386 | <a name="method27"></a> | |
387 | <p/><strong>int LHAup::id1() </strong> <br/> | |
388 | ||
389 | <strong>int LHAup::id2() </strong> <br/> | |
390 | ||
391 | <strong>double LHAup::x1() </strong> <br/> | |
392 | ||
393 | <strong>double LHAup::x2() </strong> <br/> | |
394 | ||
395 | ||
396 | <p/> | |
397 | In the LHEF description [<a href="Bibliography.html" target="page">Alw06</a>] an extension to | |
398 | include information on the parton densities of the colliding partons | |
399 | is suggested. This optional further information can be set by | |
400 | <a name="method28"></a> | |
401 | <p/><strong>void LHAup::setPdf( int id1pdf, int id2pdf, double x1pdf, double x2pdf, double scalePDF, double pdf1, double pdf2, bool pdfIsSet) </strong> <br/> | |
402 | which gives the flavours , the <i>x</i> and the <ie>Q</i> scale | |
403 | (in GeV) at which the parton densities <i>x*f_i(x, Q)</i> have been | |
404 | evaluated. The last argument is normally <code>true</code>. | |
405 | ||
406 | ||
407 | <p/> | |
408 | This information is returned by the methods | |
409 | <a name="method29"></a> | |
410 | <p/><strong>bool LHAup::pdfIsSet() </strong> <br/> | |
411 | ||
412 | <strong>int LHAup::id1pdf() </strong> <br/> | |
413 | ||
414 | <strong>int LHAup::id2pdf() </strong> <br/> | |
415 | ||
416 | <strong>double LHAup::x1pdf() </strong> <br/> | |
417 | ||
418 | <strong>double LHAup::x2pdf() </strong> <br/> | |
419 | ||
420 | <strong>double LHAup::scalePDF() </strong> <br/> | |
421 | ||
422 | <strong>double LHAup::pdf1() </strong> <br/> | |
423 | ||
424 | <strong>double LHAup::pdf2() </strong> <br/> | |
425 | where the first one tells whether this optional information has been set | |
426 | for the current event. (<code>setPdf(...)</code> must be called after the | |
427 | <code>setProcess(...)</code> call of the event for this to work.) | |
428 | Note that the flavour and <i>x</i> values usually but not always | |
429 | agree with those obtained by the same methods without <code>pdf</code> | |
430 | in their names, see explanation in the | |
431 | <a href="EventInformation.html" target="page">Event Information</a> description. | |
432 | ||
433 | ||
434 | <p/> | |
435 | <a name="method30"></a> | |
436 | <p/><strong>void LHAup::listEvent(ostream& os = cout) </strong> <br/> | |
437 | prints the above information for the current event. In cases where the | |
438 | <code>LHAup</code> object is not available to the user, the | |
439 | <code>Pythia::LHAeventList(ostream& os = cout)</code> method can | |
440 | be used, which is a wrapper for the above. | |
441 | ||
442 | ||
443 | <a name="method31"></a> | |
444 | <p/><strong>virtual bool LHAup::skipEvent(int nSkip) </strong> <br/> | |
445 | skip ahead <code>nSkip</code> events in the Les Houches generation | |
446 | sequence, without doing anything further with them. Mainly | |
447 | intended for debug purposes, e.g. when an event at a known | |
448 | location in a Les Houches Event File is causing problems. | |
449 | Will return false if operation fails, specifically if the | |
450 | end of an LHEF has been reached. The implementation in the base class | |
451 | simply executes <code>setEvent()</code> the requested number of times. | |
452 | The derived <code>LHAupLHEF</code> class (see below) only uses the | |
453 | <code>setNewEventLHEF(...)</code> part of its <code>setEvent()</code> | |
454 | method, and other derived classes could choose other shortcuts. | |
455 | ||
456 | ||
457 | <p/> | |
458 | The LHA expects the decay of resonances to be included as part of the | |
459 | hard process, i.e. if unstable particles are produced in a process then | |
460 | their decays are also described. This includes <i>Z^0, W^+-, H^0</i> | |
461 | and other short-lived particles in models beyond the Standard Model. | |
462 | Should this not be the case then PYTHIA will perform the decays of all | |
463 | resonances it knows how to do, in the same way as for internal processes. | |
464 | Note that you will be on slippery ground if you then restrict the decay of | |
465 | these resonances to specific allowed channels since, if this is not what | |
466 | was intended, you will obtain the wrong cross section and potentially the | |
467 | wrong mix of different event types. (Since the original intention is | |
468 | unknown, the cross section will not be corrected for the fraction of | |
469 | open channels, i.e. the procedure used for internal processes is not | |
470 | applied in this case.) | |
471 | ||
472 | <p/> | |
473 | Even if PYTHIA can select resonance decay modes according to its | |
474 | internal tables, there is normally no way for it to know which | |
475 | decay angular correlations should exist in the simulated process. | |
476 | Therefore almost all decays are isotropic. The exceptions are Higgs and | |
477 | top decays, in the decay chains <i>H -> WW/ZZ -> f fbar f' fbar'</i> | |
478 | and <i>t -> b W -> b f fbar</i>, where the process-independent | |
479 | correlations implemented for internal processes are used. If part of | |
480 | the decay chain has already been set, however (e.g. <i>H -> WW/ZZ</i> | |
481 | or <i>t -> b W</i>), then decay is still isotropic. | |
482 | ||
483 | <h3>An interface to Les Houches Event Files</h3> | |
484 | ||
485 | The LHEF standard [<a href="Bibliography.html" target="page">Alw06</a>] specifies a format where a single file | |
486 | packs initialization and event information. This has become the most | |
487 | frequently used procedure to process external parton-level events in | |
488 | Pythia. Therefore a special | |
489 | <code><a href="ProgramFlow.html" target="page">Pythia::init(fileName)</a></code> | |
490 | initialization option exists, where the LHEF name is provided as input. | |
491 | Internally this name is then used to create an instance of the derived | |
492 | class <code>LHAupLHEF</code>, which can do the job of reading an LHEF. | |
493 | ||
494 | <p/> | |
495 | The LHEF reader can also read in and store header blocks. By default | |
496 | this option is switched on, but may be controlled through the | |
497 | <a href="BeamParameters.html" target="page">Beams:readLHEFheaders</a> flag if | |
498 | necessary. The information can later be read out through the | |
499 | <a href="EventInformation.html" target="page">Info</a> class for further processing. | |
500 | Due to the non-standard nature of the information in these blocks they | |
501 | are stored whole, and PYTHIA itself makes no further attempt to process | |
502 | their meaning. | |
503 | ||
504 | <p/> | |
505 | Because Les Houches Event files tend not to adhere strictly to XML | |
506 | conventions, to consistently read in header information, certain | |
507 | choices must be made. The primary goal is to make as much information | |
508 | available as possible. First, information sitting directly in the | |
509 | <header> block is stored under the key "base". Second, the tags | |
510 | starting and ending each sub block must be on their own line. Finally, | |
511 | the contents of comment blocks, <!-- -->, are still stored. The | |
512 | header keys are formed hierarchically from the names of the header | |
513 | blocks. This behaviour is illustrated in the following example: | |
514 | <pre> | |
515 | <header> | |
516 | BaseA | |
517 | <hblock1> | |
518 | 1A | |
519 | <hblock11> | |
520 | 11A <hblock111> | |
521 | </hblock111> 11B | |
522 | </hblock11> | |
523 | 1B | |
524 | </hblock1> | |
525 | <hblock2> | |
526 | 2A | |
527 | <!-- 2B --> | |
528 | </hblock2> | |
529 | BaseB | |
530 | </header> | |
531 | </pre> | |
532 | which would lead to the following information being stored in the | |
533 | <a href="EventInformation.html" target="page">Info</a> class: | |
534 | <table border="1"> | |
535 | <tr> <th>Key</th> <th>Value</th> </tr> | |
536 | <tr> | |
537 | <td>base</td> | |
538 | <td>BaseA<br/>BaseB</td> | |
539 | </tr> | |
540 | <tr> | |
541 | <td>hblock1</td> | |
542 | <td>1A<br/>1B</td> | |
543 | </tr> | |
544 | <tr> | |
545 | <td>hblock1.hblock11</td> | |
546 | <td>11A <hblock111><br/></hblock111> 11B</td> | |
547 | </tr> | |
548 | <tr> | |
549 | <td>hblock2</td> | |
550 | <td>2A<br/><!-- 2B --></td> | |
551 | </tr> | |
552 | </table> | |
553 | <br/> | |
554 | <p/> | |
555 | Normally the LHEF would be in uncompressed format, and thus human-readable | |
556 | if opened in a text editor. A possibility to read gzipped files has | |
557 | been added, based on the Boost and zlib libraries, which therefore | |
558 | have to be linked appropriately in order for this option to work. | |
559 | See the <code>README</code> file in the main directory for details | |
560 | on how to do this. | |
561 | ||
562 | <p/> | |
563 | An example how to generate events from an LHEF is found in | |
564 | <code>main11.cc</code>. Note the use of | |
565 | <code>Info::atEndOfFile()</code> to find out when the whole | |
566 | LHEF has been processed. | |
567 | ||
568 | <p/> | |
569 | To allow the sequential use of several event files the | |
570 | <code>Pythia::init(...)</code> method has an optional second argument: | |
571 | <code>Pythia::init(fileName, bool skipInit = false)</code>. | |
572 | If called with this argument <code>true</code> then there will be no | |
573 | initialization, except that the existing <code>LHAupLHEF</code> class | |
574 | instance will be deleted and replaced by ones pointing to the new file. | |
575 | It is assumed (but never checked) that the initialization information is | |
576 | identical, and that the new file simply contains further events of | |
577 | exactly the same kind as the previous one. An example of this possibility, | |
578 | and the option to mix with internal processes, is found in | |
579 | <code>main12.cc</code>. A variant, based on input in a command file, | |
580 | is given in <code>main13.cc</code>. | |
581 | ||
582 | <p/> | |
583 | In C++, real numbers are printed with an 'E' to denote the exponent part, | |
584 | e.g. 1.23E+04, and are read in accordingly. Other languges may use other | |
585 | letters, e.g. Fortran allows either 'E' or 'D'. A file using | |
586 | the latter convention would not be readable by the standard routines. | |
587 | In case you have such an "incorrectly formatted" file, a conversion to | |
588 | a new corrected file could be done e.g. using <code>sed</code>, as a | |
589 | one-line command | |
590 | <pre> | |
591 | sed -e 's/\([0-9]\.\{0,1\}\)[dD]\([+-]\{0,1\}[0-9]\)/\1E\2/g' old.lhe > new.lhe | |
592 | </pre> | |
593 | This replaces a 'd' or 'D' with an 'E' only when it occurs in the combination | |
594 | <br/><i>(digit) ('.' or absent) ('d' or 'D') ('+', '-' or absent) (digit)</i> | |
595 | <br/>It will work on all parts of the file, also inside a | |
596 | <code><header>...</header></code> block. For conversion only | |
597 | inside the <code><init>...</init></code> and | |
598 | <code><event>...</event></code> blocks, create a file | |
599 | <code>convert.sed</code> containing | |
600 | <pre> | |
601 | /<init>/,/<\/init>/bconv | |
602 | /<event>/,/<\/event>/bconv | |
603 | b | |
604 | :conv | |
605 | s/\([0-9]\.\{0,1\}\)[dD]\([+-]\{0,1\}[0-9]\)/\1E\2/g | |
606 | </pre> | |
607 | and run it with | |
608 | <pre> | |
609 | sed -f convert.sed old.lhe > new.lhe | |
610 | </pre> | |
611 | ||
612 | <p/> | |
613 | The workhorses of the <code>LHAupLHEF</code> class are three methods | |
614 | found in the base class, so as to allow them to be reused in other | |
615 | contexts. Specifically, it allows derived classes where one parton-level | |
616 | configuration can be reused several times, e.g. in the context of | |
617 | matrix-element-to-parton-shower matching (example in preparation). | |
618 | Also two small utility routines. | |
619 | ||
620 | <a name="method32"></a> | |
621 | <p/><strong>bool LHAup::setInitLHEF(ifstream& is, bool readHeaders = false) </strong> <br/> | |
622 | read in and set all required initialization information from the | |
623 | specified stream. With second argument true it will also read and store | |
624 | header information, as described above. Return false if it fails. | |
625 | ||
626 | ||
627 | <a name="method33"></a> | |
628 | <p/><strong>bool LHAup::setNewEventLHEF(ifstream& is) </strong> <br/> | |
629 | read in event information from the specified stream into a staging area | |
630 | where it can be reused by <code>setOldEventLHEF</code>. | |
631 | ||
632 | ||
633 | <a name="method34"></a> | |
634 | <p/><strong>bool LHAup::setOldEventLHEF() </strong> <br/> | |
635 | store the event information from the staging area into the normal | |
636 | location. Thus a single <code>setNewEventLHEF</code> call can be | |
637 | followed by several <code>setOldEventLHEF</code> ones, so as to | |
638 | process the same configuration several times. This method currently | |
639 | only returns true, i.e. any errors should be caught by the preceding | |
640 | <code>setNewEventLHEF</code> call. | |
641 | ||
642 | ||
643 | <a name="method35"></a> | |
644 | <p/><strong>bool LHAup::fileFound() </strong> <br/> | |
645 | always returns true in the base class, but in <code>LHAupLHEF</code> | |
646 | it returns false if the LHEF provided in the constructor is not | |
647 | found and opened correctly. | |
648 | ||
649 | ||
650 | <a name="method36"></a> | |
651 | <p/><strong>void LHAup::setInfoHeader(const string &key, const string &val) </strong> <br/> | |
652 | is used to send header information on to the <code>Info</code> class. | |
653 | ||
654 | ||
655 | <p/> | |
656 | A few other methods, most of them derived from the base class, | |
657 | streamlines file opening and closing, e.g. if several LHE files are | |
658 | to be read consecutively, without the need for a complete | |
659 | reinitialization. This presupposes that the events are of the same | |
660 | kind, only split e.g. to limit file sizes. | |
661 | ||
662 | <a name="method37"></a> | |
663 | <p/><strong>bool LHAup::newEventFile(const char* fileIn) </strong> <br/> | |
664 | close current event input file/stream and open a new one, to | |
665 | continue reading events of the same kind as before. | |
666 | ||
667 | ||
668 | <a name="method38"></a> | |
669 | <p/><strong>istream* LHAup::openFile(const char *fn, ifstream &ifs) </strong> <br/> | |
670 | ||
671 | <strong>void LHAup::closeFile(istream *&is, ifstream &ifs) </strong> <br/> | |
672 | open and close a file, also gzip files, where an intermediate | |
673 | decompression layer is needed. | |
674 | ||
675 | ||
676 | <a name="method39"></a> | |
677 | <p/><strong>void LHAupLHEF::closeAllFiles() </strong> <br/> | |
678 | close main event file (LHEF) and, if present, separate header file. | |
679 | ||
680 | ||
681 | <h3>A runtime Fortran interface</h3> | |
682 | ||
683 | The runtime Fortran interface requires linking to an external Fortran | |
684 | code. In order to avoid problems with unresolved external references | |
685 | when this interface is not used, the code has been put in a separate | |
686 | <code>LHAFortran.h</code> file, that is not included in any of the | |
687 | other library files. Instead it should be included in the | |
688 | user-supplied main program, together with the implementation of two | |
689 | methods below that call the Fortran program to do its part of the job. | |
690 | ||
691 | <p/> | |
692 | The <code>LHAupFortran</code> class derives from <code>LHAup</code>. | |
693 | It reads initialization and event information from the LHA standard | |
694 | Fortran commonblocks, assuming these commonblocks behave like two | |
695 | <code>extern "C" struct</code> named <code>heprup_</code> and | |
696 | <code>hepeup_</code>. (Note the final underscore, to match how the | |
697 | gcc compiler internally names Fortran files.) | |
698 | ||
699 | <p/> | |
700 | The instantiation does not require any arguments. | |
701 | ||
702 | <p/> | |
703 | The user has to supply implementations of the <code>fillHepRup()</code> | |
704 | and <code>fillHepEup()</code> methods, that is to do the actual calling | |
705 | of the external Fortran routines that fill the <code>HEPRUP</code> and | |
706 | <code>HEPEUP</code> commonblocks. The translation of this information to | |
707 | the C++ structure is provided by the existing <code>setInit()</code> and | |
708 | <code>setEvent()</code> code. | |
709 | ||
710 | <p/> | |
711 | Up to and including version 8.125 the <code>LHAupFortran</code> class | |
712 | was used to construct a runtime interface to PYTHIA 6.4. This was | |
713 | convenient in the early days of PYTHIA 8 evolution, when this program | |
714 | did not yet contain hard-process generation, and the LHEF standard | |
715 | did not yet exist. Nowadays it is more of a bother, since a full | |
716 | cross-platform support leads to many possible combinations. Therefore | |
717 | the support has been reduced in the current version. Only the | |
718 | <code>main91.cc</code> example remains as an illustration, where the | |
719 | previously separate interface code | |
720 | (<code>include/Pythia6Interface.h</code>) has been inserted in the | |
721 | beginning. You also need to modify the <code>examples/Makefile</code> | |
722 | to link <code>main91.cc</code> properly also to a PYTHIA 6.4 library | |
723 | version, see commented-out section for ideas how to to this. | |
724 | ||
725 | <h3>Methods for LHEF output</h3> | |
726 | ||
727 | The main objective of the <code>LHAup</code> class is to feed information | |
728 | from an external program into PYTHIA. It can be used to export information | |
729 | as well, however. Specifically, there are four routines in the base class | |
730 | that can be called to write a Les Houches Event File. These should be | |
731 | called in sequence in order to build up the proper file structure. | |
732 | ||
733 | <a name="method40"></a> | |
734 | <p/><strong>bool LHAup::openLHEF(string filename) </strong> <br/> | |
735 | Opens a file with the filename indicated, and writes a header plus a brief | |
736 | comment with date and time information. | |
737 | ||
738 | ||
739 | <a name="method41"></a> | |
740 | <p/><strong>bool LHAup::initLHEF() </strong> <br/> | |
741 | Writes initialization information to the file above. Such information should | |
742 | already have been set with the methods described in the "Initialization" | |
743 | section above. | |
744 | ||
745 | ||
746 | <a name="method42"></a> | |
747 | <p/><strong>bool LHAup::eventLHEF(bool verbose = true) </strong> <br/> | |
748 | Writes event information to the file above. Such information should | |
749 | already have been set with the methods described in the "Event input" | |
750 | section above. This call should be repeated once for each event to be | |
751 | stored. By default the event information is lined up in columns. | |
752 | To save space, the alternative <code>verbose = false</code> only | |
753 | leaves a single blank between the information fields. | |
754 | ||
755 | ||
756 | <a name="method43"></a> | |
757 | <p/><strong>bool LHAup::closeLHEF(bool updateInit = false) </strong> <br/> | |
758 | Writes the closing tag and closes the file. Optionally, if | |
759 | <code>updateInit = true</code>, this routine will reopen the file from | |
760 | the beginning, rewrite the same header as <code>openLHEF()</code> did, | |
761 | and then call <code>initLHEF()</code> again to overwrite the old | |
762 | information. This is especially geared towards programs, such as PYTHIA | |
763 | itself, where the cross section information is not available at the | |
764 | beginning of the run, but only is obtained by Monte Carlo integration | |
765 | in parallel with the event generation itself. Then the | |
766 | <code>setXSec( i, xSec)</code>, <code>setXErr( i, xSec)</code> and | |
767 | <code>setXMax( i, xSec)</code> can be used to update the relevant | |
768 | information before <code>closeLHEF</code> is called. | |
769 | <br/><b>Warning:</b> overwriting the beginning of a file without | |
770 | upsetting anything is a delicate operation. It only works when the new | |
771 | lines require exactly as much space as the old ones did. Thus, if you add | |
772 | another process in between, the file will be corrupted. | |
773 | ||
774 | ||
775 | <h3>PYTHIA 8 output to an LHEF</h3> | |
776 | ||
777 | The above methods could be used by any program to write an LHEF. | |
778 | For PYTHIA 8 to do this, a derived class already exists, | |
779 | <code>LHAupFromPYTHIA8</code>. In order for it to do its job, | |
780 | it must gain access to the information produced by PYTHIA, | |
781 | specifically the <code>process</code> event record and the | |
782 | generic information stored in <code>info</code>. Therefore, if you | |
783 | are working with an instance <code>pythia</code> of the | |
784 | <code>Pythia</code> class, you have to instantiate | |
785 | <code>LHAupFromPYTHIA8</code> with pointers to the | |
786 | <code>process</code> and <code>info</code> objects of | |
787 | <code>pythia</code>: | |
788 | <br/><code>LHAupFromPYTHIA8 myLHA(&pythia.process, &pythia.info);</code> | |
789 | ||
790 | <p/> | |
791 | The method <code>setInit()</code> should be called to store the | |
792 | <code>pythia</code> initialization information in the LHA object, | |
793 | and <code>setEvent()</code> to store event information. | |
794 | Furthermore, <code>updateSigma()</code> can be used at the end | |
795 | of the run to update cross-section information, cf. | |
796 | <code>closeLHEF(true)</code> above. An example how the | |
797 | generation, translation and writing methods should be ordered is | |
798 | found in <code>main20.cc</code>. | |
799 | ||
800 | <p/> | |
801 | Currently there are some limitations, that could be overcome if | |
802 | necessary. Firstly, you may mix many processes in the same run, | |
803 | but the cross-section information stored in <code>info</code> only | |
804 | refers to the sum of them all, and therefore they are all classified | |
805 | as a common process 9999. Secondly, you should generate your events | |
806 | in the CM frame of the collision, since this is the assumed frame of | |
807 | stored Les Houches events, and no boosts have been implemented | |
808 | for the case that <code>Pythia::process</code> is not in this frame. | |
809 | ||
810 | <p/> | |
811 | The LHEF standard is the agreed format to store the particles of a | |
812 | hard process, as input to generators, whereas output of final states | |
813 | is normally handled using the <a href="HepMCInterface.html" target="page">HepMC</a> | |
814 | standard. It is possible to use LHEF also here, however. It requires | |
815 | that the above initialization is replaced by | |
816 | <br/><code>LHAupFromPYTHIA8 myLHA(&pythia.event, &pythia.info);</code> | |
817 | <br/> i.e. that <code>process</code> is replaced by <code>event</code>. | |
818 | In addition, the <code>PartonLevel:all = off</code> command found in | |
819 | <code>main20.cc</code> obviously must be removed if one wants to | |
820 | obtain complete events. | |
821 | ||
822 | </body> | |
823 | </html> | |
824 | ||
825 | <!-- Copyright (C) 2012 Torbjorn Sjostrand --> |