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