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 --> |
---|