1 <chapter name="User Hooks">
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. A few very simple derived classes come with the
12 program, mainly as illustration.
15 For a derived class to be called during the execution, a pointer to
16 an object of this class should be handed in with the
18 <aloc href="ProgramFlow">
19 <code>pythia.setUserHooksPtr( UserHooks*)</code></aloc> method.
22 There are four distinct sets of routines. Ordered by increasing
23 complexity, rather than by their appearance in the event-generation
25 <br/>(i) Ones that gives 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 with the combined
30 parton-level MI+ISR+FSR downwards evolution in <ei>pT</ei> 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, so the event can be vetoed or allowed to
35 continue the evolution.
36 <br/>(iv) Ones that gives you access to the properties of the trial
37 hard process, so that you can modify the internal Pythia cross section
38 by your own correction factors.
39 <br/>They are described further in the following.
41 <h3>Interrupt between the main generation levels</h3>
43 If your derived class redefines the
44 <br/><code>bool canVetoProcessLevel()</code>
45 <br/>method to return <code>true</code>, then the method
46 <br/><code>bool doVetoProcessLevel(const Event& process)</code>
47 <br/>will be called immediately after a hard process has been selected and
48 stored in the <code>process</code> event record. You can study, but not
49 modify, this record. Based on that you can decide whether to veto the
50 event or let it continue to evolve. If you veto, then this event is not
51 counted among the accepted ones, and do not contribute to the estimated
52 cross section. The <code>pytha.next()</code> method will begin a
53 completely new event, so the vetoed event will not appear in the
54 output of <code>pythia.next()</code>.
57 Note that this is different from setting the flag
58 <aloc href="MasterSwitches"><code>PartonLevel:all = off</code></aloc>.
59 Also in this case the event
60 generation will stop after the process level, but an event generated
61 up to this point is considered perfectly acceptable, and cross sections
62 are not affected. That is, this option is intended for simple studies of
63 hard processes, where one can save time by not generating the rest of the
64 story. By contrast, the <code>doVetoProcessLevel()</code> allows you to
65 throw away uninteresting events at an early stage to save time that way,
66 but those events that do survive the veto are allowed to develop into
67 complete final states (unless flags have been set otherwise).
71 <br/><code>bool canVetoPartonLevel()</code>
73 <br/><code>bool doVetoPartonLevel(const Event& event)</code>
74 <br/>are exact analogues to the above two methods, except that these
75 ones are called after the parton level, i.e. when showers, multiple
76 interactions and beam remnants have been set up, but hadronization and
77 decays have not yet been performed. Information is now made available in
78 the <code>event</code> event record. The difference relative to the
79 <aloc href="MasterSwitches"><code>HadronLevel:all = off</code></aloc>
80 flag setting follows the same pattern as above.
83 The effect of the vetoes can be studied in the output of the
84 <code>pythia.statistics()</code> method. The "Selected" column represents
85 the number of events that were found acceptable by the internal Pythia
86 machinery, whereas the "Accepted" one are the events that also survived
89 <h3>Interrupt during the parton-level evolution, at a <ei>pT</ei> scale</h3>
91 During the parton-level evolution, multiple interactions (MI),
92 initial-state radiation (ISR) and final-state radiation (FSR)
93 are normally evolved downwards in
94 one interleaved evolution sequence of decreasing <ei>pT</ei> values.
95 For some applications, e.g matrix-element-matching approaches, it
96 may be convenient to stop the evolution temporarily when the "hard"
97 emissions have been considered, but before continuing with the more
98 time-consuming soft activity. Based on these hard partons one can make
99 a decision whether the event at all falls in the intended event class,
100 e.g. has the "right" number of parton-level jets. If yes then, as for
101 the methods above, the evolution will continue all the way up to a
102 complete event. Also as above, if no, then the event will not be
103 considered in the final cross section.
106 In this subsection we outline the possibility to interrupt at a given
107 <ei>pT</ei> scale, in the next to interrupt after a given number of
111 To use this possibility you need to redefine
112 <br/><code>bool canVetoPT()</code>
113 <br/>to return <code>true</code> and
114 <br/><code>double scaleVetoPT()</code>
115 <br/>to return the <ei>pT</ei> scale at which you want to study the event.
118 The key routine, where you decide whether the event should be vetoed
119 (return <code>true</code>) or not (<code>false</code>), is
120 <br/><code>bool doVetoPT(int iPos, const Event& event)</code>
122 <br/><code>iPos</code> is the position/status when the routine is
124 <br/>= 0 when no MI, ISR or FSR occured above the veto scale;
125 <br/>= 1 when inside the interleaved MI + ISR + FSR evolution,
127 <br/>= 2 when inside the interleaved MI + ISR + FSR evolution,
128 after an ISR emission;
129 <br/>= 3 when inside the interleaved MI + ISR + FSR evolution,
130 after an FSR emission;
131 <br/>= 4 for the optional case where FSR is deferred from the interleaved
132 evolution and only considered separately afterward (then alternative 3
134 <br/>= 5 is for subsequent resonance decays, and is called once
135 for each decay in a chain such as <ei>t -> b W, W -> u dbar</ei>.
138 The event record contains a list of all partons generated so far, also
139 including intermediate ones not part of the "current final state",
140 and also those from further multiple interactions. This may not be
141 desirable for comparisons with matrix-element calculations. The method
142 <br/><code>void subEvent(const Event& event, bool isHardest = true)</code>
143 <br/> offers a simple recipe to extract a list of only the current
144 partons from the hardest interaction, as relevant for <code>iPos</code>
145 codes 0 - 4. With <code>isHardest = false</code> instead the latest
146 "subprocess" is extracted, as relevant when <code>iPos</code> is 5,
147 where it corresponds to the partons in the currently considered decay.
150 The result is stored in the class member <code>Event workEvent</code>.
151 The <code>daughter1()</code> and <code>daughter2()</code> both return
152 the position in the original event record (<code>process</code> or
153 <code>event</code>), so you can trace the full history, if of interest.
154 The <code>workEvent</code> can e.g. be sent on to a
155 <aloc href="EventAnalysis">jet clustering algorithm</aloc>.
156 You are free to edit <code>workEvent</code> as you desire, e.g. boost
157 to its rest frame before analysis, or remove particles that should
160 <h3>Interrupt during the parton-level evolution, after a step</h3>
162 This option is closely related to the one above, so we do not repeat
163 the introduction, nor the possibilities to study the event record,
164 also by using <code>subEvent(...)</code>.
165 What is different is that this method gives access to the event as
166 it looks like after each of the first few steps in the downwards
167 evolution, irrespectively of the <ei>pT</ei> scales of these branchings.
168 Furthermore, it is here assumed that the focus is on the hardest
169 subprocess, so that ISR/FSR emissions associated with additional MI's
173 To use the possibility to study the event after the first steps you need
175 <br/><code>bool canVetoStep()</code>
176 <br/>to return <code>true</code> and
177 <br/><code>int numberVetoStep()</code>
178 <br/>to return up to how many steps each of ISR and FSR (for the hardest
179 interaction) that you want to be able to study. The number of steps
180 defaults to the first one only.
183 The key routine, where you decide whether the event should be vetoed
184 (return <code>true</code>) or not (<code>false</code>), is
185 <br/><code>bool doVetoStep( int iPos, int nISR, int nFSR,
186 const Event& event)</code>
188 <br/><code>iPos</code> is the position from where the routine has been
189 called, options 2 - 5 of the <code>doVetoPT(...)</code> routine
190 above, while options 0 and 1 are not relevant here;
191 <br/><code>nISR</code> is the number of ISR emissions in the hardest
193 <br/><code>nFSR</code> is the number of FSR emissions in the hardest
195 <br/>For resonance decays, <code>iPos = 5</code>, the <code>nISR</code>
196 is set 0 and <code>nFSR</code> refers to the number of emissions in
197 the currently studied system.
199 <h3>Modify cross-sections</h3>
201 If you want to modify a cross section you need to redefine
202 <br/><code>bool canModifySigma()</code>
203 <br/>to return <code>true</code> and
204 <br/><code>double multiplySigmaBy(const SigmaProcess* sigmaProcessPtr,
205 const PhaseSpace* phaseSpacePtr, bool inEvent)</code>
206 <br/>to provide the factor by
207 which you want to see the cross section modified. If you return unity
208 then the normal cross section is obtained. Note that, unlike the
209 methods above, these modifications do not lead to a difference between
210 the number of "selected" events and the number of "accepted" ones,
211 since the modifications occur already before the "selected" level.
212 The integrated cross section of a process is modified, of course.
215 What makes the <code>multiplySigmaBy(...)</code> routine somewhat
216 tricky to write is that the hard-process event has not yet been
217 constructed, so one is restricted to use the information available
218 in the phase-space and cross-section objects currently being accessed.
219 Which of their methods are applicable depends on the process,
220 in particular the number of final-state particles. The
221 <code>UserHooks</code> code contains explicit instructions about
222 which methods provide meaningful information.
225 The <code>inEvent</code> flag is <code>true</code> when this method is
226 called from within the event-generation machinery and <code>false</code>
227 when it is called at the initialization stage of the run, when the
228 cross section is explored to find a maximum for later Monte Carlo usage.
229 Cross-section modifications should be independent of this flag,
230 for consistency, but if <code> multiplySigmaBy(...)</code> is used to
231 collect statistics on the original kinematics distributions before cuts,
232 then it is important to be able to exclude the initialization stage
236 Note that the cross section is only modifiable for normal hard processes.
237 It does not affect the cross section in further multiple interactions,
238 nor in elastic/diffractive/minimum-bias events.
241 One derived class is supplied as an example how this facility can be used
242 to reweight cross sections in the same spirit as is done with QCD cross
243 sections for the minimum-bias/underlying-event description:
244 <class name="SuppressSmallPT( pT0timesMI, numberAlphaS, useSameAlphaSasMI)">
245 suppress small-<ei>pT</ei> production for <ei>2 -> 2</ei> processes
246 only, while leaving other processes unaffected. The basic suppression
247 factor is <ei>pT^4 / ((k*pT0)^2 + pT^2)^2</ei>, where <ei>pT</ei>
248 refers to the current hard subprocess and <ei>pT0</ei> is the same
249 energy-dependent dampening scale as used for
250 <aloc href="MultipleInteractions">multiple interactions</aloc>.
251 The optional arguments provide further variability.
252 <argument name="pT0timesMI">
253 corresponds to the additional factor <ei>k</ei> in the above formula.
254 It is by default equal to 1 but can be used to explore deviations from
257 <argument name="numberAlphaS">
258 if this number <ei>n</ei> is bigger than the default 0, the
259 corresponding number of <ei>alpha_strong</ei> factors is also
260 reweighted from the normal renormalization scale to a modified one,
261 i.e. a further suppression factor
262 <ei>( alpha_s((k*pT0)^2 + Q^2_ren) / alpha_s(Q^2_ren) )^n</ei>
265 <argument name="useSameAlphaSasMI">
266 regulates which kind of new <ei>alpha_strong</ei> value is evaluated
267 for the numerator in the above expression. It is by default the same
268 as set for multiple interactions (i.e. same starting value at
269 <ei>M_Z</ei> and same order of running), but if <code>false</code>
270 instead the one for hard subprocesses. The denominator
271 <ei>alpha_s(Q^2_ren)</ei> is always the value used for the "original",
272 unweighted cross section.
276 <h3>Final comments</h3>
278 All the possibilities above can be combined freely and also be combined
279 with the standard flags. An event would then survive only if it survived
280 each of the possible veto methods. There are no hidden interdependencies
281 in this game, but of course some combinations may not be particularly
282 meaningful. For instance, if you set <code>PartonLevel:all = off</code>
283 then the <code>doVetoPT(...)</code> and <code>doVetoPartonLevel(...)</code>
284 locations in the code are not even reached, so they would never be called.
287 An example how the above methods can be used for toy studies is found in
288 <code>main10.cc</code>.
292 <!-- Copyright (C) 2008 Torbjorn Sjostrand -->