Context Navigation

← Previous Revision
Latest Revision
Next Revision →
Blame
Revision Log

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

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

Context Navigation

source: HiSusy/trunk/Pythia8/pythia8170/phpdoc/UserHooks.php @ 1

Download in other formats: