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