Context Navigation

← Previous Revision
Latest Revision
Next Revision →
Blame
Revision Log

ImplementNewShowers.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: 24.5 KB

Line
1	<html>
2	<head>
3	<title>Implement New Showers</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>Implement New Showers</h2>
10
11	In case you want to replace the PYTHIA initial- and final-state
12	showers by your own, it is possible but not trivial. The point is
13	that multiparton interactions (MPI), initial-state radiation (ISR) and
14	final-state radiation (FSR) in general appear in one single
15	interleaved sequence of decreasing <i>pT</i> values. Therefore
16	shower replacements would have to be able to play the game by such
17	rules, as we will outline further below. Of course, this still
18	leaves the field open exactly how to define what to mean by
19	<i>pT</i>, how to handle recoil effects, how the colour flow is
20	affected, and so on, so there is certainly room for alternative
21	showers. A first example of a shower implemented within the PYTHIA
22	context is <a href="http://home.fnal.gov/~skands/vincia/">VINCIA</a>,
23	which however so far only handles FSR.
24
25	<p/>
26	For the moment we assume you want to keep the MPI part of the story
27	unchanged, and make use of the existing beam-remnants (BR) machinery.
28	If you want to replace both MPI, ISR, FSR and BR then you had better
29	replace the whole <code>PartonLevel</code> module of the code.
30	If, in addition, you want to produce your own hard processes,
31	then you only need the
32	<a href="HadronLevelStandalone.html" target="page">hadron-level standalone</a>
33	part of the machinery.
34
35	<p/>
36	In order to write replacement codes for ISR and/or FSR it is useful
37	to be aware of which information has to be shared between the
38	different components, and which input/output structure is required
39	of the relevant methods. For details, nothing beats studying the
40	existing code. However, here we provide an overview, that should
41	serve as a useful introduction.
42
43	<p/>
44	It should be noted that we here primarily address the problem in
45	its full generality, with interleaved MPI, ISR and FSR. There exists
46	an option <code>TimeShower:interleave = off</code> where only
47	MPI and ISR would be interleaved and FSR be considered after these
48	two, but still before BR. Most of the aspects described here would
49	apply also for that case. By contrast, resonance decays are only
50	considered after all the four above components, and timelike
51	showers in those decays would never be interleaved with anything
52	else, so are much simpler to administrate.
53
54	<p/>
55	Therefore the <code><a href="ProgramFlow.html" target="page">
56	pythia.setShowerPtr( timesDecPtr, timesPtr, spacePtr)</a></code>
57	method allows two separate pointers to be set to instances of
58	derived <code>TimeShower</code> classes. The first is only required
59	to handle decays, say of <i>Z^0</i> or <i>Upsilon</i>, with no
60	dependence on beam remnants or ISR. The second, as well as
61	<code>spacePtr</code>, has to handle the interleaved evolution of MPI,
62	ISR and FSR. Therefore you are free to implement only the first, and
63	let the PYTHIA default showers take care of the latter two. But, if
64	you wanted to, you could also set <code>timesDecPtr = 0</code> and
65	only provide a <code>timesPtr</code>, or only a <code>spacePtr</code>.
66	If your timelike shower does both cases, the first two pointers
67	can agree. The only tiny point to take into account then is that
68	<code>init( beamAPtr, beamBPtr)</code> is called twice, a first time
69	to <code>timesDecPtr</code> with beam pointers 0, and a second time
70	to <code>timesPtr</code> with nonvanishing beam pointers.
71
72	<h3>The event record and associated information</h3>
73
74	Obviously the main place for sharing information is the event
75	record, specifically the <code>Event event</code> member of
76	<code>Pythia</code>, passed around as a reference. It is
77	assumed you already studied how it works, so here we only draw
78	attention to a few aspects of special relevance.
79
80	<p/>
81	One basic principle is that existing partons should not be
82	overwritten. Instead new partons should be created, even when a
83	parton only receives a slightly shifted momentum and for the rest
84	stays the same. Such "carbon copies" by final-state branchings
85	should be denoted by both daughter indices of the original parton
86	pointing to the copy, and both mother indices of the copy to the
87	original. If the copy instead is intended to represent an earlier
88	step, e.g. in ISR backwards evolution, the role of mothers and
89	daughters is interchanged. The
90	<code>event.copy( iCopy, newStatus)</code>
91	routine can take care of this tedious task; the sign of
92	<code>newStatus</code> tells the program which case to assume.
93
94	<p/>
95	To make the event record legible it is essential that the
96	<a href="ParticleProperties.html" target="page">status codes</a>
97	are selected appropriately to represent the reason why each new
98	parton is added to the record. Also remember to change the
99	status of a parton to be negative whenever an existing parton
100	is replaced by a set of new daughter partons.
101
102	<p/>
103	Another important parton property is <code>scale()</code>,
104	which does not appear in the normal event listing, but only
105	if you use the extended
106	<code>Event:listScaleAndVertex = on</code> option.
107	This property is supposed to represent the production scale
108	(in GeV) of a parton. In the current FSR and ISR algorithms
109	it is used to restrict from above the allowed <i>pT</i>
110	values for branchings of this particular parton.
111	Beam remnants and other partons that should not radiate are
112	assigned scale 0.
113
114	<p/>
115	Auxiliary to the event record proper is the
116	<code><a href="AdvancedUsage.html" target="page">PartonSystems</a></code>
117	class, that keep track of which partons belong together in the
118	same scattering subsystem. This information must be kept up-to-date
119	during the shower evolution.
120
121	<p/>
122	For initial-state showers it is also necessary to keep track of
123	the partonic content extracted from the beams. This information
124	is stored in the
125	<code><a href="AdvancedUsage.html" target="page">BeamParticle</a></code>
126	class.
127
128	<h3>The TimeShower interface</h3>
129
130	If you want to replace the <code>TimeShower</code> class this would
131	involve replacing the virtual methods among the following ones.
132
133	<a name="method1"></a>
134	<p/><strong>TimeShower::TimeShower()  </strong> <br/>
135	The constructor does not need to do anything.
136
137
138	<a name="method2"></a>
139	<p/><strong>virtual TimeShower::~TimeShower()  </strong> <br/>
140	The destructor does not need to do anything.
141
142
143	<a name="method3"></a>
144	<p/><strong>void TimeShower::initPtr(Info* infoPtr, Settings* settingsPtr, ParticleData* particleDataPtr, Rndm* rndmPtr, CoupSM* coupSMPtr, PartonSystems* partonSystemsPtr, UserHooks* userHooksPtr)  </strong> <br/>
145	This method only imports pointers to standard facilities,
146	and is not virtual.
147
148
149	<a name="method4"></a>
150	<p/><strong>virtual void TimeShower::init( BeamParticle* beamAPtrIn = 0, BeamParticle* beamBPtrIn = 0)  </strong> <br/>
151	You have to store your local copy of the pointers to these objects,
152	since they have to be used during the generation, as explained above.
153	The pointers could be zero; e.g. a local copy of <code>TimeShower</code>
154	is created to handle showers in decays such as <i>Upsilon -> q qbar</i>
155	from inside the <code>ParticleDecays class</code>. This is also the
156	place to do initialization of whatever parameters you plan to use,
157	e.g. by reading in them from a user-accessible database like the
158	<code>Settings</code> one.
159
160
161	<a name="method5"></a>
162	<p/><strong>virtual bool TimeShower::limitPTmax( Event& event, double Q2Fac = 0., double Q2Ren = 0.)  </strong> <br/>
163	The question is whether the FSR should be allowed to occur at larger
164	scales than the hard process it surrounds. This is process-dependent,
165	as illustrated below for the the analogous
166	<code>SpaeShower::limitPTmax(...)</code> method, although the two
167	kinds of radiation need not have to be modelled identically.
168	The <code>TimeShower:pTmaxMatch</code> switch allows you to force the
169	behaviour among three options, but you may replace by your own logic.
170	<br/>The internal PYTHIA implementation also allows intermediate options,
171	where emissions can go up to the kinematical limit but be dampened above
172	the factorization or renormalization scale. Therefore the (square of the)
173	latter two are provided as optional input parameters.
174
175
176	<a name="method6"></a>
177	<p/><strong>double TimeShower::enhancePTmax()  </strong> <br/>
178	Relative to the default <i>pT_max</i> evolution scale of the process,
179	it may still be convenient to vary the matching slightly for the hardest
180	interaction in an event, to probe the sensitivity to such details. The
181	base-class implementation returns the value of the
182	<code>TimeShower:pTmaxFudge</code> parameter.
183
184
185	<a name="method7"></a>
186	<p/><strong>virtual int TimeShower::shower( int iBeg, int iEnd, Event& event, double pTmax, int nBranchMax = 0)  </strong> <br/>
187	This is an all-in-one call for shower evolution, and as such cannot be
188	used for the normal interleaved evolution, where only the routines below
189	are used. It also cannot be used in resonance decays that form part of
190	the hard process, since there the
191	<a href="UserHooks.html" target="page">user hooks</a> insert a potential
192	veto step. Currently this routine is therefore only used in the
193	hadron-level decays, e.g. <i>Upsilon -> g g g</i>.
194	<br/><code>iBeg</code> and <code>iEnd</code> is the position of the
195	first and last parton of a separate system, typically produced by a
196	resonance decay. Such a system only evolves in isolation, and in
197	particular does not relate to the beams.
198	<br/>The <code>pTmax</code> value sets the maximum scale for evolution,
199	but normally you would restrict that further for each individual
200	parton based on its respective scale value.
201	<br/>The <code>nBranchMax</code> value, if positive, gives the maximum
202	number of allowed branchings in the call, as useful for matching studies.
203	<br/>The routine is expected to return the number of FSR branchings that
204	were generated, but only for non-critical statistics purposes.
205	<br/>Since the real action typically is delegated to the routines
206	below, it may well be that the existing code need not be replaced.
207
208
209	<a name="method8"></a>
210	<p/><strong>double TimeShower::pTLastInShower()  </strong> <br/>
211	Can be used to return the <i>pT</i> evolution scale of the last
212	branching in the cascade generated with the above
213	<code>shower(...)</code> method. Is to be set in the internal
214	<code>pTLastInShower</code> variable, and should be 0 if there
215	were no branchings. Can be useful for matching studies.
216
217
218	<a name="method9"></a>
219	<p/><strong>virtual void TimeShower::prepare( int iSys, Event& event)  </strong> <br/>
220	This method is called immediately after a new interaction (or the
221	products of a resonance decay) has been added, and should then be used
222	to prepare the subsystem of partons for subsequent evolution. In
223	the current code this involves identifying all colour and charge
224	dipole ends: the position of radiating and recoiling partons, maximum
225	<i>pT</i> scales, possible higher-order matrix elements matchings
226	to apply, and so on.
227	<br/>The <code>iSys</code> parameter specifies which parton system
228	is to be prepared. It is used to extract the set of partons to be
229	treated, with rules as described in the above section on subsystems.
230	Specifically, the first two partons represent the incoming state,
231	or are 0 for resonance decays unrelated to the beams, while the
232	rest are not required to be in any particular order.
233
234
235	<a name="method10"></a>
236	<p/><strong>virtual void TimeShower::rescatterUpdate( int iSys, Event& event)  </strong> <br/>
237	This method is called immediately after rescattering in the description
238	of multiparton interactions. Thus the information on one or several
239	systems is out-of-date, while that of the others is unchanged.
240	We do not provide the details here, since we presume few implementors
241	of new showers will want to touch the technicalities involved
242	in obtaining a description of rescattering.
243
244
245	<a name="method11"></a>
246	<p/><strong>virtual void TimeShower::update( int iSys, Event& event)  </strong> <br/>
247	This method is called immediately after a spacelike branching in the
248	<code>iSys</code>'th subsystem. Thus the information for that system is
249	out-of-date, while that of the others is unchanged. If you want, you are
250	free to throw away all information for the affected subsystem and call
251	<code>prepare( iSys, event)</code> to create new one. Alternatively
252	you may choose only to update the information that has changed.
253
254
255	<a name="method12"></a>
256	<p/><strong>virtual double TimeShower::pTnext( Event& event, double pTbegAll, double pTendAll)  </strong> <br/>
257	This is the main driver routine for the downwards evolution. A new
258	<i>pT</i> is to be selected based on the current information set up
259	by the routines above, and along with that a branching parton or dipole.
260	The <code>pTbegAll</code> scale is the maximum scale allowed, from which
261	the downwards evolution should be begun (usually respecting the maximum
262	scale of each individual parton). If no emission is found above
263	<code>pTendAll</code> (and above the respective shower cutoff scales)
264	then <code>0.</code> should be returned and no emissions will be allowed.
265	Both scales can vary from one event to the next: if a scale has
266	already been selected for MPI or ISR it makes no sense to look for
267	a scale smaller than that from FSR, since it would not be able to
268	compete, so <code>pTendAll</code> is set correspondingly. As it happens,
269	FSR is tried before ISR and MPI in the interleaved evolution,
270	but this is an implementational detail that could well change.
271	<br/>Typically the implementation of this routine would be to set
272	up a loop over all possible radiating objects (dipoles, dipole ends, ...),
273	for each pick its possible branching scale and then pick the one
274	with largest scale as possible winner. At this stage no branching should
275	actually be carried out, since MPI, ISR and FSR still have to be compared
276	to assign the winner.
277
278
279	<a name="method13"></a>
280	<p/><strong>virtual bool TimeShower::branch( Event& event, bool isInterleaved = false)  </strong> <br/>
281	This method will be called once FSR has won the competition with
282	MPI and ISR to do the next branching. The candidate branching found
283	in the previous step should here be carried out in full. The
284	pre-branching partons should get a negative status code and new
285	replacement ones added to the end of the event record. Also the
286	subsystem information should be updated, and possibly also the
287	beams.
288	<br/>Should some problem be encountered in this procedure, e.g. if
289	some not-previously-considered kinematics requirement fails, it is
290	allowed to return <code>false</code> to indicate that no branching
291	could be carried out.
292	<br/>Normally the optional <code>isInterleaved</code> argument would
293	not be of interest. It can be used to separate resonance decays, false,
294	from the interleaved evolution together with MPI and ISR, true.
295	More precisely, it separates calls to the <code>timesDecPtr</code>
296	and the <code>timesPtr</code> instances.
297
298
299	<a name="method14"></a>
300	<p/><strong>virtual bool TimeShower::rescatterPropogateRecoil( Event& event, Vec4& pNew)  </strong> <br/>
301	This method is only called if rescattering is switched on in the
302	description of multiparton interactions. It then propagates a recoil
303	from a timelike branching to internal lines that connect systems.
304	As for <code>rescatterUpdate</code> above, this is not likely to be
305	of interest to most implementors of new showers.
306
307
308	<a name="method15"></a>
309	<p/><strong>int TimeShower::system()  </strong> <br/>
310	This method is not virtual. If a branching is constructed by the
311	previous routine this tiny method should be able to return the number
312	of the selected subsystem <code>iSysSel</code> where it occured,
313	so that the spacelike shower can be told which system to update,
314	if necessary. Therefore <code>iSysSel</code> must be set in
315	<code>branch</code> (or already in <code>pTnext</code>).
316
317
318	<a name="method16"></a>
319	<p/><strong>virtual void TimeShower::list( ostream& os = cout)  </strong> <br/>
320	This method is not at all required. In the current implementation it
321	outputs a list of all the dipole ends, with information on the
322	respective dipole. The routine is not called anywhere in the public
323	code, but has been inserted at various places during the
324	development/debug phase.
325
326
327	<h3>The SpaceShower interface</h3>
328
329	If you want to replace the <code>SpaceShower</code> class this would
330	involve replacing the virtual methods in the following. You will find
331	that much of the story reminds of <code>TimeShower</code> above, and
332	actually some cut-and-paste of text is involved. In some respects the
333	description is simpler, since there are no special cases for resonance
334	decays and non-interleaved evolution. Thus there is no correspondence
335	to the <code>TimeShower::shower(...)</code> routine.
336
337	<a name="method17"></a>
338	<p/><strong>SpaceShower::SpaceShower()  </strong> <br/>
339	The constructor does not need to do anything.
340
341
342	<a name="method18"></a>
343	<p/><strong>virtual SpaceShower::~SpaceShower()  </strong> <br/>
344	Also the destructor does not need to do anything.
345
346
347	<a name="method19"></a>
348	<p/><strong>void SpaceShower::initPtr(Info* infoPtr, Settings* settingsPtr, ParticleData* particleDataPtr, Rndm* rndmPtr, PartonSystems* partonSystemsPtr, UserHooks* userHooksPtr)  </strong> <br/>
349	This method only imports pointers to standard facilities,
350	and is not virtual.
351
352
353	<a name="method20"></a>
354	<p/><strong>virtual void SpaceShower::init( BeamParticle* beamAPtrIn, BeamParticle* beamBPtrIn)  </strong> <br/>
355	You have to store your local copy of the pointers to these objects,
356	since they have to be used during the generation, as explained above.
357	This is also the place to do initialization of whatever parameters
358	you plan to use, e.g. by reading in them from a user-accessible
359	database like the <code>Settings</code> one.
360
361
362	<a name="method21"></a>
363	<p/><strong>virtual bool SpaceShower::limitPTmax( Event& event, double Q2Fac = 0., double Q2Ren = 0.)  </strong> <br/>
364	The question is whether the ISR should be allowed to occur at larger
365	scales than the hard process it surrounds. This is process-dependent.
366	For instance, if the hard process is <i>Z^0</i> production we know
367	that ISR should be allowed to go right up to the kinematical limit.
368	If it is a <i>2 -> 2</i> QCD process the ISR should not exceed
369	the scale of the hard process, since if so one would doublecount.
370	The <code>SpaceShower:pTmaxMatch</code> switch allows you to force the
371	behaviour, or else to program your own logic. The current default
372	implementation limits <i>pT</i> whenever the final state contains
373	a quark (except top), gluon or photon, since then the danger of
374	doublecounting is there. You may replace by your own logic, or leave as is.
375	<br/>The internal PYTHIA implementation also allows intermediate options,
376	where emissions can go up to the kinematical limit but be dampened above
377	the factorization or renormalization scale. Therefore the (square of the)
378	latter two are provided as optional input parameters.
379
380
381	<a name="method22"></a>
382	<p/><strong>virtual double SpaceShower::enhancePTmax()  </strong> <br/>
383	When the above method limits <i>pT_max</i> to the scale of the process,
384	it may still be convenient to vary the matching slightly for the hardest
385	interaction in an event, to probe the sensitivity to such details. The
386	base-class implementation returns the value of the
387	<code>SpaceShower:pTmaxFudge</code> parameter.
388
389
390	<a name="method23"></a>
391	<p/><strong>virtual void SpaceShower::prepare( int iSys, Event& event, bool limitPTmax = true)  </strong> <br/>
392	This method is called immediately after a new interaction has been
393	added, and should then be used to prepare the subsystem of partons
394	for subsequent evolution. In the current code this involves identifying
395	the colour and charge dipole ends: the position of radiating and recoiling
396	partons, maximum <i>pT</i> scales, and possible higher-order matrix
397	elements matchings to apply. Depending on what you have in mind you may
398	choose to store slightly different quantities. You have to use the
399	subsystem information described above to find the positions of the two
400	incoming partons (and the outgoing ones) of the system, and from there
401	the scales at which they were produced.
402	<br/> The <code>limitPTmax</code> input agrees with the output of the
403	previous method for the hardest process, and is always true for
404	subsequent MPI, since there an unlimited <i>pT</i> for sure
405	would lead to doublecounting.
406
407
408	<a name="method24"></a>
409	<p/><strong>virtual void SpaceShower::update( int iSys, Event& event)  </strong> <br/>
410	This method is called immediately after a timelike branching in the
411	<code>iSys</code>'th subsystem. Thus the information for that system may
412	be out-of-date, and to be updated. For the standard PYTHIA showers
413	this routine does not need to do anything, but that may be different
414	in another implementation.
415
416
417	<a name="method25"></a>
418	<p/><strong>virtual double SpaceShower::pTnext( Event& event, double pTbegAll, double pTendAll, int nRadIn = -1)  </strong> <br/>
419	This is the main driver routine for the downwards evolution. A new
420	<i>pT</i> is to be selected based on the current information set up
421	by the routines above, and along with that a branching parton or dipole.
422	The <code>pTbegAll</code> scale is the maximum scale allowed, from which
423	the downwards evolution should be begun (usually respecting the maximum
424	scale of each individual parton). If no emission is found above
425	<code>pTendAll</code> (and above the respective shower cutoff scales)
426	then <code>0.</code> should be returned and no emissions will be allowed.
427	Both scales can vary from one event to the next: if a scale has
428	already been selected for MPI or ISR it makes no sense to look for
429	a scale smaller than that from FSR, since it would not be able to
430	compete, so <code>pTendAll</code> is set correspondingly. As it happens,
431	FSR is tried before ISR and MPI in the interleaved evolution,
432	but this is an implementational detail that could well change.
433	<br/>Typically the implementation of this routine would be to set
434	up a loop over all possible radiating objects (dipoles, dipole ends, ...),
435	for each pick its possible branching scale and then pick the one
436	with largest scale as possible winner. At this stage no branching should
437	actually be carried out, since MPI, ISR and FSR still have to be compared
438	to assign the winner.
439	<br/>The final input <code>nRadIn</code> provides the total number of
440	ISR and FSR emissions already generated in the event, and so allows a
441	special treatment for the very first emission, if desired.
442
443
444	<a name="method26"></a>
445	<p/><strong>virtual bool SpaceShower::branch( Event& event)  </strong> <br/>
446	This method will be called once FSR has won the competition with
447	MPI and ISR to do the next branching. The candidate branching found
448	in the previous step should here be carried out in full. The
449	pre-branching partons should get a negative status code and new
450	replacement ones added to the end of the event record. Also the
451	subsystem information should be updated, and possibly also the
452	beams.
453	<br/>Should some problem be encountered in this procedure, e.g. if
454	some not-previously-considered kinematics requirement fails, it is
455	allowed to return <code>false</code> to indicate that no branching
456	could be carried out. Also a complete restart of the parton-level
457	description may be necessary, see <code>doRestart()</code> below.
458
459
460	<a name="method27"></a>
461	<p/><strong>int SpaceShower::system()  </strong> <br/>
462	This method is not virtual. If a branching is constructed by the
463	previous routine this tiny method should be able to return the number
464	of the selected subsystem <code>iSysSel</code> where it occured,
465	so that the spacelike shower can be told which system to update,
466	if necessary. Therefore <code>iSysSel</code> must be set in
467	<code>branch</code> (or already in <code>pTnext</code>).
468
469
470	<a name="method28"></a>
471	<p/><strong>bool SpaceShower::doRestart()  </strong> <br/>
472	This method is not virtual. If <code>branch(...)</code> above fails
473	to construct a branching, and the conditions are such that the whole
474	parton-level description should be restarted, then it should return
475	true, else not. Currently only the rescattering description can give
476	thi kind of failures, and so the internal <code>rescatterFail</code>
477	boolean must be set true when this should happen, and else false.
478
479
480	<a name="method29"></a>
481	<p/><strong>virtual void SpaceShower::list( ostream& os = cout)  </strong> <br/>
482	This method is not at all required. In the current implementation it
483	outputs a list of all the dipole ends, with information on the
484	respective dipole. The routine is not called anywhere in the public
485	code, but has been inserted at various places during the
486	development/debug phase.
487
488
489	</body>
490	</html>
491
492	<!-- Copyright (C) 2012 Torbjorn Sjostrand -->

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

Context Navigation

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

Download in other formats: