PYTHIA8/pythia8170/htmldoc/HadronLevelStandalone.html

   1 <html>
   2 <head>
   3 <title>Hadron-Level Standalone</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>Hadron-Level Standalone</h2>
  10
  11 The Les Houches Accord allows external process-level configurations
  12 to be fed in, for subsequent parton-level and hadron-level generation
  13 to be handled internally by PYTHIA. There is no correspondingly
  14 standardized interface if you have external events that have also
  15 been generated through the parton-level stage, so that only the
  16 hadron-level remains to be handled. A non-standard way to achieve this
  17 exists, however, and can be useful both for real applications and
  18 for various tests of the hadronization model on its own.
  19
  20 <p/>
  21 The key trick is to set the flag <code>ProcessLevel:all = off</code>.
  22 When <code>pythia.next()</code> is called it then does not try to
  23 generate a hard process. Since there are no beams, it is also not
  24 possible to perform the normal <code>PartonLevel</code> step.
  25 (It is still possible to generate final-state radiation, but this
  26 is not automatic. It would have to be done by hand, using the
  27 <code>pythia.forceTimeShower(...)</code> method, before
  28 <code>pythia.next()</code> is called.)
  29 Thus only the <code>HadronLevel</code> methods are
  30 called, to take the current content of the event record stored in
  31 <code>pythia.event</code> as a starting point for any hadronization
  32 and decays that are allowed by the normal parameters of this step.
  33 Often the input would consist solely of partons grouped into colour
  34 singlets, but also (colour-singlet) particles are allowed.
  35
  36 <p/>
  37 To set up all the parameters, a <code>pythia.init()</code> call has
  38 to be used, without any arguments. In brief, the structure of the
  39 main program therefore should be something like
  40 <pre>
  41   Pythia pythia;                               // Declare generator.
  42   Event& event = pythia.event                  // Convenient shorthand.
  43   pythia.readString("ProcessLevel:all = off"); // The trick!
  44   pythia.init();                               // Initialization.
  45   for (int iEvent = 0; iEvent < nEvent; ++iEvent) {
  46     // Insert filling of event here!
  47     pythia.next();                             // Do the hadron level.
  48   }
  49 </pre>
  50 Of course this should be supplemented by analysis of events, error checks,
  51 and so on, as for a normal PYTHIA run. The unique aspect is how to fill
  52 the <code>event</code> inside the loop, before <code>pythia.next()</code>
  53 is called.
  54
  55 <h3>Input configuration</h3>
  56
  57 To set up a new configuration the first step is to throw away the current
  58 one, with <code>event.reset()</code>. This routine will also reserve
  59 the zeroth entry in the even record to represent the event as a whole.
  60
  61 <p/>
  62 With the <code>event.append(...)</code> methods a new entry is added at the
  63 bottom of the current record, i.e. the first time it is called entry
  64 number 1 is filled, and so on. The <code>append</code>  method basically
  65 exists in four variants, either without or with history information,
  66 and with four-momentum provided either as a <code>Vec4</code> four-vector
  67 or as four individual components:
  68 <pre>
  69   append( id, status, col, acol, p, m)
  70   append( id, status, col, acol, px, py, pz, e, m)
  71   append( id, status, mother1, mother2, daughter1, daughter2, col, acol, p, m)
  72   append( id, status, mother1, mother2, daughter1, daughter2, col, acol, px, py, pz, e, m)
  73 </pre>
  74 The methods return the index at which the entry has been stored,
  75 but normally you would not use this feature.
  76
  77 <p/>
  78 You can find descriptions of the input variables
  79 <a href="ParticleProperties.html" target="page">here</a>.
  80 The PDG particle code <code>id</code> and the Les Houches Accord colour
  81 <code>col</code> and anticolour <code>acol</code> tags must be set
  82 correctly. The four-momentum and mass have to be provided in units of GeV;
  83 if you omit the mass it defaults to 0.
  84
  85 <p/>
  86 Outgoing particles that should hadronize should be given status code 23.
  87 Often this is the only status code you need. You could e.g. also fill in
  88 incoming partons with -21 and intermediate ones with -22, if you so wish.
  89 Usually the choice of status codes is not crucial, so long as you recall
  90 that positive numbers correspond to particles that are still around, while
  91 negative numbers denote ones that already hadronized or decayed. However,
  92 so as not to run into contradictions with the internal PYTHIA checks
  93 (when <code>Check:event = on</code>), or with external formats such as
  94 HepMC, we do recommend the above codes. When <code>pythia.next()</code>
  95 is called the positive-status particles that hadronize/decay get the sign
  96 of the status code flipped to negative but the absolute value is retained.
  97 The new particles are added with normal PYTHIA status codes.
  98
  99 <p/>
 100 For normal hadronization/decays in <code>pythia.next()</code> the
 101 history encoded in the mother and daughter indices is not used.
 102 Therefore the first two <code>append</code> methods, which set all these
 103 indices vanishing, should suffice. The subsequent hadronization/decays
 104 will still be properly documented.
 105
 106 <p/>
 107 The exception is when you want to include junctions in your string
 108 topology, i.e. have three string pieces meet. Then you must insert in
 109 your event record the (decayed) particle that is the reason for the
 110 presence of a junction, e.g. a baryon beam remnant from which several
 111 valence quarks have been kicked out, or a neutralino that underwent a
 112 baryon-number-violating decay. This particle must have as daughters
 113 the three partons that together carry the baryon number.
 114
 115 <p/>
 116 The sample program in <code>main21.cc</code> illustrates how you can work
 117 with this facility, both for simple parton configurations and for more
 118 complicated ones with junctions.
 119
 120 <p/>
 121 As an alternative to setting up a topology with the methods above,
 122 a <a href="LesHouchesAccord.html" target="page">Les Houches Event File</a> (LHEF)
 123 can also provide the configurations. Since no beams or processes are
 124 defined, only the <code>&lt;event&gt;....&lt;/event&gt;</code> blocks
 125 need to be present, one for each event, so strictly it is not a true
 126 LHEF. You need to select <code>Beams:frameType = 4</code>, provide
 127 the file name in <code>Beams:LHEF</code> and, as above, set
 128 <code>ProcessLevel:all = off</code>. Needless to say, an externally
 129 linked <code>LHAup</code> class works as well as an LHEF,
 130 with <code>Beams:frameType = 5</code>.
 131
 132 <p/>
 133 The event information to store in the LHEF, or provide by the
 134 <code>LHAup</code>, is essentially the same as above. The only
 135 difference is in status codes: outgoing particles should have 1
 136 instead of 23, and intermediate resonances 2 instead of -22.
 137 Incoming partons, if any, are -1 instead of -21.
 138
 139 <h3>Extensions to resonance decays</h3>
 140
 141 With the above scheme, <code>pythia.next()</code> will generate
 142 hadronization, i.e. string fragmentation and subsequent decays of
 143 normal unstable particles. It will not decay
 144 <a href="ResonanceDecays.html" target="page">resonances</a>, i.e.
 145 <i>W, Z</i>, top, Higgs, SUSY and other massive particles.
 146
 147 <p/>
 148 If the decay products are already provided, of course those
 149 products will be hadronized, but without any of the showers
 150 that one would expect in <i>Z^0 -> q qbar</i>, say. That is, the
 151 presence of a decayed resonance in the event record can be nice
 152 for documentation purposes, but otherwise it plays no role.
 153 It is possible to change this behaviour with the following flag.
 154
 155 <p/><code>flag&nbsp; </code><strong> Standalone:allowResDec &nbsp;</strong>
 156  (<code>default = <strong>off</strong></code>)<br/>
 157 If off, then resonances are stable if final-state particles,
 158 and irrelevant if intermediate particles. If on, then
 159 resonances are decayed, sequentially if necessary. After each
 160 decay step a parton shower is applied, and subsequent decay
 161 kinematics is shifted by the recoil of such branchings.
 162 If the decay chain and kinematics of the resonance is provided
 163 at input, this information is used, otherwise it is generated
 164 internally according to built-in branching ratios etc.
 165
 166
 167 <p/>
 168 The input configuration has to follow the rules described above,
 169 with <code>ProcessLevel:all = off</code>. (Terminology not quite
 170 consistent, since resonance decays normally is part of the
 171 process-level step.) It is possible to combine several resonances,
 172 and other coloured or uncoloured particles into the same event.
 173
 174 <p/>
 175 Final-state radiation is applied to each step of the decay
 176 sequence by default, but can be switched off with
 177 <code>PartonLevel:FSR = off</code> or
 178 <code>PartonLevel:FSRinResonances</code>.
 179
 180 <h3>Repeated hadronization or decay</h3>
 181
 182 An alternative approach is possible with the
 183 <code>pythia.forceHadronLevel()</code> routine. This method does
 184 a call to the <code>HadronLevel</code> methods, irrespective of the
 185 value of the <code>HadronLevel:all</code> flag. If you hadronize
 186 externally generated events it is equivalent to a
 187 <code>pythia.next()</code> call with
 188 <code>ProcessLevel:all = off</code>.
 189
 190 <p/>
 191 This method truly sticks to the hadron level, and thus cannot handle
 192 resonance decays. You therefore <b>must not</b> mix it with the
 193 <code>Standalone:allowResDec = on</code> framework.
 194
 195 <p/>
 196 The similarity of names indicates that
 197 <code>pythia.forceTimeShower( int iBeg, int iEnd, double pTmax,
 198 int nBranchMax = 0)</code> is intended to belong to the same set of
 199 work-by-hand methods. Here <code>iBeg</code> and <code>iEnd</code>
 200 give the range of partons that should be allowed to shower,
 201 <code>pTmax</code> the maximum <i>pT</i> scale of emissions,
 202 and a nonzero <code>nBranchMax</code> a maximum number of allowed
 203 branchings. Additionally, a <code>scale</code> has to be set for each
 204 parton that should shower, which requires an additional final argument
 205 to the <code>append</code> methods above. This scale limits the maximum
 206 <i>pT</i> allowed for each parton, in addition to the global
 207 <code>pTmax</code>. When not set the scale defaults to 0, meaning no
 208 radiation for that parton.
 209
 210 <p/>
 211 The real application instead is for repeated hadronization of the same
 212 PYTHIA process- and parton-level event. This may for some studies
 213 help to save time, given that these two first step are more
 214 time-consuming than the hadronization one.
 215
 216 <p/>
 217 For repeated hadronization you should first generate an event as usual,
 218 but with <code>HadronLevel:all = off</code>. This event you can save
 219 in a temporary copy, e.g. <code>Event savedEvent = pythia.event</code>.
 220 Inside a loop you copy back with <code>pythia.event = savedEvent</code>,
 221 and call <code>pythia.forceHadronLevel()</code> to obtain a new
 222 hadronization history.
 223
 224 <p/>
 225 A more limited form of repetition is if you want to decay a given kind
 226 of particle repeatedly, without having to generate the rest of the event
 227 anew. This could be the case e.g. in <i>B</i> physics applications.
 228 Then you can use the <code>pythia.moreDecays()</code> method, which
 229 decays all particles in the event record that have not been decayed
 230 but should have been done so. The
 231 <code>pythia.particleData.mayDecay( id, false/true)</code> method
 232 may be used to switch off/on the decays of a particle species
 233 <code>id</code>, so that it is not decayed in the
 234 <code>pythia.next()</code> call but only inside a loop over a number of
 235 tries.
 236
 237 <p/>
 238 Between each loop the newly produced decay products must be
 239 removed and the decayed particle status restored to undecayed.
 240 The former is simple, since the new products are appended to the
 241 end of the event record: <code>event.saveSize()</code> saves the
 242 initial size of the event record, and <code>event.restoreSize()</code>
 243 can later be used repeatedly to restore this original size, which means
 244 that the new particles at the end are thrown away. The latter is more
 245 complicated, and requires the user to identify the positions of all
 246 particles of the species and restore a positive status code with
 247 <code>event[i].statusPos()</code>.
 248
 249 <p/>
 250 The <code>main15.cc</code> program illustrates both these methods,
 251 i.e. either repeated hadronization or repeated decay of PYTHIA
 252 events.
 253
 254 </body>
 255 </html>
 256
 257 <!-- Copyright (C) 2012 Torbjorn Sjostrand -->