PYTHIA8/pythia8145/htmldoc/UserHooks.html

   1 <html>
   2 <head>
   3 <title>User Hooks</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>User Hooks</h2>
  10
  11 Sometimes it may be convenient to step in during the generation
  12 process: to modify the built-in cross sections, to veto undesirable
  13 events or simply to collect statistics at various stages of the
  14 evolution. There is a base class <code>UserHooks</code> that gives
  15 you this access at a few selected places. This class in itself does
  16 nothing; the idea is that you should write your own derived class
  17 for your task. One simple derived class (<code>SuppressSmallPT</code>)
  18 comes with the program, mainly as illustration, and the
  19 <code>main10.cc</code> program provides a complete (toy) example how
  20 a derived class could be set up and used.
  21
  22 <p/>
  23 There are six sets of routines, that give you different kinds of
  24 freedom. They are, in no particular order:
  25 <br/>(i) Ones that give you access to the event record in between
  26 the process-level and parton-level steps, or in between the
  27 parton-level and hadron-level ones. You can study the event record
  28 and decide whether to veto this event.
  29 <br/>(ii) Ones that allow you to set a scale at which the combined
  30 parton-level MI+ISR+FSR downwards evolution in <i>pT</i> is
  31 temporarily interrupted, so the event can be studied and either
  32 vetoed or allowed to continue the evolution.
  33 <br/>(iii) Ones that allow you to to study the event after the first
  34 few ISR/FSR emissions, or first few MI, so the event can be vetoed
  35 or allowed to continue the evolution.
  36 <br/>(iv) Ones that allow you to study the latest initial- or
  37 final-state emission and veto that emission, without vetoing the
  38 event as a whole.
  39 <br/>(v) Ones that give you access to the properties of the trial
  40 hard process, so that you can modify the internal Pythia cross section
  41 by your own correction factors.
  42 <br/>(vi) Ones that let you set the scale of shower evolution,
  43 specifically for matching in resonance decays.
  44 <br/>They are described further in the following numbered subsections.
  45
  46 <p/>
  47 All the possibilities above can be combined freely and also be combined
  48 with the standard flags. An event would then survive only if it survived
  49 each of the possible veto methods. There are no hidden interdependencies
  50 in this game, but of course some combinations may not be particularly
  51 meaningful. For instance, if you set <code>PartonLevel:all = off</code>
  52 then the <code>doVetoPT(...)</code> and <code>doVetoPartonLevel(...)</code>
  53 locations in the code are not even reached, so they would never be called.
  54
  55 <p/>
  56 The effect of the vetoes of types (i), (ii) and (iii) can be studied
  57 in the output of the
  58 <code><a href="EventStatistics.html" target="page">Pythia::statistics()</a></code>
  59 method. The "Selected" column represents the number of events that were
  60 found acceptable by the internal Pythia machinery, whereas the "Accepted"
  61 one are the events that also survived the user cuts. The cross section
  62 is based on the latter number, and so is reduced by the amount associated
  63 by the vetoed events. Also type (v) modifies the cross section, while
  64 types (iv) and (vi) do not.
  65
  66 <h3>The basic components</h3>
  67
  68 For a derived <code>UserHooks</code> class to be called during the
  69 execution, a pointer to an object of this class should be handed in
  70 with the
  71 <br/><code><a href="ProgramFlow.html" target="page">
  72 Pythia::setUserHooksPtr( UserHooks*)</a></code>
  73 <br/>method. The first step therefore is to construct your own derived
  74 class, of course. This must contain a constructor and a destructor. The
  75 <code>initPtr</code> method comes "for free", and is set up without
  76 any intervention from you.
  77
  78 <a name="method1"></a>
  79 <p/><strong>UserHooks::UserHooks() &nbsp;</strong> <br/>
  80
  81 <strong>virtual UserHooks::~UserHooks() &nbsp;</strong> <br/>
  82 The constructor and destructor do not need to do anything.
  83
  84
  85 <a name="method2"></a>
  86 <p/><strong>void UserHooks::initPtr( Info* infoPtr, Settings* settingsPtr, ParticleData* particleDataPtr,  Rndm* rndmPtr, BeamParticle* beamAPtr, BeamParticle* beamBPtr, BeamParticle* beamPomAPtr, BeamParticle* beamPomBPtr, CoupSM* coupSMPtr, PartonSystems* partonSystemsPtr, SigmaTotal* sigmaTotPtr) &nbsp;</strong> <br/>
  87 this (non-virtual) method is automatically called during the
  88 initialization stage to set several useful pointers, and to set up
  89 the <code>workEvent</code> below. The corresponding objects can
  90 later be used to extract some useful information.
  91 <br/><a href="EventInformation.html" target="page">Info</a>:
  92 general event and run information, including some loop counters.
  93 <br/><a href="SettingsScheme.html" target="page">Settings</a>:
  94 the settings used to determine the character of the run.
  95 <br/><a href="ParticleDataScheme.html" target="page">ParticleData</a>:
  96 the particle data used in the event record
  97 (including <code>workEvent</code> below).
  98 <br/><a href="RandomNumbers.html" target="page">Rndm</a>: the random number
  99 generator, that you could also use in your code.
 100 <br/><a href="BeamRemnants.html" target="page">BeamParticle</a>:
 101 the <code>beamAPtr</code> and <code>beamBPtr</code> beam particles
 102 contain info on partons extracted from the two incoming beams,
 103 on the PDFs used, and more. In cases when diffraction is simulated,
 104 also special Pomeron beams <code>beamPomAPtr</code> and
 105 <code>beamPomBPtr</code> are introduced, for the Pomerons residing
 106 inside the respective proton.
 107 <br/><a href="StandardModelParameters.html" target="page">CoupSM</a>:
 108 Standard Model couplings.
 109 <br/><a href="AdvancedUsage.html" target="page">PartonSystems</a>:
 110 the list of partons that belong to each individual subcollision system.
 111 <br/><a href="TotalCrossSections.html" target="page">SigmaTotal</a>:
 112 total/elastic/diffractive cross section parametrizations.
 113
 114
 115 <p/>
 116 Next you overload the desired methods listed in the sections below.
 117 These often come in pairs or triplets, where the first must return
 118 true for the last method to be called. This latter method typically
 119 hands you a reference to the event record, which you then can use to
 120 decide whether or not to veto. Often the event record can be quite
 121 lengthy and difficult to overview. The following methods and data member
 122 can then come in handy.
 123
 124 <a name="method3"></a>
 125 <p/><strong>void UserHooks::omitResonanceDecays(const Event& process) &nbsp;</strong> <br/>
 126 is a protected method that you can make use of in your own methods to
 127 extract a simplified list of the hard process, where all resonance decay
 128 chains are omitted. Intended for the <code>can/doVetoProcessLevel</code>
 129 routines. Note that the normal process-level generation does include
 130 resonance decays. That is, if a top quark is produced in the hard process,
 131 then also decays such as <i>t -> b W+, W+ -> u dbar</i> will be generated
 132 and stored in <code>process</code>. The <code>omitResonanceDecays</code>
 133 routine will take the input <code>process</code> and copy it to
 134 <code>workEvent</code> (see below), minus the resonance decay chains.
 135 All particles produced in the hard process, such as the top, will be
 136 considered final-state ones, with positive status and no daughters,
 137 just as it is before resonances are allowed to decay.
 138 <br/>(In the <code>PartonLevel</code> routines, these decay chains will
 139 initially not be copied from <code>process</code> to <code>event</code>.
 140 Instead the combined MI, ISR and FSR evolution is done with the top
 141 above as final particle. Only afterwards will the resonance decay chains
 142 be copied over, with kinematics changes reflecting those of the top, and
 143 showers in the decays carried out.)
 144 <br/>
 145
 146
 147
 148 <a name="method4"></a>
 149 <p/><strong>void UserHooks::subEvent(const Event& event, bool isHardest = true) &nbsp;</strong> <br/>
 150 is a protected method that you can make use of in your own methods to
 151 extract a brief list of the current
 152 partons of interest, with all irrelevant ones omitted. For the default
 153 <code>isHardest = true</code> only the outgoing partons from the hardest
 154 interaction (including the partons added to it by ISR and FSR) are
 155 extracted, as relevant e.g. for <code>doVetoPT( iPos, event)</code> with
 156 <code>iPos = 0 - 4</code>. With <code>isHardest = false</code> instead
 157 the outgoing partons of the latest "subprocess" are extracted, as relevant
 158 when <code>iPos = 5</code>, where it corresponds to the outgoing partons
 159 in the currently considered decay. The resut is stored in
 160 <code>workEvent</code> below. The partons are stored in slots 0 through
 161 <code>workEvent.size() - 1</code>. The <code>mother1()</code> and
 162 <code>mother2()</code> indices of a particle in this list both return 0.
 163 The <code>daughter1()</code> and <code>daughter2()</code> indices both
 164 return the index of the same parton in the original event record
 165 (<code>event</code>; possibly <code>process</code>),
 166 so that you can trace the full history, if of interest.
 167
 168
 169 <a name="method5"></a>
 170 <p/><strong>Event UserHooks::workEvent &nbsp;</strong> <br/>
 171 This protected class member contains the outcome of the above
 172 <code>omitResonanceDecays(...)</code> and
 173 <code>subEvent(...)</code> methods. Alternatively you can use it for
 174 whatever temporary purposes you wish. You are free to use standard
 175 operations, e.g. to boost the event to its rest frame before analysis,
 176 or remove particles that should not be analyzed.
 177 The <code>workEvent</code> can also be sent on to a
 178 <a href="EventAnalysis.html" target="page">jet clustering algorithm</a>.
 179
 180 <h3>(i) Interrupt between the main generation levels</h3>
 181
 182 <a name="method6"></a>
 183 <p/><strong>virtual bool UserHooks::canVetoProcessLevel() &nbsp;</strong> <br/>
 184 In the base class this method returns false. If you redefine it
 185 to return true then the method <code>doVetoProcessLevel(...)</code>
 186 will be called immediately after a hard process (and associated
 187 resonance decays) has been selected and stored in the
 188 <code><a href="EventRecord.html" target="page">process</a></code> event record.
 189 <br/>At this stage, the <code>process</code> record typically contains
 190 the two beams in slots 1 and 2, the two incoming partons to the hard
 191 process in slots 3 and 4, the N (usually 1, 2 or 3) primary produced
 192 particles in slots 5 through 4 + N, and thereafter recursively the
 193 resonance decay chains, if any. Use the method
 194 <code>omitResonanceDecays(...)</code> if you want to skip these
 195 decay chains. There are exceptions to this structure,
 196 for <a href="QCDProcesses.html" target="page">soft QCD processes</a> (where
 197 the partonic process may not yet have been selected at this stage),
 198 and when <a href="ASecondHardProcess.html" target="page">a second hard process</a> has
 199 been requested (where two hard processes are bookkept). In general
 200 it is useful to begin the development work by listing a few
 201 <code>process</code> records, to clarify what the structure is for
 202 the cases of interest.
 203
 204
 205 <a name="method7"></a>
 206 <p/><strong>virtual bool UserHooks::doVetoProcessLevel(Event& process) &nbsp;</strong> <br/>
 207 can optionally be called, as described above. You can study the
 208 <code>process</code> event record of the hard process.
 209 Based on that you can decide whether to veto the event, true, or let
 210 it continue to evolve, false. If you veto, then this event is not
 211 counted among the accepted ones, and does not contribute to the estimated
 212 cross section. The <code>Pytha::next()</code> method will begin a
 213 completely new event, so the vetoed event will not appear in the
 214 output of <code>Pythia::next()</code>.
 215 <br/><b>Warning:</b> Normally you should not modify the <code>process</code>
 216 event record. However, for some matrix-element-matching procedures it may
 217 become unavoidable. If so, be very careful, since there are many pitfalls.
 218 Only to give one example: if you modify the incoming partons then also
 219 the information stored in the beam particles may need to be modified.
 220 <br/><b>Note:</b> the above veto is different from setting the flag
 221 <code><a href="MasterSwitches.html" target="page">PartonLevel:all = off</a></code>.
 222 Also in the latter case the event generation will stop after the process
 223 level, but an event generated up to this point is considered perfectly
 224 acceptable. It can be studied and it contributes to the cross section.
 225 That is, <code>PartonLevel:all = off</code> is intended for simple studies
 226 of hard processes, where one can save a lot of time by not generating
 227 the rest of the story. By contrast, the <code>doVetoProcessLevel()</code>
 228 method allows you to throw away uninteresting events at an early stage
 229 to save time, but those events that do survive the veto are allowed to
 230 develop into complete final states (unless flags have been set otherwise).
 231
 232
 233 <a name="method8"></a>
 234 <p/><strong>virtual bool UserHooks::canVetoPartonLevel() &nbsp;</strong> <br/>
 235 In the base class this method returns false. If you redefine it
 236 to return true then the method <code>doVetoPartonLevel(...)</code>
 237 will be called immediately after the parton level has been generated
 238 and stored in the <code><a href="EventRecord.html" target="page">event</a></code>
 239 event record. Thus showers, multiple interactions and beam remnants
 240 have been set up, but hadronization and decays have not yet been
 241 performed. This is already a fairly complete event, possibly with quite
 242 a complex parton-level history. Therefore it is usually only meaningful
 243 to study the hardest interaction, e.g. using <code>subEvent(...)</code>
 244 introduced above, or fairly generic properties, such as the parton-level
 245 jet structure.
 246
 247
 248 <a name="method9"></a>
 249 <p/><strong>virtual bool UserHooks::doVetoPartonLevel(const Event& event) &nbsp;</strong> <br/>
 250 can optionally be called, as described above. You can study, but not
 251 modify, the <code>event</code> event record of the partonic process.
 252 Based on that you can decide whether to veto the event, true, or let
 253 it continue to evolve, false. If you veto, then this event is not
 254 counted among the accepted ones, and does not contribute to the estimated
 255 cross section. The <code>Pytha::next()</code> method will begin a
 256 completely new event, so the vetoed event will not appear in the
 257 output of <code>Pythia::next()</code>.
 258 <br/><b>Note:</b> the above veto is different from setting the flag
 259 <code><a href="MasterSwitches.html" target="page">HadronLevel:all = off</a></code>.
 260 Also in the latter case the event generation will stop after the parton
 261 level, but an event generated up to this point is considered perfectly
 262 acceptable. It can be studied and it contributes to the cross section.
 263 That is, <code>HadronLevel:all = off</code> is intended for simple
 264 studies of complete partonic states, where one can save time by not
 265 generating the complete hadronic final state. By contrast, the
 266 <code>doVetoPartonLevel()</code> method allows you to throw away
 267 uninteresting events to save time that way, but those events that
 268 do survive the veto are allowed to develop into complete final states
 269 (unless flags have been set otherwise).
 270
 271
 272 <h3>(ii) Interrupt during the parton-level evolution, at a
 273 <i>pT</i> scale</h3>
 274
 275 During the parton-level evolution, multiple interactions (MI),
 276 initial-state radiation (ISR) and final-state radiation (FSR)
 277 are normally evolved downwards in
 278 one interleaved evolution sequence of decreasing <i>pT</i> values.
 279 For some applications, e.g  matrix-element-matching approaches, it
 280 may be convenient to stop the evolution temporarily when the "hard"
 281 emissions have been considered, but before continuing with the more
 282 time-consuming soft activity. Based on these hard partons one can make
 283 a decision whether the event at all falls in the intended event class,
 284 e.g. has the "right" number of parton-level jets. If yes then, as for
 285 the methods above, the evolution will continue all the way up to a
 286 complete event. Also as above, if no, then the event will not be
 287 considered in the final cross section.
 288
 289 <p/>
 290 Recall that the new or modified partons resulting from a MI, ISR or FSR
 291 step are always appended to the end of the then-current event record.
 292 Previously existing partons are not touched, except for the
 293 <a href="ParticleProperties.html" target="page">status, mother and daughter</a>
 294 values, which are updated to reflect the modified history. It is
 295 therefore straightforward to find the partons associated with the most
 296 recent occurence.
 297 <br/>An MI results in four new partons being appended, two incoming
 298 and two outgoing ones.
 299 <br/>An ISR results in the whole affected system being copied down,
 300 with one of the two incoming partons being replaced by a new one, and
 301 one more outgoing parton.
 302 <br/>An FSR results in three new partons, two that come from the
 303 branching and one that takes the recoil.
 304 <br/>The story becomes more messy when rescattering is allowed as part
 305 of the MI machinery. Then there will not only be a new system, as
 306 outlined above, but additionally some existing systems will undergo
 307 cascade effects, and be copied down with changed kinematics.
 308
 309 <p/>
 310 In this subsection we outline the possibility to interrupt at a given
 311 <i>pT</i> scale, in the next to interrupt after a given number of
 312 emissions.
 313
 314 <a name="method10"></a>
 315 <p/><strong>virtual bool UserHooks::canVetoPT() &nbsp;</strong> <br/>
 316 In the base class this method returns false. If you redefine it
 317 to return true then the method <code>doVetoPT(...)</code> will
 318 interrupt the downward evolution at <code>scaleVetoPT()</code>.
 319
 320 <a name="method11"></a>
 321 <p/><strong>virtual double UserHooks::scaleVetoPT() &nbsp;</strong> <br/>
 322 In the base class this method returns 0. You should redefine it
 323 to return the <i>pT</i> scale at which you want to study the event.
 324
 325
 326 <a name="method12"></a>
 327 <p/><strong>virtual bool UserHooks::doVetoPT(int iPos, const Event& event) &nbsp;</strong> <br/>
 328 can optionally be called, as described above. You can study, but not
 329 modify, the <code>event</code> event record of the partonic process.
 330 Based on that you can decide whether to veto the event, true, or let
 331 it continue to evolve, false. If you veto, then this event is not
 332 counted among the accepted ones, and does not contribute to the estimated
 333 cross section. The <code>Pytha::next()</code> method will begin a
 334 completely new event, so the vetoed event will not appear in the
 335 output of <code>Pythia::next()</code>.
 336 <br/><code>argument</code><strong> iPos </strong>  :  is the position/status when the routine is
 337 called, information that can help you decide your course of action:
 338 <br/><code>argumentoption </code><strong> 0</strong> :  when no MI, ISR or FSR occured above the veto scale;
 339
 340 <br/><code>argumentoption </code><strong> 1</strong> :  when inside the interleaved MI + ISR + FSR evolution,
 341 after an MI process;
 342
 343 <br/><code>argumentoption </code><strong> 2</strong> :  when inside the interleaved MI + ISR + FSR evolution,
 344 after an ISR emission;
 345
 346 <br/><code>argumentoption </code><strong> 3</strong> :  when inside the interleaved MI + ISR + FSR evolution,
 347 after an FSR emission;
 348
 349 <br/><code>argumentoption </code><strong> 4</strong> :  for the optional case where FSR is deferred from the
 350 interleaved evolution and only considered separately afterward (then
 351 alternative 3 would never occur);
 352
 353 <br/><code>argumentoption </code><strong> 5</strong> :  is for subsequent resonance decays, and is called once
 354 for each decaying resonance in a chain such as <i>t -> b W, W -> u dbar</i>.
 355
 356
 357 <br/><code>argument</code><strong> event </strong>  :  the event record contains a list of all partons
 358 generated so far, also including intermediate ones not part of the
 359 "current final state", and also those from further multiple interactions.
 360 This may not be desirable for comparisons with matrix-element calculations.
 361 You may want to make use of the <code>subEvent(...)</code> method below to
 362 obtain a simplified event record <code>workEvent</code>.
 363
 364
 365
 366 <h3>(iii) Interrupt during the parton-level evolution, after a step</h3>
 367
 368 These options are closely related to the ones above in section (ii), so
 369 we do not repeat the introduction, nor the possibilities to study the
 370 event record, also by using <code>subEvent(...)</code> and
 371 <code>workEvent</code>.
 372 What is different is that the methods in this section give access to the
 373 event as it looks like after each of the first few steps in the downwards
 374 evolution, irrespectively of the <i>pT</i> scales of these branchings.
 375 Furthermore, it is here assumed that the focus normally is on the hardest
 376 subprocess, so that ISR/FSR emissions associated with additional MI's
 377 are not considered. For MI studies, however, a separate simpler
 378 alternative is offered to consider the event after a given number
 379 of interactions.
 380
 381 <a name="method13"></a>
 382 <p/><strong>virtual bool UserHooks::canVetoStep() &nbsp;</strong> <br/>
 383 In the base class this method returns false. If you redefine it
 384 to return true then the method <code>doVetoStep(...)</code> will
 385 interrupt the downward ISR and FSR evolution the first
 386 <code>numberVetoStep()</code> times.
 387
 388 <a name="method14"></a>
 389 <p/><strong>virtual int UserHooks::numberVetoStep() &nbsp;</strong> <br/>
 390 Returns the number of steps <i>n</i> each of ISR and FSR, for the
 391 hardest interaction, that you want to be able to study. That is,
 392 the method will be called after the first <i>n</i> ISR emissions,
 393 irrespective of the number of FSR ones at the time, and after the
 394 first <i>n</i> FSR emissions, irespective of the number of ISR ones.
 395 The number of steps defaults to the first one only, but you are free
 396 to pick another value. Note that double diffraction is handled as two
 397 separate Pomeron-proton collisions, and thus has two sequences of
 398 emissions.
 399
 400
 401 <a name="method15"></a>
 402 <p/><strong>virtual bool UserHooks::doVetoStep(int iPos, int nISR, int nFSR, const Event& event) &nbsp;</strong> <br/>
 403 can optionally be called, as described above. You can study, but not
 404 modify, the <code>event</code> event record of the partonic process.
 405 Based on that you can decide whether to veto the event, true, or let
 406 it continue to evolve, false. If you veto, then this event is not
 407 counted among the accepted ones, and does not contribute to the estimated
 408 cross section. The <code>Pytha::next()</code> method will begin a
 409 completely new event, so the vetoed event will not appear in the
 410 output of <code>Pythia::next()</code>.
 411 <br/><code>argument</code><strong> iPos </strong>  :  is the position/status when the routine is
 412 called, information that can help you decide your course of action.
 413 Agrees with options 2 - 5 of the <code>doVetoPT(...)</code> routine
 414 above, while options 0 and 1 are not relevant here.
 415
 416 <br/><code>argument</code><strong> nISR </strong>  :  is the number of ISR emissions in the hardest
 417 process so far. For resonance decays, <code>iPos = 5</code>, it is 0.
 418
 419 <br/><code>argument</code><strong> nFSR </strong>  :  is the number of FSR emissions in the hardest
 420 process so far. For resonance decays, <code>iPos = 5</code>, it is the
 421 number of emissions in the currently studied system.
 422
 423 <br/><code>argument</code><strong> event </strong>  :  the event record contains a list of all partons
 424 generated so far, also including intermediate ones not part of the
 425 "current final state", and also those from further multiple interactions.
 426 This may not be desirable for comparisons with matrix-element calculations.
 427 You may want to make use of the <code>subEvent(...)</code> method above to
 428 obtain a simplified event record.
 429
 430
 431
 432 <a name="method16"></a>
 433 <p/><strong>virtual bool UserHooks::canVetoMIStep() &nbsp;</strong> <br/>
 434 In the base class this method returns false. If you redefine it
 435 to return true then the method <code>doVetoMIStep(...)</code> will
 436 interrupt the downward MI evolution the first
 437 <code>numberVetoMIStep()</code> times.
 438
 439 <a name="method17"></a>
 440 <p/><strong>virtual int UserHooks::numberVetoMIStep() &nbsp;</strong> <br/>
 441 Returns the number of steps in the MI evolution that you want to be
 442 able to study, right after each new step has been taken and the
 443 subcollision has been added to the event record. The number of steps
 444 defaults to the first one only, but you are free to pick another value.
 445 Note that the hardest interaction of an events counts as the first
 446 multiple interaction. For most hard processes it thus at the first
 447 step offers nothing not available with the <code>VetoProcessLevel</code>
 448 functionality above. For the minimum-bias and diffractive systems the
 449 hardest interaction is not selected at the process level, however, so
 450 there a check after the first multiple interaction offers new
 451 functionality. Note that double diffraction is handled as two separate
 452 Pomeron-proton collisions, and thus has two sequences of interactions.
 453 Also, if you have set up a second hard process then a check is made
 454 after these first two, and the first interaction coming from the MI
 455 machinery would have sequence number 3.
 456
 457
 458 <a name="method18"></a>
 459 <p/><strong>virtual bool UserHooks::doVetoMIStep(int nMI,const Event& event) &nbsp;</strong> <br/>
 460 can optionally be called, as described above. You can study, but not
 461 modify, the <code>event</code> event record of the partonic process.
 462 Based on that you can decide whether to veto the event, true, or let
 463 it continue to evolve, false. If you veto, then this event is not
 464 counted among the accepted ones, and does not contribute to the estimated
 465 cross section. The <code>Pytha::next()</code> method will begin a
 466 completely new event, so the vetoed event will not appear in the
 467 output of <code>Pythia::next()</code>.
 468 <br/><code>argument</code><strong> nMI </strong>  :  is the number of MI subprocesses has occured
 469 so far.
 470
 471 <br/><code>argument</code><strong> event </strong>  :  the event record contains a list of all partons
 472 generated so far, also including intermediate ones not part of the
 473 "current final state", e.g. leftovers from the ISR and FSR evolution
 474 of previously generated systems. The most recently added one has not
 475 had time to radiate, of course.
 476
 477
 478
 479 <h3>(iv) Veto emissions</h3>
 480
 481 The methods in this group are intended to allow the veto of an emission
 482 in ISR or FSR, without affecting the evolution in any other way.
 483 If an emission is vetoed, the event record is "rolled back" to the
 484 way it was before the emission occured, and the evolution in <i>pT</i>
 485 is continued downwards from the rejected value. The decision can be
 486 based on full knowledge of the kinematics of the branching.
 487
 488 <a name="method19"></a>
 489 <p/><strong>virtual bool UserHooks::canVetoISREmission() &nbsp;</strong> <br/>
 490 In the base class this method returns false. If you redefine it
 491 to return true then the method <code>doVetoISREmission(...)</code>
 492 will interrupt the initial-state shower immediately after each
 493 emission and allow that emission to be vetoed.
 494
 495 <a name="method20"></a>
 496 <p/><strong>virtual bool UserHooks::doVetoISREmission( const int sizeOld, const Event& event) &nbsp;</strong> <br/>
 497 can optionally be called, as described above. You can study, but not
 498 modify, the <code>event</code> event record of the partonic process.
 499 Based on that you can decide whether to veto the emission, true, or
 500 not, false. If you veto, then the latest emission is removed from
 501 the event record. In either case the evolution of the shower will
 502 continue from the point where it was left off.
 503 <br/><code>argument</code><strong> sizeOld </strong>  :  is the size of the event record before the
 504 latest emission was added to it. It will also become the new size if
 505 the emission is vetoed.
 506
 507 <br/><code>argument</code><strong> event </strong>  :  the event record contains a list of all partons
 508 generated so far. Of special interest are the ones associated with the
 509 most recent emission, which are stored in entries from <code>sizeOld</code>
 510 through <code>event.size() - 1</code> inclusive. If you veto the emission
 511 these entries will be removed, and the history info in the remaining
 512 partons will be restored to a state as if the emission had never occured.
 513
 514
 515
 516 <a name="method21"></a>
 517 <p/><strong>virtual bool UserHooks::canVetoFSREmission() &nbsp;</strong> <br/>
 518 In the base class this method returns false. If you redefine it
 519 to return true then the method <code>doVetoFSREmission(...)</code>
 520 will interrupt the final-state shower immediately after each
 521 emission and allow that emission to be vetoed.
 522
 523 <a name="method22"></a>
 524 <p/><strong>virtual bool UserHooks::doVetoFSREmission( const int sizeOld, const Event& event) &nbsp;</strong> <br/>
 525 can optionally be called, as described above. You can study, but not
 526 modify, the <code>event</code> event record of the partonic process.
 527 Based on that you can decide whether to veto the emission, true, or
 528 not, false. If you veto, then the latest emission is removed from
 529 the event record. In either case the evolution of the shower will
 530 continue from the point where it was left off.
 531 <br/><code>argument</code><strong> sizeOld </strong>  :  is the size of the event record before the
 532 latest emission was added to it. It will also become the new size if
 533 the emission is vetoed.
 534
 535 <br/><code>argument</code><strong> event </strong>  :  the event record contains a list of all partons
 536 generated so far. Of special interest are the ones associated with the
 537 most recent emission, which are stored in entries from <code>sizeOld</code>
 538 through <code>event.size() - 1</code> inclusive. If you veto the emission
 539 these entries will be removed, and the history info in the remaining
 540 partons will be restored to a state as if the emission had never occured.
 541
 542
 543
 544 <h3>(v) Modify cross-sections</h3>
 545
 546 <a name="method23"></a>
 547 <p/><strong>virtual bool UserHooks::canModifySigma() &nbsp;</strong> <br/>
 548 In the base class this method returns false. If you redefine it
 549 to return true then the method <code>multiplySigmaBy(...)</code> will
 550 allow you to modify the cross section weight assigned to the current
 551 event.
 552
 553
 554 <a name="method24"></a>
 555 <p/><strong>virtual double UserHooks::multiplySigmaBy(const SigmaProcess* sigmaProcessPtr, const PhaseSpace* phaseSpacePtr, bool inEvent) &nbsp;</strong> <br/>
 556 when called this method should provide the factor by which you want to
 557 see the cross section weight of the current event modified by. If you
 558 return unity then the normal cross section is obtained. Note that, unlike
 559 the methods above, these modifications do not lead to a difference between
 560 the number of "selected" events and the number of "accepted" ones,
 561 since the modifications occur already before the "selected" level.
 562 The integrated cross section of a process is modified, of course.
 563 Note that the cross section is only modifiable for normal hard processes.
 564 It does not affect the cross section in further multiple interactions,
 565 nor in elastic/diffractive/minimum-bias events.
 566 <br/><code>argument</code><strong> sigmaProcessPtr, phaseSpacePtr </strong>  : :
 567 what makes this routine somewhat tricky to write is that the
 568 hard-process event has not yet been constructed, so one is restricted
 569 to use the information available in the phase-space and cross-section
 570 objects currently being accessed. Which of their  methods are applicable
 571 depends on the process, in particular the number of final-state particles.
 572 The <code>multiplySigmaBy</code> code in <code>UserHooks.cc</code>
 573 contains explicit instructions about which methods provide meaningful
 574 information, and so offers a convenient starting point.
 575
 576 <br/><code>argument</code><strong> inEvent </strong>  : : this flag is true when the method is
 577 called from within the event-generation machinery and false
 578 when it is called at the initialization stage of the run, when the
 579 cross section is explored to find a maximum for later Monte Carlo usage.
 580 Cross-section modifications should be independent of this flag,
 581 for consistency, but if <code> multiplySigmaBy(...)</code> is used to
 582 collect statistics on the original kinematics distributions before cuts,
 583 then it is important to be able to exclude the initialization stage
 584 from comparisons.
 585
 586
 587
 588 <p/>
 589 One derived class is supplied as an example how this facility can be used
 590 to reweight cross sections in the same spirit as is done with QCD cross
 591 sections for the minimum-bias/underlying-event description:
 592 <p/><code>class&nbsp; </code><strong> SuppressSmallPT : public UserHooks &nbsp;</strong> <br/>
 593 suppress small-<i>pT</i> production for <i>2 -> 2</i> processes
 594 only, while leaving other processes unaffected. The basic suppression
 595 factor is <i>pT^4 / ((k*pT0)^2 + pT^2)^2</i>, where <i>pT</i>
 596 refers to the current hard subprocess and <i>pT0</i> is the same
 597 energy-dependent dampening scale as used for
 598 <a href="MultipleInteractions.html" target="page">multiple interactions</a>.
 599 This class contains <code>canModifySigma()</code> and
 600 <code>multiplySigmaBy()</code> methods that overload the base class ones.
 601
 602 <a name="method25"></a>
 603 <p/><strong>SuppressSmallPT::SuppressSmallPT( double pT0timesMI = 1., int numberAlphaS = 0, bool useSameAlphaSasMI = true) &nbsp;</strong> <br/>
 604  The optional arguments of the constructor provides further variability.
 605 <br/><code>argument</code><strong> pT0timesMI </strong>  :
 606 corresponds to the additional factor <i>k</i> in the above formula.
 607 It is by default equal to 1 but can be used to explore deviations from
 608 the expected value.
 609
 610 <br/><code>argument</code><strong> numberAlphaS </strong>  :
 611 if this number <i>n</i> is bigger than the default 0, the
 612 corresponding number of <i>alpha_strong</i> factors is also
 613 reweighted from the normal renormalization scale to a modified one,
 614 i.e. a further suppression factor
 615 <i>( alpha_s((k*pT0)^2 + Q^2_ren) / alpha_s(Q^2_ren) )^n</i>
 616 is introduced.
 617
 618 <br/><code>argument</code><strong> useSameAlphaSasMI </strong>  :
 619 regulates which kind of new <i>alpha_strong</i> value is evaluated
 620 for the numerator in the above expression. It is by default the same
 621 as set for multiple interactions (i.e. same starting value at
 622 <i>M_Z</i> and same order of running), but if <code>false</code>
 623 instead the one for hard subprocesses. The denominator
 624 <i>alpha_s(Q^2_ren)</i> is always the value used for the "original",
 625 unweighted cross section.
 626
 627
 628
 629 <h3>(vi) Modify scale in shower evolution</h3>
 630
 631 The choice of maximum shower scale in resonance decays is normally not a
 632 big issue, since the shower here is expected to cover the full phase
 633 space. In some special cases a matching scheme is intended, where hard
 634 radiation is covered by matrix elements, and only softer by showers. The
 635 below two methods support such an approach. Note that the two methods
 636 are not used in the <code>TimeShower</code> class itself, but when
 637 showers are called from the <code>PartonLevel</code> generation. Thus
 638 user calls directly to <code>TimeShower</code> are not affected.
 639
 640 <a name="method26"></a>
 641 <p/><strong>virtual bool UserHooks::canSetResonanceScale() &nbsp;</strong> <br/>
 642 In the base class this method returns false. If you redefine it
 643 to return true then the method <code>scaleResonance(...)</code>
 644 will set the initial scale of downwards shower evolution.
 645
 646 <a name="method27"></a>
 647 <p/><strong>virtual double UserHooks::scaleResonance( const int iRes, const Event& event) &nbsp;</strong> <br/>
 648 can optionally be called, as described above. You should return the maximum
 649 scale, in GeV, from which the shower evolution will begin. The base class
 650 method returns 0, i.e. gives no shower evolution at all.
 651 You can study, but not modify, the <code>event</code> event record
 652 of the partonic process to check which resonance is decaying, and into what.
 653 <br/><code>argument</code><strong> iRes </strong>  :  is the location in the event record of the
 654 resonance that decayed to the particles that now will shower.
 655
 656 <br/><code>argument</code><strong> event </strong>  :  the event record contains a list of all partons
 657 generated so far, specifically the decaying resonance and its immediate
 658 decay products.
 659
 660
 661
 662 </body>
 663 </html>
 664
 665 <!-- Copyright (C) 2010 Torbjorn Sjostrand -->