[1] | 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 --> |
---|