Context Navigation

← Previous Revision
Latest Revision
Next Revision →
Blame
Revision Log

UserHooks.html @ 1

Last change on this file since 1 was 1, checked in by zerwas, 11 years ago
first import of structure, PYTHIA8 and DELPHES
File size: 46.7 KB

Line
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 MPI+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 MPI, 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	alternatively the phase space sampling, by your own correction factors.
42	<br/>(vi) Ones that allow you to reject the decay sequence of resonances
43	at the process level.
44	<br/>(vii) Ones that let you set the scale of shower evolution,
45	specifically for matching in resonance decays.
46	<br/>They are described further in the following numbered subsections.
47
48	<p/>
49	All the possibilities above can be combined freely and also be combined
50	with the standard flags. An event would then survive only if it survived
51	each of the possible veto methods. There are no hidden interdependencies
52	in this game, but of course some combinations may not be particularly
53	meaningful. For instance, if you set <code>PartonLevel:all = off</code>
54	then the <code>doVetoPT(...)</code> and <code>doVetoPartonLevel(...)</code>
55	locations in the code are not even reached, so they would never be called.
56
57	<p/>
58	The effect of the vetoes of types (i), (ii) and (iii) can be studied
59	in the output of the
60	<code><a href="EventStatistics.html" target="page">Pythia::statistics()</a></code>
61	method. The "Selected" column represents the number of events that were
62	found acceptable by the internal Pythia machinery, whereas the "Accepted"
63	one are the events that also survived the user cuts. The cross section
64	is based on the latter number, and so is reduced by the amount associated
65	by the vetoed events. Also type (v) modifies the cross section, while
66	types (iv), (vi) and (vii) do not.
67
68	<p/>
69	A warning. When you program your own derived class, do remember that you
70	must exactly match the arguments of the base-class methods you overload.
71	If not, your methods will be considered as completely new ones, and
72	compile without any warnings, but not be used inside <code>Pythia</code>.
73	So, at the debug stage, do insert some suitable print statements to check
74	that the new methods are called (and do what they should).
75
76	<h3>The basic components</h3>
77
78	For a derived <code>UserHooks</code> class to be called during the
79	execution, a pointer to an object of this class should be handed in
80	with the
81	<br/><code><a href="ProgramFlow.html" target="page">
82	Pythia::setUserHooksPtr( UserHooks*)</a></code>
83	<br/>method. The first step therefore is to construct your own derived
84	class, of course. This must contain a constructor and a destructor. The
85	<code>initPtr</code> method comes "for free", and is set up without
86	any intervention from you.
87
88	<a name="method1"></a>
89	<p/><strong>UserHooks::UserHooks()  </strong> <br/>
90
91	<strong>virtual UserHooks::~UserHooks()  </strong> <br/>
92	The constructor and destructor do not need to do anything.
93
94
95	<a name="method2"></a>
96	<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)  </strong> <br/>
97	this (non-virtual) method is automatically called during the
98	initialization stage to set several useful pointers, and to set up
99	the <code>workEvent</code> below. The corresponding objects can
100	later be used to extract some useful information.
101	<br/><a href="EventInformation.html" target="page">Info</a>:
102	general event and run information, including some loop counters.
103	<br/><a href="SettingsScheme.html" target="page">Settings</a>:
104	the settings used to determine the character of the run.
105	<br/><a href="ParticleDataScheme.html" target="page">ParticleData</a>:
106	the particle data used in the event record
107	(including <code>workEvent</code> below).
108	<br/><a href="RandomNumbers.html" target="page">Rndm</a>: the random number
109	generator, that you could also use in your code.
110	<br/><a href="BeamRemnants.html" target="page">BeamParticle</a>:
111	the <code>beamAPtr</code> and <code>beamBPtr</code> beam particles
112	contain info on partons extracted from the two incoming beams,
113	on the PDFs used, and more. In cases when diffraction is simulated,
114	also special Pomeron beams <code>beamPomAPtr</code> and
115	<code>beamPomBPtr</code> are introduced, for the Pomerons residing
116	inside the respective proton.
117	<br/><a href="StandardModelParameters.html" target="page">CoupSM</a>:
118	Standard Model couplings.
119	<br/><a href="AdvancedUsage.html" target="page">PartonSystems</a>:
120	the list of partons that belong to each individual subcollision system.
121	<br/><a href="TotalCrossSections.html" target="page">SigmaTotal</a>:
122	total/elastic/diffractive cross section parametrizations.
123
124
125	<p/>
126	Next you overload the desired methods listed in the sections below.
127	These often come in pairs or triplets, where the first must return
128	true for the last method to be called. This latter method typically
129	hands you a reference to the event record, which you then can use to
130	decide whether or not to veto. Often the event record can be quite
131	lengthy and difficult to overview. The following methods and data member
132	can then come in handy.
133
134	<a name="method3"></a>
135	<p/><strong>void UserHooks::omitResonanceDecays(const Event& process, bool finalOnly = false)  </strong> <br/>
136	is a protected method that you can make use of in your own methods to
137	extract a simplified list of the hard process, where all resonance decay
138	chains are omitted. Intended for the <code>can/doVetoProcessLevel</code>
139	routines. Note that the normal process-level generation does include
140	resonance decays. That is, if a top quark is produced in the hard process,
141	then also decays such as <i>t -> b W+, W+ -> u dbar</i> will be generated
142	and stored in <code>process</code>. The <code>omitResonanceDecays</code>
143	routine will take the input <code>process</code> and copy it to
144	<code>workEvent</code> (see below), minus the resonance decay chains.
145	All particles produced in the hard process, such as the top, will be
146	considered final-state ones, with positive status and no daughters,
147	just as it is before resonances are allowed to decay.
148	<br/>(In the <code>PartonLevel</code> routines, these decay chains will
149	initially not be copied from <code>process</code> to <code>event</code>.
150	Instead the combined MPI, ISR and FSR evolution is done with the top
151	above as final particle. Only afterwards will the resonance decay chains
152	be copied over, with kinematics changes reflecting those of the top, and
153	showers in the decays carried out.)
154	<br/>For the default <code>finalOnly = false</code> the beam particles
155	and incoming partons are retained, so the event looks like a normal
156	event record up to the point of resonance decays, with a normal history
157	setup.
158	<br/>With <code>finalOnly = true</code> only the final-state partons
159	are retained in the list. It therefore becomes similar in functionality
160	to the <code>subEvent</code> method below, with the difference that
161	<code>subEvent</code> counts the decay products of the resonances
162	as the final state, whereas here the resonances themselves are the
163	final state. Since the history has been removed in this option,
164	<code>mother1()</code> and <code>mother2()</code> return 0, while
165	<code>daughter1()</code> and <code>daughter2()</code> both return the
166	index of the same parton in the original event record.
167
168
169	<a name="method4"></a>
170	<p/><strong>void UserHooks::subEvent(const Event& event, bool isHardest = true)  </strong> <br/>
171	is a protected method that you can make use of in your own methods to
172	extract a brief list of the current partons of interest, with all
173	irrelevant ones omitted. It is primarily intended to track the evolution
174	at the parton level, notably the shower evolution of the hardest
175	(i.e. first) interaction.
176	<br/>For the default <code>isHardest = true</code> only the outgoing partons
177	from the hardest interaction (including the partons added to it by ISR and
178	FSR) are extracted, as relevant e.g. for <code>doVetoPT( iPos, event)</code>
179	with <code>iPos = 0 - 4</code>. With <code>isHardest = false</code> instead
180	the outgoing partons of the latest "subprocess" are extracted, as relevant
181	when <code>iPos = 5</code>, where it corresponds to the outgoing partons
182	in the currently considered decay.
183	<br/>The method also works at the process level, but there simply extracts
184	all final-state partons in the event, and thus offers no extra functionality.
185	<br/>The result is stored in <code>workEvent</code> below. Since the
186	history has been removed, <code>mother1()</code> and <code>mother2()</code>
187	return 0, while <code>daughter1()</code> and <code>daughter2()</code> both
188	return the index of the same parton in the original event record
189	(<code>event</code>; possibly <code>process</code>), so that you can
190	trace the full history, if of interest.
191
192
193	<a name="method5"></a>
194	<p/><strong>Event UserHooks::workEvent  </strong> <br/>
195	This protected class member contains the outcome of the above
196	<code>omitResonanceDecays(...)</code> and
197	<code>subEvent(...)</code> methods. Alternatively you can use it for
198	whatever temporary purposes you wish. You are free to use standard
199	operations, e.g. to boost the event to its rest frame before analysis,
200	or remove particles that should not be analyzed.
201	The <code>workEvent</code> can also be sent on to a
202	<a href="EventAnalysis.html" target="page">jet clustering algorithm</a>.
203
204	<h3>(i) Interrupt between the main generation levels</h3>
205
206	<a name="method6"></a>
207	<p/><strong>virtual bool UserHooks::initAfterBeams()  </strong> <br/>
208	This routine is called by Pythia::init(), after the beams have been
209	set up, but before any other initialisation. Therefore, at this stage,
210	it is still possible to modifiy settings (apart from
211	<code>Beams:*</code>) and particle data. This is mainly intended
212	to be used in conjunction with Les Houches Event files, where
213	headers are read in during beam initialisation, see the header
214	functions in the <a href="EventInformation.html" target="page">Info</a> class.
215	In the base class this method returns true. By returning false,
216	PYTHIA initialisation will be aborted.
217
218
219	<a name="method7"></a>
220	<p/><strong>virtual bool UserHooks::canVetoProcessLevel()  </strong> <br/>
221	In the base class this method returns false. If you redefine it
222	to return true then the method <code>doVetoProcessLevel(...)</code>
223	will be called immediately after a hard process (and associated
224	resonance decays) has been selected and stored in the
225	<code><a href="EventRecord.html" target="page">process</a></code> event record.
226	<br/>At this stage, the <code>process</code> record typically contains
227	the two beams in slots 1 and 2, the two incoming partons to the hard
228	process in slots 3 and 4, the N (usually 1, 2 or 3) primary produced
229	particles in slots 5 through 4 + N, and thereafter recursively the
230	resonance decay chains, if any. Use the method
231	<code>omitResonanceDecays(...)</code> if you want to skip these
232	decay chains. There are exceptions to this structure,
233	for <a href="QCDProcesses.html" target="page">soft QCD processes</a> (where
234	the partonic process may not yet have been selected at this stage),
235	and when <a href="ASecondHardProcess.html" target="page">a second hard process</a> has
236	been requested (where two hard processes are bookkept). In general
237	it is useful to begin the development work by listing a few
238	<code>process</code> records, to clarify what the structure is for
239	the cases of interest.
240
241
242	<a name="method8"></a>
243	<p/><strong>virtual bool UserHooks::doVetoProcessLevel(Event& process)  </strong> <br/>
244	can optionally be called, as described above. You can study the
245	<code>process</code> event record of the hard process.
246	Based on that you can decide whether to veto the event, true, or let
247	it continue to evolve, false. If you veto, then this event is not
248	counted among the accepted ones, and does not contribute to the estimated
249	cross section. The <code>Pytha::next()</code> method will begin a
250	completely new event, so the vetoed event will not appear in the
251	output of <code>Pythia::next()</code>.
252	<br/><b>Warning:</b> Normally you should not modify the <code>process</code>
253	event record. However, for some matrix-element-matching procedures it may
254	become unavoidable. If so, be very careful, since there are many pitfalls.
255	Only to give one example: if you modify the incoming partons then also
256	the information stored in the beam particles may need to be modified.
257	<br/><b>Note:</b> the above veto is different from setting the flag
258	<code><a href="MasterSwitches.html" target="page">PartonLevel:all = off</a></code>.
259	Also in the latter case the event generation will stop after the process
260	level, but an event generated up to this point is considered perfectly
261	acceptable. It can be studied and it contributes to the cross section.
262	That is, <code>PartonLevel:all = off</code> is intended for simple studies
263	of hard processes, where one can save a lot of time by not generating
264	the rest of the story. By contrast, the <code>doVetoProcessLevel()</code>
265	method allows you to throw away uninteresting events at an early stage
266	to save time, but those events that do survive the veto are allowed to
267	develop into complete final states (unless flags have been set otherwise).
268
269
270	<a name="method9"></a>
271	<p/><strong>virtual bool UserHooks::canVetoPartonLevel()  </strong> <br/>
272	In the base class this method returns false. If you redefine it
273	to return true then the method <code>doVetoPartonLevel(...)</code>
274	will be called immediately after the parton level has been generated
275	and stored in the <code><a href="EventRecord.html" target="page">event</a></code>
276	event record. Thus showers, multiparton interactions and beam remnants
277	have been set up, but hadronization and decays have not yet been
278	performed. This is already a fairly complete event, possibly with quite
279	a complex parton-level history. Therefore it is usually only meaningful
280	to study the hardest interaction, e.g. using <code>subEvent(...)</code>
281	introduced above, or fairly generic properties, such as the parton-level
282	jet structure.
283
284
285	<a name="method10"></a>
286	<p/><strong>virtual bool UserHooks::doVetoPartonLevel(const Event& event)  </strong> <br/>
287	can optionally be called, as described above. You can study, but not
288	modify, the <code>event</code> event record of the partonic process.
289	Based on that you can decide whether to veto the event, true, or let
290	it continue to evolve, false. If you veto, then this event is not
291	counted among the accepted ones, and does not contribute to the estimated
292	cross section. The <code>Pytha::next()</code> method will begin a
293	completely new event, so the vetoed event will not appear in the
294	output of <code>Pythia::next()</code>.
295	<br/><b>Note:</b> the above veto is different from setting the flag
296	<code><a href="MasterSwitches.html" target="page">HadronLevel:all = off</a></code>.
297	Also in the latter case the event generation will stop after the parton
298	level, but an event generated up to this point is considered perfectly
299	acceptable. It can be studied and it contributes to the cross section.
300	That is, <code>HadronLevel:all = off</code> is intended for simple
301	studies of complete partonic states, where one can save time by not
302	generating the complete hadronic final state. By contrast, the
303	<code>doVetoPartonLevel()</code> method allows you to throw away
304	uninteresting events to save time that way, but those events that
305	do survive the veto are allowed to develop into complete final states
306	(unless flags have been set otherwise).
307
308
309	<a name="method11"></a>
310	<p/><strong>virtual bool UserHooks::canVetoPartonLevelEarly()  </strong> <br/>
311	is very similar to <code>canVetoPartonLevel()</code> above, except
312	that the chance to veto appears somewhat earlier in the generation
313	chain, after showers and multiparton interactions, but before the
314	beam remnants and resonance decays have been added. It is therefore
315	somewhat more convenient for many matrix element strategies, where
316	the primordial <i>kT</i> added along with the beam remnants should
317	not be included.
318
319
320	<a name="method12"></a>
321	<p/><strong>virtual bool UserHooks::doVetoPartonLevelEarly(const Event& event)  </strong> <br/>
322	is very similar to <code>doVetoPartonLevel(...)</code> above, but
323	the veto can be done earier, as described for
324	<code>canVetoPartonLevelEarly()</code>.
325
326	<h3>(ii) Interrupt during the parton-level evolution, at a
327	<i>pT</i> scale</h3>
328
329	During the parton-level evolution, multiparton interactions (MPI),
330	initial-state radiation (ISR) and final-state radiation (FSR)
331	are normally evolved downwards in
332	one interleaved evolution sequence of decreasing <i>pT</i> values.
333	For some applications, e.g matrix-element-matching approaches, it
334	may be convenient to stop the evolution temporarily when the "hard"
335	emissions have been considered, but before continuing with the more
336	time-consuming soft activity. Based on these hard partons one can make
337	a decision whether the event at all falls in the intended event class,
338	e.g. has the "right" number of parton-level jets. If yes then, as for
339	the methods above, the evolution will continue all the way up to a
340	complete event. Also as above, if no, then the event will not be
341	considered in the final cross section.
342
343	<p/>
344	Recall that the new or modified partons resulting from a MPI, ISR or FSR
345	step are always appended to the end of the then-current event record.
346	Previously existing partons are not touched, except for the
347	<a href="ParticleProperties.html" target="page">status, mother and daughter</a>
348	values, which are updated to reflect the modified history. It is
349	therefore straightforward to find the partons associated with the most
350	recent occurence.
351	<br/>An MPI results in four new partons being appended, two incoming
352	and two outgoing ones.
353	<br/>An ISR results in the whole affected system being copied down,
354	with one of the two incoming partons being replaced by a new one, and
355	one more outgoing parton.
356	<br/>An FSR results in three new partons, two that come from the
357	branching and one that takes the recoil.
358	<br/>The story becomes more messy when rescattering is allowed as part
359	of the MPI machinery. Then there will not only be a new system, as
360	outlined above, but additionally some existing systems will undergo
361	cascade effects, and be copied down with changed kinematics.
362
363	<p/>
364	In this subsection we outline the possibility to interrupt at a given
365	<i>pT</i> scale, in the next to interrupt after a given number of
366	emissions.
367
368	<a name="method13"></a>
369	<p/><strong>virtual bool UserHooks::canVetoPT()  </strong> <br/>
370	In the base class this method returns false. If you redefine it
371	to return true then the method <code>doVetoPT(...)</code> will
372	interrupt the downward evolution at <code>scaleVetoPT()</code>.
373
374	<a name="method14"></a>
375	<p/><strong>virtual double UserHooks::scaleVetoPT()  </strong> <br/>
376	In the base class this method returns 0. You should redefine it
377	to return the <i>pT</i> scale at which you want to study the event.
378
379
380	<a name="method15"></a>
381	<p/><strong>virtual bool UserHooks::doVetoPT(int iPos, const Event& event)  </strong> <br/>
382	can optionally be called, as described above. You can study, but not
383	modify, the <code>event</code> event record of the partonic process.
384	Based on that you can decide whether to veto the event, true, or let
385	it continue to evolve, false. If you veto, then this event is not
386	counted among the accepted ones, and does not contribute to the estimated
387	cross section. The <code>Pytha::next()</code> method will begin a
388	completely new event, so the vetoed event will not appear in the
389	output of <code>Pythia::next()</code>.
390	<br/><code>argument</code><strong> iPos </strong> : is the position/status when the routine is
391	called, information that can help you decide your course of action:
392	<br/><code>argumentoption </code><strong> 0</strong> : when no MPI, ISR or FSR occured above the veto scale;
393
394	<br/><code>argumentoption </code><strong> 1</strong> : when inside the interleaved MPI + ISR + FSR evolution,
395	after an MPI process;
396
397	<br/><code>argumentoption </code><strong> 2</strong> : when inside the interleaved MPI + ISR + FSR evolution,
398	after an ISR emission;
399
400	<br/><code>argumentoption </code><strong> 3</strong> : when inside the interleaved MPI + ISR + FSR evolution,
401	after an FSR emission;
402
403	<br/><code>argumentoption </code><strong> 4</strong> : for the optional case where FSR is deferred from the
404	interleaved evolution and only considered separately afterward (then
405	alternative 3 would never occur);
406
407	<br/><code>argumentoption </code><strong> 5</strong> : is for subsequent resonance decays, and is called once
408	for each decaying resonance in a chain such as <i>t -> b W, W -> u dbar</i>.
409
410
411	<br/><code>argument</code><strong> event </strong> : the event record contains a list of all partons
412	generated so far, also including intermediate ones not part of the
413	"current final state", and also those from further multiparton interactions.
414	This may not be desirable for comparisons with matrix-element calculations.
415	You may want to make use of the <code>subEvent(...)</code> method below to
416	obtain a simplified event record <code>workEvent</code>.
417
418
419
420	<h3>(iii) Interrupt during the parton-level evolution, after a step</h3>
421
422	These options are closely related to the ones above in section (ii), so
423	we do not repeat the introduction, nor the possibilities to study the
424	event record, also by using <code>subEvent(...)</code> and
425	<code>workEvent</code>.
426	What is different is that the methods in this section give access to the
427	event as it looks like after each of the first few steps in the downwards
428	evolution, irrespectively of the <i>pT</i> scales of these branchings.
429	Furthermore, it is here assumed that the focus normally is on the hardest
430	subprocess, so that ISR/FSR emissions associated with additional MPI's
431	are not considered. For MPI studies, however, a separate simpler
432	alternative is offered to consider the event after a given number
433	of interactions.
434
435	<a name="method16"></a>
436	<p/><strong>virtual bool UserHooks::canVetoStep()  </strong> <br/>
437	In the base class this method returns false. If you redefine it
438	to return true then the method <code>doVetoStep(...)</code> will
439	interrupt the downward ISR and FSR evolution the first
440	<code>numberVetoStep()</code> times.
441
442	<a name="method17"></a>
443	<p/><strong>virtual int UserHooks::numberVetoStep()  </strong> <br/>
444	Returns the number of steps <i>n</i> each of ISR and FSR, for the
445	hardest interaction, that you want to be able to study. That is,
446	the method will be called after the first <i>n</i> ISR emissions,
447	irrespective of the number of FSR ones at the time, and after the
448	first <i>n</i> FSR emissions, irespective of the number of ISR ones.
449	The number of steps defaults to the first one only, but you are free
450	to pick another value. Note that double diffraction is handled as two
451	separate Pomeron-proton collisions, and thus has two sequences of
452	emissions.
453
454
455	<a name="method18"></a>
456	<p/><strong>virtual bool UserHooks::doVetoStep(int iPos, int nISR, int nFSR, const Event& event)  </strong> <br/>
457	can optionally be called, as described above. You can study, but not
458	modify, the <code>event</code> event record of the partonic process.
459	Based on that you can decide whether to veto the event, true, or let
460	it continue to evolve, false. If you veto, then this event is not
461	counted among the accepted ones, and does not contribute to the estimated
462	cross section. The <code>Pytha::next()</code> method will begin a
463	completely new event, so the vetoed event will not appear in the
464	output of <code>Pythia::next()</code>.
465	<br/><code>argument</code><strong> iPos </strong> : is the position/status when the routine is
466	called, information that can help you decide your course of action.
467	Agrees with options 2 - 5 of the <code>doVetoPT(...)</code> routine
468	above, while options 0 and 1 are not relevant here.
469
470	<br/><code>argument</code><strong> nISR </strong> : is the number of ISR emissions in the hardest
471	process so far. For resonance decays, <code>iPos = 5</code>, it is 0.
472
473	<br/><code>argument</code><strong> nFSR </strong> : is the number of FSR emissions in the hardest
474	process so far. For resonance decays, <code>iPos = 5</code>, it is the
475	number of emissions in the currently studied system.
476
477	<br/><code>argument</code><strong> event </strong> : the event record contains a list of all partons
478	generated so far, also including intermediate ones not part of the
479	"current final state", and also those from further multiparton interactions.
480	This may not be desirable for comparisons with matrix-element calculations.
481	You may want to make use of the <code>subEvent(...)</code> method above to
482	obtain a simplified event record.
483
484
485
486	<a name="method19"></a>
487	<p/><strong>virtual bool UserHooks::canVetoMPIStep()  </strong> <br/>
488	In the base class this method returns false. If you redefine it
489	to return true then the method <code>doVetoMPIStep(...)</code> will
490	interrupt the downward MPI evolution the first
491	<code>numberVetoMPIStep()</code> times.
492
493	<a name="method20"></a>
494	<p/><strong>virtual int UserHooks::numberVetoMPIStep()  </strong> <br/>
495	Returns the number of steps in the MPI evolution that you want to be
496	able to study, right after each new step has been taken and the
497	subcollision has been added to the event record. The number of steps
498	defaults to the first one only, but you are free to pick another value.
499	Note that the hardest interaction of an events counts as the first
500	multiparton interaction. For most hard processes it thus at the first
501	step offers nothing not available with the <code>VetoProcessLevel</code>
502	functionality above. For the minimum-bias and diffractive systems the
503	hardest interaction is not selected at the process level, however, so
504	there a check after the first multiparton interaction offers new
505	functionality. Note that double diffraction is handled as two separate
506	Pomeron-proton collisions, and thus has two sequences of interactions.
507	Also, if you have set up a second hard process then a check is made
508	after these first two, and the first interaction coming from the MPI
509	machinery would have sequence number 3.
510
511
512	<a name="method21"></a>
513	<p/><strong>virtual bool UserHooks::doVetoMPIStep(int nMPI,const Event& event)  </strong> <br/>
514	can optionally be called, as described above. You can study, but not
515	modify, the <code>event</code> event record of the partonic process.
516	Based on that you can decide whether to veto the event, true, or let
517	it continue to evolve, false. If you veto, then this event is not
518	counted among the accepted ones, and does not contribute to the estimated
519	cross section. The <code>Pytha::next()</code> method will begin a
520	completely new event, so the vetoed event will not appear in the
521	output of <code>Pythia::next()</code>.
522	<br/><code>argument</code><strong> nMPI </strong> : is the number of MPI subprocesses has occured
523	so far.
524
525	<br/><code>argument</code><strong> event </strong> : the event record contains a list of all partons
526	generated so far, also including intermediate ones not part of the
527	"current final state", e.g. leftovers from the ISR and FSR evolution
528	of previously generated systems. The most recently added one has not
529	had time to radiate, of course.
530
531
532
533	<h3>(iv) Veto emissions</h3>
534
535	The methods in this group are intended to allow the veto of an emission
536	in ISR, FSR or MPI, without affecting the evolution in any other way.
537	If an emission is vetoed, the event record is "rolled back" to the
538	way it was before the emission occured, and the evolution in <i>pT</i>
539	is continued downwards from the rejected value. The decision can be
540	based on full knowledge of the kinematics of the shower branching or MPI.
541
542	<p/>
543	To identify where shower emissions originated, the ISR/FSR veto
544	routines are passed the system from which the radiation occured, according
545	to the Parton Systems class (see <a href="AdvancedUsage.html" target="page">Advanced
546	Usage</a>). Note, however, that inside the veto routines only the event
547	record has been updated; all other information, including the Parton
548	Systems, reflects the event before the shower branching or MPI has
549	taken place.
550
551	<a name="method22"></a>
552	<p/><strong>virtual bool UserHooks::canVetoISREmission()  </strong> <br/>
553	In the base class this method returns false. If you redefine it
554	to return true then the method <code>doVetoISREmission(...)</code>
555	will interrupt the initial-state shower immediately after each
556	emission and allow that emission to be vetoed.
557
558	<a name="method23"></a>
559	<p/><strong>virtual bool UserHooks::doVetoISREmission( int sizeOld, const Event& event, int iSys)  </strong> <br/>
560	can optionally be called, as described above. You can study, but not
561	modify, the <code>event</code> event record of the partonic process.
562	Based on that you can decide whether to veto the emission, true, or
563	not, false. If you veto, then the latest emission is removed from
564	the event record. In either case the evolution of the shower will
565	continue from the point where it was left off.
566	<br/><code>argument</code><strong> sizeOld </strong> : is the size of the event record before the
567	latest emission was added to it. It will also become the new size if
568	the emission is vetoed.
569
570	<br/><code>argument</code><strong> event </strong> : the event record contains a list of all partons
571	generated so far. Of special interest are the ones associated with the
572	most recent emission, which are stored in entries from <code>sizeOld</code>
573	through <code>event.size() - 1</code> inclusive. If you veto the emission
574	these entries will be removed, and the history info in the remaining
575	partons will be restored to a state as if the emission had never occured.
576
577	<br/><code>argument</code><strong> iSys </strong> : the system where the radiation occurs, according
578	to Parton Systems.
579
580
581
582	<a name="method24"></a>
583	<p/><strong>virtual bool UserHooks::canVetoFSREmission()  </strong> <br/>
584	In the base class this method returns false. If you redefine it
585	to return true then the method <code>doVetoFSREmission(...)</code>
586	will interrupt the final-state shower immediately after each
587	emission and allow that emission to be vetoed.
588
589	<a name="method25"></a>
590	<p/><strong>virtual bool UserHooks::doVetoFSREmission( int sizeOld, const Event& event, int iSys, bool inResonance = false)  </strong> <br/>
591	can optionally be called, as described above. You can study, but not
592	modify, the <code>event</code> event record of the partonic process.
593	Based on that you can decide whether to veto the emission, true, or
594	not, false. If you veto, then the latest emission is removed from
595	the event record. In either case the evolution of the shower will
596	continue from the point where it was left off.
597	<br/><code>argument</code><strong> sizeOld </strong> : is the size of the event record before the
598	latest emission was added to it. It will also become the new size if
599	the emission is vetoed.
600
601	<br/><code>argument</code><strong> event </strong> : the event record contains a list of all partons
602	generated so far. Of special interest are the ones associated with the
603	most recent emission, which are stored in entries from <code>sizeOld</code>
604	through <code>event.size() - 1</code> inclusive. If you veto the emission
605	these entries will be removed, and the history info in the remaining
606	partons will be restored to a state as if the emission had never occured.
607
608	<br/><code>argument</code><strong> iSys </strong> : the system where the radiation occurs, according
609	to Parton Systems.
610
611	<br/><code>argument</code><strong> inResonance </strong> : <code>true</code> if the emission takes
612	place in a resonance decay, subsequent to the hard process.
613
614
615
616	<a name="method26"></a>
617	<p/><strong>virtual bool UserHooks::canVetoMPIEmission()  </strong> <br/>
618	In the base class this method returns false. If you redefine it
619	to return true then the method <code>doVetoMPIEmission(...)</code>
620	will interrupt the MPI machinery immediately after each multiparton
621	interaction and allow it to be vetoed.
622
623	<a name="method27"></a>
624	<p/><strong>virtual bool UserHooks::doVetoMPIEmission( int sizeOld, const Event& event)  </strong> <br/>
625	can optionally be called, as described above. You can study, but not
626	modify, the <code>event</code> event record of the partonic process.
627	Based on that you can decide whether to veto the MPI, true, or
628	not, false. If you veto, then the latest MPI is removed from
629	the event record. In either case the interleaved evolution will
630	continue from the point where it was left off.
631	<br/><code>argument</code><strong> sizeOld </strong> : is the size of the event record before the
632	latest MPI was added to it. It will also become the new size if
633	the MPI is vetoed.
634
635	<br/><code>argument</code><strong> event </strong> : the event record contains a list of all partons
636	generated so far. Of special interest are the ones associated with the
637	most recent MPI, which are stored in entries from <code>sizeOld</code>
638	through <code>event.size() - 1</code> inclusive. If you veto the MPI
639	these entries will be removed.
640
641
642
643	<h3>(v) Modify cross-sections or phase space samling</h3>
644
645	This section addresses two related but different topics. In both
646	cases the sampling of events in phase space is modified, so that
647	some regions are more populated while others are depleted.
648	In the first case, this is assumed to be because the physical
649	cross section should be modified relative to the built-in Pythia
650	form. Therefore not only the relative population of phase space
651	is changed, but also the integrated cross section of the process.
652	In the second case the repopulation is only to be viewed as a
653	technical trick to sample some phase-space regions better, so as
654	to reduce the statistical error. There each event instead obtains
655	a compensating weight, the inverse of the differential cross section
656	reweighting factor, in such a way thet the integrated cross section
657	is unchanged. Below these two cases are considered separately,
658	but note that they share many points.
659
660	<a name="method28"></a>
661	<p/><strong>virtual bool UserHooks::canModifySigma()  </strong> <br/>
662	In the base class this method returns false. If you redefine it
663	to return true then the method <code>multiplySigmaBy(...)</code> will
664	allow you to modify the cross section weight assigned to the current
665	event.
666
667
668	<a name="method29"></a>
669	<p/><strong>virtual double UserHooks::multiplySigmaBy(const SigmaProcess* sigmaProcessPtr, const PhaseSpace* phaseSpacePtr, bool inEvent)  </strong> <br/>
670	when called this method should provide the factor by which you want to
671	see the cross section weight of the current event modified. If you
672	return unity then the normal cross section is obtained. Note that, unlike
673	the methods above, these modifications do not lead to a difference between
674	the number of "selected" events and the number of "accepted" ones,
675	since the modifications occur already before the "selected" level.
676	The integrated cross section of a process is modified, of course.
677	Note that the cross section is only modifiable for normal hard processes.
678	It does not affect the cross section in further multiparton interactions,
679	nor in elastic/diffractive/minimum-bias events.
680	<br/><code>argument</code><strong> sigmaProcessPtr, phaseSpacePtr </strong> : :
681	what makes this routine somewhat tricky to write is that the
682	hard-process event has not yet been constructed, so one is restricted
683	to use the information available in the phase-space and cross-section
684	objects currently being accessed. Which of their methods are applicable
685	depends on the process, in particular the number of final-state particles.
686	The <code>multiplySigmaBy</code> code in <code>UserHooks.cc</code>
687	contains explicit instructions about which methods provide meaningful
688	information, and so offers a convenient starting point.
689
690	<br/><code>argument</code><strong> inEvent </strong> : : this flag is true when the method is
691	called from within the event-generation machinery and false
692	when it is called at the initialization stage of the run, when the
693	cross section is explored to find a maximum for later Monte Carlo usage.
694	Cross-section modifications should be independent of this flag,
695	for consistency, but if <code> multiplySigmaBy(...)</code> is used to
696	collect statistics on the original kinematics distributions before cuts,
697	then it is important to be able to exclude the initialization stage
698	from comparisons.
699
700
701
702	<p/>
703	One derived class is supplied as an example how this facility can be used
704	to reweight cross sections in the same spirit as is done with QCD cross
705	sections for the minimum-bias/underlying-event description:
706
707	<p/><code>class  </code><strong> SuppressSmallPT : public UserHooks  </strong> <br/>
708	suppress small-<i>pT</i> production for <i>2 -> 2</i> processes
709	only, while leaving other processes unaffected. The basic suppression
710	factor is <i>pT^4 / ((k*pT0)^2 + pT^2)^2</i>, where <i>pT</i>
711	refers to the current hard subprocess and <i>pT0</i> is the same
712	energy-dependent dampening scale as used for
713	<a href="MultipartonInteractions.html" target="page">multiparton interactions</a>.
714	This class contains <code>canModifySigma()</code> and
715	<code>multiplySigmaBy()</code> methods that overload the base class ones.
716
717	<a name="method30"></a>
718	<p/><strong>SuppressSmallPT::SuppressSmallPT( double pT0timesMPI = 1., int numberAlphaS = 0, bool useSameAlphaSasMPI = true)  </strong> <br/>
719	The optional arguments of the constructor provides further variability.
720	<br/><code>argument</code><strong> pT0timesMPI </strong> :
721	corresponds to the additional factor <i>k</i> in the above formula.
722	It is by default equal to 1 but can be used to explore deviations from
723	the expected value.
724
725	<br/><code>argument</code><strong> numberAlphaS </strong> :
726	if this number <i>n</i> is bigger than the default 0, the
727	corresponding number of <i>alpha_strong</i> factors is also
728	reweighted from the normal renormalization scale to a modified one,
729	i.e. a further suppression factor
730	<i>( alpha_s((k*pT0)^2 + Q^2_ren) / alpha_s(Q^2_ren) )^n</i>
731	is introduced.
732
733	<br/><code>argument</code><strong> useSameAlphaSasMPI </strong> :
734	regulates which kind of new <i>alpha_strong</i> value is evaluated
735	for the numerator in the above expression. It is by default the same
736	as set for multiparton interactions (i.e. same starting value at
737	<i>M_Z</i> and same order of running), but if <code>false</code>
738	instead the one for hard subprocesses. The denominator
739	<i>alpha_s(Q^2_ren)</i> is always the value used for the "original",
740	unweighted cross section.
741
742
743
744	<p/>
745	The second main case of the current section involves three methods,
746	as follows.
747
748	<a name="method31"></a>
749	<p/><strong>virtual bool UserHooks::canBiasSelection()  </strong> <br/>
750	In the base class this method returns false. If you redefine it
751	to return true then the method <code>biasSelectionBy(...)</code> will
752	allow you to modify the phase space sampling, with a compensating
753	event weight, such that the cross section is unchanged. You cannot
754	combine this kind of reweighting with the selection of
755	<a href="ASecondHardProcess.html" target="page">a second hard process</a>.
756
757
758	<a name="method32"></a>
759	<p/><strong>virtual double UserHooks::biasSelectionBy(const SigmaProcess* sigmaProcessPtr, const PhaseSpace* phaseSpacePtr, bool inEvent)  </strong> <br/>
760	when called this method should provide the factor by which you want to
761	see the phase space sampling of the current event modified. Events are
762	assigned a weight being the inverse of this, such that the integrated
763	cross section of a process is unchanged. Note that the selection
764	is only modifiable for normal hard processes. It does not affect the
765	selection in further multiparton interactions, nor in
766	elastic/diffractive/minimum-bias events.
767	<br/><code>argument</code><strong> sigmaProcessPtr, phaseSpacePtr </strong> : :
768	what makes this routine somewhat tricky to write is that the
769	hard-process event has not yet been constructed, so one is restricted
770	to use the information available in the phase-space and cross-section
771	objects currently being accessed. Which of their methods are applicable
772	depends on the process, in particular the number of final-state particles.
773	The <code>biasSelectionBy</code> code in <code>UserHooks.cc</code>
774	contains explicit instructions about which methods provide meaningful
775	information, and so offers a convenient starting point.
776
777	<br/><code>argument</code><strong> inEvent </strong> : : this flag is true when the method is
778	called from within the event-generation machinery and false
779	when it is called at the initialization stage of the run, when the
780	cross section is explored to find a maximum for later Monte Carlo usage.
781	Cross-section modifications should be independent of this flag,
782	for consistency, but if <code>biasSelectionBy(...)</code> is used to
783	collect statistics on the original kinematics distributions before cuts,
784	then it is important to be able to exclude the initialization stage
785	from comparisons.
786
787
788
789	<a name="method33"></a>
790	<p/><strong>virtual double UserHooks::biasedSelectionWeight()  </strong> <br/>
791	Returns the weight you should assign to the event, to use e.g. when
792	you histogram results. It is the exact inverse of the weight you
793	used to modify the phase-space sampling, a weight that must be stored
794	in the <code>selBias</code> member variable, such that this routine
795	can return <code>1/selBias</code>. The weight is also returned by the
796	<code>Info::weight()</code> method, which may be more convenient to use.
797
798
799	<h3>(vi) Reject the decay sequence of resonances</h3>
800
801	Resonance decays are performed already at the process level, as
802	an integrated second step of the hard process itself. One reason is
803	that the matrix element of many processes encode nontrivial decay
804	angular distributions. Another is to have equivalence with Les Houches
805	input, where resonance decays typically are provided from the onset.
806	The methods in this section allow you to veto that decay sequence and
807	try a new one. Unlike the veto of the whole process-level step,
808	in point (i), the first step of the hard process is retained, i.e.
809	where the resonances are produced. For this reason the cross section
810	is not affected here but, depending on context, you may want to introduce
811	your own counters to check how often a new set of decay modes and
812	kinematics is selected, and correct accordingly.
813
814	<p/>The main method below is applied after all decays. For the production
815	of a <i>t tbar</i> pair this typically means after four decays,
816	namely those of the <i>t</i>, the <i>tbar</i>, the <i>W+</i>
817	and the <i>W-</i>. If Les Houches events are processed, the rollback
818	is to the level of the originally read events. For top, that might mean
819	either to the tops, or to the <i>W</i> bosons, or no rollback at all,
820	depending on how the process generation was set up.
821
822	<a name="method34"></a>
823	<p/><strong>virtual bool UserHooks::canVetoResonanceDecays()  </strong> <br/>
824	In the base class this method returns false. If you redefine it
825	to return true then the method <code>doVetoResonanceDecays(...)</code>
826	will be called immediately after the resonance decays have been
827	selected and stored in the <code>process</code> event record,
828	as described above for <code>canVetoProcessLevel()</code>.
829
830
831	<a name="method35"></a>
832	<p/><strong>virtual bool UserHooks::doVetoResonanceDecays(Event& process)  </strong> <br/>
833	can optionally be called, as described above. You can study the
834	<code>process</code> event record of the hard process.
835	Based on that you can decide whether to reject the sequence of
836	resonance decays that was not already fixed by the production step
837	of the hard process (which can vary depending on how a process has
838	been set up, see above). If you veto, then a new resonance decay
839	sequence is selected, but the production step remains unchanged.
840	The cross section remains unaffected by this veto, for better or worse.
841	<br/><b>Warning:</b> Normally you should not modify the <code>process</code>
842	event record. However, as an extreme measure, parts or the complete decay
843	chain could be overwritten. If so, be very careful.
844
845
846	<h3>(vii) Modify scale in shower evolution</h3>
847
848	The choice of maximum shower scale in resonance decays is normally not a
849	big issue, since the shower here is expected to cover the full phase
850	space. In some special cases a matching scheme is intended, where hard
851	radiation is covered by matrix elements, and only softer by showers. The
852	below two methods support such an approach. Note that the two methods
853	are not used in the <code>TimeShower</code> class itself, but when
854	showers are called from the <code>PartonLevel</code> generation. Thus
855	user calls directly to <code>TimeShower</code> are not affected.
856
857	<a name="method36"></a>
858	<p/><strong>virtual bool UserHooks::canSetResonanceScale()  </strong> <br/>
859	In the base class this method returns false. If you redefine it
860	to return true then the method <code>scaleResonance(...)</code>
861	will set the initial scale of downwards shower evolution.
862
863	<a name="method37"></a>
864	<p/><strong>virtual double UserHooks::scaleResonance( int iRes, const Event& event)  </strong> <br/>
865	can optionally be called, as described above. You should return the maximum
866	scale, in GeV, from which the shower evolution will begin. The base class
867	method returns 0, i.e. gives no shower evolution at all.
868	You can study, but not modify, the <code>event</code> event record
869	of the partonic process to check which resonance is decaying, and into what.
870	<br/><code>argument</code><strong> iRes </strong> : is the location in the event record of the
871	resonance that decayed to the particles that now will shower.
872
873	<br/><code>argument</code><strong> event </strong> : the event record contains a list of all partons
874	generated so far, specifically the decaying resonance and its immediate
875	decay products.
876
877
878
879	</body>
880	</html>
881
882	<!-- Copyright (C) 2012 Torbjorn Sjostrand -->

Note: See TracBrowser for help on using the repository browser.

Context Navigation

source: HiSusy/trunk/Pythia8/pythia8170/htmldoc/UserHooks.html @ 1

Download in other formats: