Fork me on GitHub

source: git/external/fastjet/contribs/Nsubjettiness/README

Last change on this file was 973b92a, checked in by Pavel Demin <pavel.demin@…>, 9 years ago

update FastJet library to 3.1.3 and Nsubjettiness library to 2.2.1

  • Property mode set to 100644
File size: 18.7 KB
Line 
1--------------------------------------------------------------------------------
2Nsubjettiness Package
3--------------------------------------------------------------------------------
4
5The Nsubjettiness package is based on the physics described in:
6
7 Identifying Boosted Objects with N-subjettiness.
8 Jesse Thaler and Ken Van Tilburg.
9 JHEP 1103:015 (2011), arXiv:1011.2268.
10
11 Maximizing Boosted Top Identification by Minimizing N-subjettiness.
12 Jesse Thaler and Ken Van Tilburg.
13 JHEP 1202:093 (2012), arXiv:1108.2701.
14
15New in v2.0 is the winner-take-all axis, which is described in:
16
17 Jet Observables Without Jet Algorithms.
18 Daniele Bertolini, Tucker Chan, and Jesse Thaler.
19 JHEP 1404:013 (2014), arXiv:1310.7584.
20
21 Jet Shapes with the Broadening Axis.
22 Andrew J. Larkoski, Duff Neill, and Jesse Thaler.
23 JHEP 1404:017 (2014), arXiv:1401.2158.
24
25 Unpublished work by Gavin Salam
26
27New in v2.2 are new measures used in the XCone jet algorithm, described in:
28
29 XCone: N-jettiness as an Exclusive Cone Jet Algorithm.
30 Iain W. Stewart, Frank J. Tackmann, Jesse Thaler,
31 Christopher K. Vermilion, and Thomas F. Wilkason.
32 arXiv:1508.01516.
33
34 Resolving Boosted Jets with XCone.
35 Jesse Thaler and Thomas F. Wilkason.
36 arXiv:1508.01518.
37
38--------------------------------------------------------------------------------
39Core Classes
40--------------------------------------------------------------------------------
41
42There are various ways to access N-(sub)jettiness variables, described
43in more detail below:
44
45Nsubjettiness [Nsubjettiness.hh]:
46 A FunctionOfPseudoJet<double> interface to measure the
47 N-subjettiness jet shape
48 (Recommended for most users)
49
50NsubjettinessRatio [Nsubjettiness.hh]:
51 A FunctionOfPseudoJet<double> interface to measure ratios of
52 two different N-subjettiness (i.e. tau3/tau2)
53 (Recommended for most users)
54
55XConePlugin [XConePlugin.hh]:
56 A FastJet plugin for using the XCone jet algorithm.
57 (Recommended for most users)
58
59NjettinessPlugin [NjettinessPlugin.hh]:
60 A FastJet plugin for finding jets by minimizing N-jettiness.
61 Same basic philosophy as XCone, but many more options.
62 (Recommended for advanced users only.)
63
64Njettiness [Njettiness.hh]:
65 Access to the core Njettiness code.
66 (Not recommended for users, since the interface might change)
67
68The code assumes that you have FastJet 3, but does not (yet) require FastJet 3.1
69
70--------------------------------------------------------------------------------
71Basic Usage: Nsubjettiness and NsubjettinessRatio [Nsubjettiness.hh]
72--------------------------------------------------------------------------------
73
74Most users will only need to use the Nsubjettiness class. The basic
75functionality is given by:
76
77 Nsubjettiness nSub(N, AxesDefinition, MeasureDefinition)
78 // N specifies the number of (sub) jets to measure
79 // AxesDefinition is WTA_KT_Axes, OnePass_KT_Axes, etc.
80 // MeasureDefinition is UnnormalizedMeasure(beta),
81 // NormalizedMeasure(beta,R0), etc.
82
83 // get tau value
84 double tauN = nSub.result(PseudoJet);
85
86Also available are ratios of N-subjettiness values
87 NsubjettinessRatio nSubRatio(N, M, AxesDefinition,
88 MeasureDefinition)
89 // N and M give tau_N / tau_M, all other options the same
90
91For example, if you just want the tau_2/tau_1 value of a jet, using recommended
92parameter choices, do this:
93
94 PseudoJet this_jet = /*from your favorite jet algorithm*/;
95 double beta = 1.0;
96 NsubjettinessRatio nSub21(2,1,
97 OnePass_WTA_KT_Axes(),
98 UnnormalizedMeasure(beta));
99 double tau21 = nSub21(this_jet);
100
101--------------------------------------------------------------------------------
102AxesDefinition [NjettinessDefinition.hh]
103--------------------------------------------------------------------------------
104
105N-(sub)jettiness requires choosing axes as well as a measure (see below). There
106are a number of axes choices available to the user, though modes with a (*) are
107recommended. Arguments in parentheses are parameters that the user must set.
108
109Axes can be found using standard recursive clustering procedures. New in v2 is
110the option to use the "winner-take-all" recombination scheme:
111(*) KT_Axes // exclusive kt axes
112 CA_Axes // exclusive ca axes
113 AntiKT_Axes(R0) // inclusive hardest axes with antikt, R0 = radius
114(*) WTA_KT_Axes // exclusive kt with winner-take-all recombination
115 WTA_CA_Axes // exclusive ca with winner-take-all recombination
116
117New in v2.2 are generalized recombination/clustering schemes:
118 GenET_GenKT_Axes(delta, p, R0 = inf)
119 WTA_GenKT_Axes(p, R0 = inf)
120 GenKT_Axes(p, R0 = inf)
121Here, delta > 0 labels the generalized ET recombination scheme (delta = 1 for
122standard ET scheme, delta = 2 for ET^2 scheme, delta = infinity for WTA scheme)
123p >= 0 labels the generalized KT clustering metric (p = 0 for ca, p = 1 for kt),
124R0 is the radius parameter, and the clustering is run in exclusive mode. The
125GenKT_Axes mode uses standard E-scheme recombination. By default the value of
126R0 is set to "infinity", namely fastjet::JetDefinition::max_allowable_R.
127
128Also new in v2.2 is option of identifying nExtra axes through exclusive
129clustering and then looking at all (N + nExtra) choose N axes and finding the
130one that gives the smallest N-(sub)jettiness value:
131 Comb_GenET_GenKT_Axes(nExtra, delta, p, R0 = inf)
132 Comb_WTA_GenKT_Axes(nExtra, p, R0 = inf)
133 Comb_GenKT_Axes(nExtra, p, R0 = inf)
134These modes are not recommended for reasons of speed.
135
136Starting from any set of seed axes, one can run a minimization routine to find
137a (local) minimum of N-(sub)jettiness. Note that the one-pass minimization
138routine is tied to the choice of MeasureDefinition.
139(*) OnePass_KT_Axes // one-pass minimization from kt starting point
140 OnePass_CA_Axes // one-pass min. from ca starting point
141 OnePass_AntiKT(R0) // one-pass min. from antikt starting point,R0=rad
142(*) OnePass_WTA_KT_Axes // one-pass min. from wta_kt starting point
143 OnePass_WTA_CA_Axes // one-pass min. from wta_ca starting point
144 OnePass_GenET_GenKT_Axes(delta, p, R0 = inf) // one-pass min. from GenET/KT
145 OnePass_WTA_GenKT_Axes(p, R0 = inf) // one-pass min from WTA/GenKT
146 OnePass_GenKT_Axes(p, R0 = inf) // one-pass min from GenKT
147
148For one-pass minimization, OnePass_CA_Axes and OnePass_WTA_CA_Axes are not
149recommended as they provide a poor choice of seed axes.
150
151In general, it is difficult to find the global minimum, but this mode attempts
152to do so:
153 MultiPass_Axes(NPass) // axes that (attempt to) minimize N-subjettiness
154 // (NPass = 100 is typical)
155This does multi-pass minimization from KT_Axes starting points.
156
157Finally, one can set manual axes:
158 Manual_Axes // set your own axes with setAxes()
159 OnePass_Manual_Axes // one-pass minimization from manual starting point
160 MultiPass_Manual_Axes(Npass) // multi-pass min. from manual
161
162If one wants to change the number of passes used by any of the axes finders, one
163can call the function
164 setNPass(NPass,nAttempts,accuracy,noise_range)
165where NPass = 0 only uses the seed axes, NPass = 1 is one-pass minimization, and
166NPass = 100 is the default multi-pass. nAttempts is the number of iterations to
167use in each pass, accuracy is how close to the minimum one tries to get, and
168noise_range is how much in rapidity/azimuth the random axes are jiggled.
169
170For most cases, running with OnePass_KT_Axes or OnePass_WTA_KT_Axes gives
171reasonable results (and the results are IRC safe). Because it uses random
172number seeds, MultiPass_Axes is not IRC safe (and the code is rather slow).
173Note that for the minimization routines, beta = 1.1 is faster than beta = 1,
174with comparable performance.
175
176--------------------------------------------------------------------------------
177MeasureDefinition [NjettinessDefinition.hh]
178--------------------------------------------------------------------------------
179
180The value of N-(sub)jettiness depends crucially on the choice of measure. Each
181measure has a different number of parameters, so one has to be careful when
182switching between measures The one indicated by (*) is the one recommended for
183use by users new to Nsubjettiness.
184
185The original N-subjettiness measures are:
186 NormalizedMeasure(beta,R0) //default normalized measure with
187 //parameters beta and R0 (dimensionless)
188(*) UnnormalizedMeasure(beta) //default unnormalized measure with just
189 //parameter beta (dimensionful)
190
191There are also measures that incorporate a radial cutoff:
192 NormalizedCutoffMeasure(beta,R0,Rcutoff) //normalized measure with
193 //additional Rcutoff
194 UnnormalizedCutoffMeasure(beta,Rcutoff) //unnormalized measure with
195 //additional Rcutoff
196
197For all of the above measures, there is an optional argument to change from the
198ordinary pt_R distance measure recommended for pp collisions to an
199E_theta distance measure recommended for ee collisions. There are also
200lorentz_dot and perp_lorentz_dot distance measures recommended only for
201advanced users.
202
203New for v2.2 is a set of measures defined in arXiv:1508.01516. First, there is
204the "conical measure":
205
206 ConicalMeasure(beta,R0) // same jets as UnnormalizedCutoffMeasure
207 // but differs in normalization and specifics
208 // of one-pass minimization
209
210Next, there is the geometric measure (as well as a modified version to yield
211more conical jet regions):
212
213 OriginalGeometricMeasure(R) // not recommended for analysis
214 ModifiedGeometricMeasure(R)
215
216(Prior to v2.2, there was a "GeometricMeasure" which unfortunately had the wrong
217definition. These have been commented out in the code as
218"DeprecatedGeometricMeasure" and "DeprecatedGeometricCutoffMeasure", but they
219should not be used.)
220
221Next, there is a "conical geometric" measure:
222
223 ConicalGeometricMeasure(beta, gamma, Rcutoff)
224
225This is a hybrid between the conical and geometric measures and is the basis for
226the XCone jet algorithm. Finally, setting to the gamma = 1 default gives the
227XCone default measure, which is used in the XConePlugin jet finder
228
229(*) XConeMeasure(beta,Rcutoff)
230
231where beta = 2 is the recommended default value and beta = 1 is the recoil-free
232default.
233
234--------------------------------------------------------------------------------
235A note on beta dependence
236--------------------------------------------------------------------------------
237
238The angular exponent in N-subjettiness is called beta. The original
239N-subjettiness paper advocated beta = 1, but it is now understood that different
240beta values can be useful in different contexts. The two main choices are:
241
242beta = 1: aka broadening/girth/width measure
243 the axes behave like the "median" in that they point to the hardest cluster
244 wta_kt_axes are approximately the same as minimizing beta = 1 measure
245
246beta = 2: aka thrust/mass measure
247 the axes behave like the "mean" in that they point along the jet momentum
248 kt_axes are approximately the same as minimizing beta = 2 measure
249
250N.B. The minimization routines are only valid for 1 < beta < 3.
251
252For quark/gluon discrimination with N = 1, beta~0.2 with wta_kt_axes appears
253to be a good choice.
254
255--------------------------------------------------------------------------------
256XConePlugin [XConePlugin.hh]
257--------------------------------------------------------------------------------
258
259The XCone FastJet plugin is an exclusive cone jet finder which yields a
260fixed N number of jets which approximately conical boundaries. The algorithm
261finds N axes, and jets are simply the sum of particles closest to a given axis
262(or unclustered if they are closest to the beam). Unlike the NjettinessPlugin
263below, the user is restricted to using the XConeMeasure.
264
265 XConePlugin plugin(N,R,beta=2);
266 JetDefinition def(&plugin);
267 ClusterSequence cs(vector<PseudoJet>,def);
268 vector<PseudoJet> jets = cs.inclusive_jets();
269
270Note that despite being an exclusive jet algorithm, one finds the jets using the
271inclusive_jets() call.
272
273The AxesDefinition and MeasureDefinition are defaulted in this measure to
274OnePass_GenET_GenKT_Axes and XConeMeasure, respectively. The parameters chosen
275for the OnePass_GenET_GenKT_Axes are defined according to the chosen value of
276beta as delta = 1/(beta - 1) and p = 1/beta. These have been shown to give the
277optimal choice of seed axes. The R value for finding the axes is chosen to be
278the same as the R for the jet algorithm, although in principle, these two radii
279could be different.
280
281N.B.: The order of the R, beta arguments is *reversed* from the XConeMeasure
282itself, since this ordering is the more natural one to use for Plugins. We
283apologize in advance for any confusion this might cause.
284
285--------------------------------------------------------------------------------
286Advanced Usage: NjettinessPlugin [NjettinessPlugin.hh]
287--------------------------------------------------------------------------------
288
289Same as the XConePlugin, but the axes finding methods and measures are the same
290as for Nsubjettiness, allowing more flexibility.
291
292 NjettinessPlugin plugin(N, AxesDefinition, MeasureDefinition);
293 JetDefinition def(&plugin);
294 ClusterSequence cs(vector<PseudoJet>,def);
295 vector<PseudoJet> jets = cs.inclusive_jets();
296
297--------------------------------------------------------------------------------
298Very Advanced Usage: Njettiness [Njettiness.hh]
299--------------------------------------------------------------------------------
300
301Most users will want to use the Nsubjettiness or NjettinessPlugin classes to
302access N-(sub)jettiness information. For direct access to the Njettiness class,
303one can use Njettiness.hh directly. This class is in constant evolution, so
304users who wish to extend its functionality should contact the authors first.
305
306--------------------------------------------------------------------------------
307TauComponents [MeasureDefinition.hh]
308--------------------------------------------------------------------------------
309
310For most users, they will only need the value of N-subjettiness (i.e. tau)
311itself. For advanced users, they can access individual tau components (i.e.
312the individual numerator pieces, the denominator, etc.)
313
314 TauComponents tauComp = nSub.component_result(jet);
315 vector<double> numer = tauComp.jet_pieces_numerator(); //tau for each subjet
316 double denom = tauComp.denominator(); //normalization factor
317
318--------------------------------------------------------------------------------
319Extra Recombiners [ExtraRecombiners.hh]
320--------------------------------------------------------------------------------
321
322New in v2.0 are winner-take-all axes. (These have now been included in
323FastJet 3.1, but we have left the code here to allow the plugin to work under
324FJ 3.0). These axes are found with the help of the WinnerTakeAllRecombiner.
325This class defines a new recombination scheme for clustering particles. This
326scheme recombines two PseudoJets into a PseudoJet with pT of the sum of the two
327input PseudoJet pTs and direction of the harder PseudoJet. This is a
328"recoil-free" recombination scheme that guarantees that the axes is aligned with
329one of the input particles. It is IRC safe. Axes found with the standard
330E-scheme recombiner at similar to the beta = 2 minimization, while
331winner-take-all is similar to the beta = 1 measure.
332
333New in v2.2 is the GeneralEtSchemeRecombiner, as defined in arxiv:1506.XXXX.
334This functions similarly to the Et-scheme defined in Fastjet, but the reweighting
335of the sum of rap and phi is parameterized by an exponent delta. Thus, delta = 1
336is the normal Et-scheme recombination, delta = 2 is Et^2 recombination, and
337delta = infinity is the winner-take-all recombination. This recombination scheme
338is used in GenET_GenKT_Axes, and we find that optimal seed axes for minimization
339can be found by using delta = 1/(beta - 1).
340
341Note that the WinnerTakeAllRecombiner can be used outside of Nsubjettiness
342itself for jet finding. For example, the direction of anti-kT jets found
343with the WinnerTakeAllRecombiner is particularly robust against soft jet
344contamination. That said, this functionality is now included in FJ 3.1, so this
345code is likely to be deprecated in a future version.
346
347--------------------------------------------------------------------------------
348Technical Details
349--------------------------------------------------------------------------------
350
351In general, the user will never need access to these header files. Here is a
352brief description about how they are used to help the calculation of
353N-(sub)jettiness:
354
355AxesDefinition.hh:
356
357The AxesDefinition class (and derived classes) defines the axes used in the
358calculation of N-(sub)jettiness. These axes can be defined from the exclusive
359jets from a kT or CA algorithm, the hardest jets from an anti-kT algorithm,
360manually, or from minimization of N-jettiness. In the future, the user will be
361able to write their own axes finder, though currently the interface is still
362evolving. At the moment, the user should stick to the options allowed by
363AxesDefinition.
364
365MeasureDefinition.hh:
366
367The MeasureDefinition class (and derived classes) defines the measure by which
368N-(sub)jettiness is calculated. This measure is calculated between each
369particle and its corresponding axis, and then summed and normalized to
370produce N-(sub)jettiness. The default measure for this calculation is
371pT*dR^beta, where dR is the rapidity-azimuth distance between the particle
372and its axis, and beta is the angular exponent. Again, in the future the user
373will be able to write their own measures, but for the time being, only the
374predefined MeasureDefinition values should be used. Note that the one-pass
375minimization algorithms are defined within MeasureDefinition, since they are
376measure specific.
377
378--------------------------------------------------------------------------------
379Known Issues
380--------------------------------------------------------------------------------
381
382-- The MultiPass_Axes mode gives different answers on different runs, since
383 random numbers are used.
384-- For the default measures, in rare cases, one pass minimization can give a
385 larger value of Njettiness than without minimization. The reason is due
386 to the fact that axes in default measure are not defined as light-like
387-- Nsubjettiness is not thread safe, since there are mutables in Njettiness.
388-- If the AxesDefinition does not find N axes, then it adds zero vectors to the
389 list of axes to get the total up to N. This can lead to unpredictable
390 results (including divide by zero issues), and a warning is thrown to alert
391 the user.
392
393--------------------------------------------------------------------------------
394--------------------------------------------------------------------------------
Note: See TracBrowser for help on using the repository browser.