Update to pythi8.170
[u/mrichter/AliRoot.git] / PYTHIA8 / pythia8170 / xmldoc / PhaseSpaceCuts.xml
1 <chapter name="Phase Space Cuts">
2
3 <h2>Phase Space Cuts</h2>
4
5 <code>PhaseSpace</code> is base class for all hard-process phase-space 
6 generators, either generic <ei>2 -> 1</ei> or <ei>2 -> 2</ei> ones, 
7 or specialized ones like for elastic and diffractive scattering.
8
9 <p/>
10 In it, it is possible to constrain the kinematics of most processes.
11 (Exceptions are "soft physics", i.e. minimum bias, elastic and 
12 diffractive processes. The Coulomb singularity for elastic scatterings,
13 if simulated, is <aloc href="TotalCrossSections">handled separately</aloc>.) 
14 These constraints apply in the rest frame of the hard subprocess, and 
15 topologies normally would be changed e.g. by subsequent showering 
16 activity. The cross section of a process is adjusted to only 
17 correspond to the allowed phase space.
18
19 <p/>
20 The more particles in the final state, the more cuts could be applied.
21 Here we have tried to remain with the useful minimum, however. More
22 generic possibilities could be handled by the 
23 <aloc href="UserHooks">user hooks</aloc> facility. 
24
25 <h3>Cuts in all processes</h3>
26
27 <parm name="PhaseSpace:mHatMin" default="4." min="0.">
28 The minimum invariant mass.
29 </parm>
30
31 <parm name="PhaseSpace:mHatMax" default="-1.">
32 The maximum invariant mass.
33 A value below <code>mHatMin</code> means there is no upper limit.
34 </parm>
35
36 <h3>Cuts in <ei>2 -> 1</ei> processes</h3>
37
38 When a resonance <code>id</code> is produced, the 
39 <code><aloc href="ParticleDataScheme">mMin(id)</aloc></code> and 
40 <code><aloc href="ParticleDataScheme">mMax(id)</aloc></code> 
41 methods restrict the allowed mass range
42 of this resonance. Therefore the allowed range is chosen to be the 
43 overlap of this range and the <code>mHatMin</code> to 
44 <code>mHatMax</code> range above. Most resonances by default have no 
45 upper mass limit, so effects mainly concern the lower limit. 
46 Should there be no overlap between the two ranges then the process 
47 will be switched off.
48
49 <h3>Cuts in <ei>2 -> 2</ei> processes</h3>
50
51 <parm name="PhaseSpace:pTHatMin" default="0." min="0.">
52 The minimum invariant <ei>pT</ei>.
53 </parm>
54
55 <parm name="PhaseSpace:pTHatMax" default="-1.">
56 The maximum invariant <ei>pT</ei>.
57 A value below <code>pTHatMin</code> means there is no upper limit.
58 </parm>
59
60 <parm name="PhaseSpace:pTHatMinDiverge" default="1." min="0.5">
61 Extra <ei>pT</ei> cut to avoid the divergences of some processes 
62 in the limit <ei>pT -> 0</ei>. Specifically, if either or both
63 produced particles have a mass below <code>pTHatMinDiverge</code> 
64 then <ei>pT</ei> is limited from below by the larger of 
65 <code>pTHatMin</code> and <code>pTHatMinDiverge</code>.
66 </parm>
67
68 <flag name="PhaseSpace:useBreitWigners" default="on">
69 Allows masses to be selected according to Breit-Wigner shapes in 
70 <ei>2 -> 2</ei> processes, whenever particles have been declared 
71 with a nonvanishing width above the threshold below. In those cases 
72 also the limits below will be used for the mass selection. For 
73 <ei>2 -> 1</ei> processes the Breit-Wigner shape is part of the 
74 cross section itself, and therefore always included.
75 </flag>
76
77 <parm name="PhaseSpace:minWidthBreitWigners" default="0.01" min="1e-6">
78 The minimum width a resonance must have for the mass to be dynamically
79 selected according to a Breit-Wigner shape, within the limits set below.
80 Only applies when <code>useBreitWigners</code> is on; else the nominal
81 mass value is always used.
82 </parm>
83
84 <p/>
85 For a particle with a Breit-Wigner shape selected, according to the 
86 rules above and to the rules of the particle species itself, the 
87 <code><aloc href="ParticleDataScheme">mMin(id)</aloc></code> and 
88 <code><aloc href="ParticleDataScheme">mMax(id)</aloc></code> 
89 methods restrict the allowed mass range of the particle, just like for 
90 the <ei>2 -> 1 </ei> processes.   
91
92 <h3>Cuts in <ei>2 -> 3</ei> processes</h3>
93
94 There are two main classes of <ei>2 -> 3</ei> processes. One is the 
95 processes such as <ei>WW/ZZ</ei>-fusion Higgs production, i.e.
96 <ei>q q -> q q H</ei>, where there are no special singularities 
97 associated with two partons in the final state being collinear,
98 or even for <ei>pT -> 0</ei>. For this class, no further cuts 
99 have been introduced than those already available for <ei>2 -> 2</ei> 
100 processes. Specifically, for now all three are restricted exactly the 
101 same way by <code>pTHatMin</code> and <code>pTHatMax</code>. As above, 
102 Breit-Wigner mass ranges can be restricted.
103
104 <p/>
105 The other <ei>2 -> 3</ei> event class is QCD processes, such as 
106 <ei>g g -> g g g</ei>. Here the soft and collinear singularities 
107 play a major role, and the phase space generation and cuts have 
108 been adapted to this. For this class, an alternative set of cuts 
109 is used, as outlined in the following. First of all the three
110 outgoing partons are ordered in falling <ei>pT</ei>, i.e. 
111 <ei>pT_3 > pT_4 > pT_5</ei> (where the labelling 3, 4, 5 of the outgoing 
112 partons is random, i.e. unrelated to the order specified in the
113 process name). The allowed ranges of <ei>pT_3</ei> and <ei>pT_5</ei>
114 can be specified, but obviously <ei>pT_3max >= pT_5max</ei> and
115 <ei>pT_3min >= pT_5min</ei>. The <ei>pT_4</ei> is not constrained 
116 explicitly, but is constructed from the vector sum of <ei>pT_3</ei>
117 and <ei>pT_5</ei>, subject to the constraint that it has to lie
118 between the two in magnitude. While the <ei>pT</ei> cuts take care
119 of singularities collinear with the incoming beams, it is also 
120 necessary to handle final-state singularities, when two outgoing
121 partons become collinear. This is done by requiring a minimal 
122 separation in <ei>R</ei>, where 
123 <ei>R^2 = (Delta eta)^2 + (Delta phi)^2</ei>. 
124 Finally, a note about efficiency. The QCD <ei>2 -> 3</ei> phase space 
125 is not set up to explicitly include <ei>mHat</ei> as one of the basic
126 variables. Such a cut is only done after a phase space point is already 
127 selected, which means that a narrow mass choice will slow down the 
128 program appreciably. Also narrow <ei>pT_3</ei> and <ei>pT_5</ei> bins
129 are likely to give inefficient generation, if it gives rise to
130 significant indirect restrictions on <ei>pT_4</ei>. 
131
132 <parm name="PhaseSpace:pTHat3Min" default="10." min="0.">
133 The minimum invariant <ei>pT</ei> of the highest-<ei>pT</ei> parton in
134 QCD <ei>2 -> 3</ei> processes.
135 </parm>
136
137 <parm name="PhaseSpace:pTHat3Max" default="-1.">
138 The maximum invariant <ei>pT</ei> of the highest-<ei>pT</ei> parton in
139 QCD <ei>2 -> 3</ei> processes
140 A value below <code>pTHat3Min</code> means there is no upper limit.
141 </parm>
142
143 <parm name="PhaseSpace:pTHat5Min" default="10." min="0.">
144 The minimum invariant <ei>pT</ei> of the lowest-<ei>pT</ei> parton in
145 QCD <ei>2 -> 3</ei> processes.
146 </parm>
147
148 <parm name="PhaseSpace:pTHat5Max" default="-1.">
149 The maximum invariant <ei>pT</ei> of the lowest-<ei>pT</ei> parton in
150 QCD <ei>2 -> 3</ei> processes
151 A value below <code>pTHat5Min</code> means there is no upper limit.
152 </parm>
153
154 <parm name="PhaseSpace:RsepMin" default="1.">
155 The minimum separation <ei>R</ei> in <ei>(eta, phi)</ei> space between
156 any two outgoing partons in QCD <ei>2 -> 3</ei> processes.
157 </parm>
158
159
160 <h3>Cuts for a second hard process</h3>
161
162 If you use the machinery that allows the generation of a specified 
163 <aloc href="ASecondHardProcess">second hard process</aloc> then,
164 by default, the same phase space cuts will be used for it as listed
165 above. Optionally, however, you may use a second set of cuts, as 
166 described here. In this context "first" and "second" is merely a 
167 technical distinction; you are welcome e.g. to pick <ei>pT</ei> ranges 
168 such that the second interaction always has a larger <ei>pT</ei> than 
169 the first.
170
171 <flag name="PhaseSpace:sameForSecond" default="on">
172 By default use the same cuts for a second hard process as for the 
173 first. If <code>off</code> then instead use the mass and <ei>pT</ei>
174 cuts below, where relevant. (The other cuts above still remain the same.)  
175 </flag>
176
177 <parm name="PhaseSpace:mHatMinSecond" default="4." min="0.">
178 The minimum invariant mass for a second interaction, if separate.
179 </parm>
180
181 <parm name="PhaseSpace:mHatMaxSecond" default="-1.">
182 The maximum invariant mass for a second interaction, if separate.
183 A value below <code>mHatMin</code> means there is no upper limit.
184 </parm>
185
186 <parm name="PhaseSpace:pTHatMinSecond" default="0." min="0.">
187 The minimum invariant <ei>pT</ei> for a second interaction, if separate.
188 </parm>
189
190 <parm name="PhaseSpace:pTHatMaxSecond" default="-1.">
191 The maximum invariant <ei>pT</ei> for a second interaction, if separate.
192 A value below <code>pTHatMin</code> means there is no upper limit.
193 </parm>
194
195 <h3>Generation strategy and documentation</h3>
196
197 During the initialization stage a simplified function is found,
198 that is intended to be above the true cross-section behaviour
199 over the whole of phase space. It is chosen to be easily integrable 
200 and invertible. That way a trial phase space point can be selected 
201 according this simple function, and then be accepted by the ratio of
202 true to the simple function. For a good efficieny the ratio should be
203 close to unity,  yet never above it. This constrains the absolute 
204 normalization of the simple function. The initial search may fail to 
205 find the phase space point where the true-to-simple ratio is maximal,
206 however. This then can lead to subsequent maximum violations, where the 
207 ratio is above unity. Two alternative strategies are implemented to 
208 handle such situations, see below.
209
210 <flag name="PhaseSpace:showSearch" default="off">
211 Possibility to print information on the search for phase-space 
212 coefficients that (in a multichannel approach) provides an analytical 
213 upper envelope of the differential cross section, and the 
214 corresponding upper estimate of the cross section. Of interest 
215 for crosschecks by expert users only. 
216 </flag>
217
218 <flag name="PhaseSpace:showViolation" default="off">
219 Possibility to print information whenever the assumed maximum 
220 differential cross section of a process is violated, i.e. when 
221 the initial maximization procedure did not find the true maximum.
222 Also, should negative cross sections occur, print whenever a more
223 negative value is encountered.
224 </flag>
225
226 <flag name="PhaseSpace:increaseMaximum" default="off">
227 Strategy for handling cases where a larger cross section is
228 obtained during the event generation than was assumed at initialization,
229 i.e. when a violation occurs.
230 <br/><b>off:</b>each event comes with a weight, which normally is unity
231 (as a consequence of the acceptance/rejection step), and is found in
232 <code><aloc href="EventInformation">Info::weight()</aloc></code>. 
233 For events which exceed the maximum instead the true-to-simple ratio 
234 is stored as event weight, which then is above unity. If the user so 
235 wishes this weight can then be carried along when event properties are
236 histogrammed. Since normally such violations should be rare and not 
237 too much above unity one could expect most users to ignore such issues
238 be default. Should maximum violations turn out to be frequent (visible
239 in the <code><aloc href="EventStatistics">Pythia::statistics()</aloc></code>
240 output) the option exists to use the information.
241 <br/><b>on:</b>the maximum is increased whenever it is exceeded. Thus
242 events generated after this point will be "correctly" distributed,
243 while ones generated previously obviously then have had too high a 
244 relative weight. If violations occur early on and/or are small this
245 strategy should do a good job of correcting to the desired phase-space
246 distribution. This strategy may be more convenient for the normal user,
247 who would not wish to worry about event weights. It does have the
248 disadvantage that the raised maximum introduces an extra amount of
249 "history memory" to the generation sequence, so that it becomes less
250 easy to save-and-restore the <aloc href="RandomNumbers">random-number 
251 state</aloc> for debugging purposes.  
252 </flag>
253
254 <h3>Reweighting of <ei>2 -> 2</ei> processes</h3>
255
256 Events normally come with unit weight, i.e. are distributed across
257 the allowed phase space region according to the appropriate differential
258 cross sections. Sometimes it may be convenient to have an uneven 
259 distribution of events. The classical example here is that many cross
260 sections drop off with transverse momentum <ei>pT</ei>, such that few
261 events are generated at large <ei>pT</ei> scales. If one wants to 
262 plot the <ei>pT</ei> cross section, and all that comes with it, the 
263 statistical error will then degrade with increasing <ei>pT</ei> 
264 where fewer events end up. 
265
266 <p/>
267 One solution is to split the full <ei>pT</ei> range into several 
268 separate subranges, where the events of each subsample obtains a 
269 different overall normalization. Specifically, if you generate a
270 comparable number of events in each <ei>pT</ei> bin, such that 
271 larger <ei>pT</ei> bins are oversampled, these bins come with a
272 correspondingly reduced overall weight, that needs to be taken into
273 account when the bins are combined. The other is to have a continuously
274 increasing oversampling of events at larger <ei>pT</ei> scales, which
275 is compensated by a continuously decreasing weight for the event.
276
277 <p/>
278 Both of these solutions are supported. Specifically, for 
279 <ei>2 -> 2</ei> processes, the <ei>pTHat</ei> scale offers a 
280 convenient classification of the event. (Of course, two events 
281 starting out from the same <ei>pTHat</ei> scale will experience
282 different parton shower evolutions, etc., and may therefore look 
283 quite different at the end.) The two cuts 
284 <code>PhaseSpace:pTHatMin</code> and <code>PhaseSpace:pTHatMax</code>
285 therefore offers a way to slice a <ei>pT</ei> range into subranges,
286 see e.g. <code>main08.cc</code>. Alternatively the 
287 <aloc href="UserHooks">User Hooks</aloc> machinery offers the 
288 possibility for you to define your own reweighting of phase space
289 sampling, with a corresponding event weight, with 
290 <code>UserHooks::canBiasSelection</code> and related methods.
291
292 <p/>
293 As a simplified option, we here offer the possibility to bias the 
294 <ei>2 -> 2</ei> sampling by a power of <ei>pTHat</ei>, then with     
295 events having a weight the inverse of this. This fast track will only
296 work under a number of strict conditions, implemented to reduce the 
297 risk of abuse. (Whereas a <code>UserHooks</code> setup can be more 
298 flexible.) Specifically it will work if only high-<ei>pT</ei>
299 <ei>2 -> 2</ei> processes already implemented in PYTHIA are requested,
300 notably the <code>HardQCD</code> ones. That is, you cannot mix with 
301 <ei>2 -> 1</ei> or <ei>2 -> 3</ei> processes, nor with external 
302 processes (notably Les Houches input) or <code>SoftQCD</code> ones, 
303 and  you cannot use the option to define a 
304 <aloc href="ASecondHardProcess">second hard process</aloc> in
305 the same event. Furthermore you have to be careful about the choice 
306 of <code>PhaseSpace:pTHatMin</code>, since a <ei>pTHat = 0</ei> 
307 event would come with an infinite weight. 
308
309 <flag name="PhaseSpace:bias2Selection" default="off">
310 Possibility to switch on a biased phase space sampling, 
311 with compensatingly weighted events, for <ei>2 -> 2</ei> processes. 
312 Can only be used under the specific conditions explained in 
313 the paragraph above; under other conditions the initialization 
314 will abort. 
315 </flag>
316
317 <parm name="PhaseSpace:bias2SelectionPow" default="4." min="0." max="10.">
318 If the above flag is on, then a <ei>2 -> 2</ei> process at a scale 
319 <ei>pTHat</ei> will be oversampled in phase space by an amount
320 <ei>(pTHat/pTRef)^pow</ei>, where you set the power <ei>pow</ei>
321 here. Events are assigned a compensating 
322 <aloc href="EventInformation">weight</aloc> the inverse of this,
323 i.e. <code>Info::weight()</code> will return <ei>(pTRef/pTHat)^pow</ei>.
324 This weight should then be used in the histogramming of event properties.
325 The final overall normalization also involves the 
326 <code>Info::weightSum()</code> value.  
327 </parm>
328
329 <parm name="PhaseSpace:bias2SelectionRef" default="10." min="1.">
330 The reference scale <ei>pTRef</ei> introduced above, such that events
331 with this <ei>pTHat</ei> obtain unit weight in the reweighting procedure.
332 The value of this parameter has no impact on the final result of the
333 reweighting procedure, but is only there for convenience, i.e. to
334 give "reasonably-sized" weights.  
335 </parm>
336
337 </chapter>
338
339 <!-- Copyright (C) 2012 Torbjorn Sjostrand -->