1 | --------------------------------------------------------------------------------
|
---|
2 | Nsubjettiness Package
|
---|
3 | --------------------------------------------------------------------------------
|
---|
4 |
|
---|
5 | The 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 |
|
---|
15 | New 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 |
|
---|
27 | New 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 | --------------------------------------------------------------------------------
|
---|
39 | Core Classes
|
---|
40 | --------------------------------------------------------------------------------
|
---|
41 |
|
---|
42 | There are various ways to access N-(sub)jettiness variables, described
|
---|
43 | in more detail below:
|
---|
44 |
|
---|
45 | Nsubjettiness [Nsubjettiness.hh]:
|
---|
46 | A FunctionOfPseudoJet<double> interface to measure the
|
---|
47 | N-subjettiness jet shape
|
---|
48 | (Recommended for most users)
|
---|
49 |
|
---|
50 | NsubjettinessRatio [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 |
|
---|
55 | XConePlugin [XConePlugin.hh]:
|
---|
56 | A FastJet plugin for using the XCone jet algorithm.
|
---|
57 | (Recommended for most users)
|
---|
58 |
|
---|
59 | NjettinessPlugin [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 |
|
---|
64 | Njettiness [Njettiness.hh]:
|
---|
65 | Access to the core Njettiness code.
|
---|
66 | (Not recommended for users, since the interface might change)
|
---|
67 |
|
---|
68 | The code assumes that you have FastJet 3, but does not (yet) require FastJet 3.1
|
---|
69 |
|
---|
70 | --------------------------------------------------------------------------------
|
---|
71 | Basic Usage: Nsubjettiness and NsubjettinessRatio [Nsubjettiness.hh]
|
---|
72 | --------------------------------------------------------------------------------
|
---|
73 |
|
---|
74 | Most users will only need to use the Nsubjettiness class. The basic
|
---|
75 | functionality 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 |
|
---|
86 | Also 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 |
|
---|
91 | For example, if you just want the tau_2/tau_1 value of a jet, using recommended
|
---|
92 | parameter 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 | --------------------------------------------------------------------------------
|
---|
102 | AxesDefinition [NjettinessDefinition.hh]
|
---|
103 | --------------------------------------------------------------------------------
|
---|
104 |
|
---|
105 | N-(sub)jettiness requires choosing axes as well as a measure (see below). There
|
---|
106 | are a number of axes choices available to the user, though modes with a (*) are
|
---|
107 | recommended. Arguments in parentheses are parameters that the user must set.
|
---|
108 |
|
---|
109 | Axes can be found using standard recursive clustering procedures. New in v2 is
|
---|
110 | the 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 |
|
---|
117 | New 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)
|
---|
121 | Here, delta > 0 labels the generalized ET recombination scheme (delta = 1 for
|
---|
122 | standard ET scheme, delta = 2 for ET^2 scheme, delta = infinity for WTA scheme)
|
---|
123 | p >= 0 labels the generalized KT clustering metric (p = 0 for ca, p = 1 for kt),
|
---|
124 | R0 is the radius parameter, and the clustering is run in exclusive mode. The
|
---|
125 | GenKT_Axes mode uses standard E-scheme recombination. By default the value of
|
---|
126 | R0 is set to "infinity", namely fastjet::JetDefinition::max_allowable_R.
|
---|
127 |
|
---|
128 | Also new in v2.2 is option of identifying nExtra axes through exclusive
|
---|
129 | clustering and then looking at all (N + nExtra) choose N axes and finding the
|
---|
130 | one 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)
|
---|
134 | These modes are not recommended for reasons of speed.
|
---|
135 |
|
---|
136 | Starting from any set of seed axes, one can run a minimization routine to find
|
---|
137 | a (local) minimum of N-(sub)jettiness. Note that the one-pass minimization
|
---|
138 | routine 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 |
|
---|
148 | For one-pass minimization, OnePass_CA_Axes and OnePass_WTA_CA_Axes are not
|
---|
149 | recommended as they provide a poor choice of seed axes.
|
---|
150 |
|
---|
151 | In general, it is difficult to find the global minimum, but this mode attempts
|
---|
152 | to do so:
|
---|
153 | MultiPass_Axes(NPass) // axes that (attempt to) minimize N-subjettiness
|
---|
154 | // (NPass = 100 is typical)
|
---|
155 | This does multi-pass minimization from KT_Axes starting points.
|
---|
156 |
|
---|
157 | Finally, 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 |
|
---|
162 | If one wants to change the number of passes used by any of the axes finders, one
|
---|
163 | can call the function
|
---|
164 | setNPass(NPass,nAttempts,accuracy,noise_range)
|
---|
165 | where NPass = 0 only uses the seed axes, NPass = 1 is one-pass minimization, and
|
---|
166 | NPass = 100 is the default multi-pass. nAttempts is the number of iterations to
|
---|
167 | use in each pass, accuracy is how close to the minimum one tries to get, and
|
---|
168 | noise_range is how much in rapidity/azimuth the random axes are jiggled.
|
---|
169 |
|
---|
170 | For most cases, running with OnePass_KT_Axes or OnePass_WTA_KT_Axes gives
|
---|
171 | reasonable results (and the results are IRC safe). Because it uses random
|
---|
172 | number seeds, MultiPass_Axes is not IRC safe (and the code is rather slow).
|
---|
173 | Note that for the minimization routines, beta = 1.1 is faster than beta = 1,
|
---|
174 | with comparable performance.
|
---|
175 |
|
---|
176 | --------------------------------------------------------------------------------
|
---|
177 | MeasureDefinition [NjettinessDefinition.hh]
|
---|
178 | --------------------------------------------------------------------------------
|
---|
179 |
|
---|
180 | The value of N-(sub)jettiness depends crucially on the choice of measure. Each
|
---|
181 | measure has a different number of parameters, so one has to be careful when
|
---|
182 | switching between measures The one indicated by (*) is the one recommended for
|
---|
183 | use by users new to Nsubjettiness.
|
---|
184 |
|
---|
185 | The 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 |
|
---|
191 | There 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 |
|
---|
197 | For all of the above measures, there is an optional argument to change from the
|
---|
198 | ordinary pt_R distance measure recommended for pp collisions to an
|
---|
199 | E_theta distance measure recommended for ee collisions. There are also
|
---|
200 | lorentz_dot and perp_lorentz_dot distance measures recommended only for
|
---|
201 | advanced users.
|
---|
202 |
|
---|
203 | New for v2.2 is a set of measures defined in arXiv:1508.01516. First, there is
|
---|
204 | the "conical measure":
|
---|
205 |
|
---|
206 | ConicalMeasure(beta,R0) // same jets as UnnormalizedCutoffMeasure
|
---|
207 | // but differs in normalization and specifics
|
---|
208 | // of one-pass minimization
|
---|
209 |
|
---|
210 | Next, there is the geometric measure (as well as a modified version to yield
|
---|
211 | more 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
|
---|
217 | definition. These have been commented out in the code as
|
---|
218 | "DeprecatedGeometricMeasure" and "DeprecatedGeometricCutoffMeasure", but they
|
---|
219 | should not be used.)
|
---|
220 |
|
---|
221 | Next, there is a "conical geometric" measure:
|
---|
222 |
|
---|
223 | ConicalGeometricMeasure(beta, gamma, Rcutoff)
|
---|
224 |
|
---|
225 | This is a hybrid between the conical and geometric measures and is the basis for
|
---|
226 | the XCone jet algorithm. Finally, setting to the gamma = 1 default gives the
|
---|
227 | XCone default measure, which is used in the XConePlugin jet finder
|
---|
228 |
|
---|
229 | (*) XConeMeasure(beta,Rcutoff)
|
---|
230 |
|
---|
231 | where beta = 2 is the recommended default value and beta = 1 is the recoil-free
|
---|
232 | default.
|
---|
233 |
|
---|
234 | --------------------------------------------------------------------------------
|
---|
235 | A note on beta dependence
|
---|
236 | --------------------------------------------------------------------------------
|
---|
237 |
|
---|
238 | The angular exponent in N-subjettiness is called beta. The original
|
---|
239 | N-subjettiness paper advocated beta = 1, but it is now understood that different
|
---|
240 | beta values can be useful in different contexts. The two main choices are:
|
---|
241 |
|
---|
242 | beta = 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 |
|
---|
246 | beta = 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 |
|
---|
250 | N.B. The minimization routines are only valid for 1 < beta < 3.
|
---|
251 |
|
---|
252 | For quark/gluon discrimination with N = 1, beta~0.2 with wta_kt_axes appears
|
---|
253 | to be a good choice.
|
---|
254 |
|
---|
255 | --------------------------------------------------------------------------------
|
---|
256 | XConePlugin [XConePlugin.hh]
|
---|
257 | --------------------------------------------------------------------------------
|
---|
258 |
|
---|
259 | The XCone FastJet plugin is an exclusive cone jet finder which yields a
|
---|
260 | fixed N number of jets which approximately conical boundaries. The algorithm
|
---|
261 | finds 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
|
---|
263 | below, 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 |
|
---|
270 | Note that despite being an exclusive jet algorithm, one finds the jets using the
|
---|
271 | inclusive_jets() call.
|
---|
272 |
|
---|
273 | The AxesDefinition and MeasureDefinition are defaulted in this measure to
|
---|
274 | OnePass_GenET_GenKT_Axes and XConeMeasure, respectively. The parameters chosen
|
---|
275 | for the OnePass_GenET_GenKT_Axes are defined according to the chosen value of
|
---|
276 | beta as delta = 1/(beta - 1) and p = 1/beta. These have been shown to give the
|
---|
277 | optimal choice of seed axes. The R value for finding the axes is chosen to be
|
---|
278 | the same as the R for the jet algorithm, although in principle, these two radii
|
---|
279 | could be different.
|
---|
280 |
|
---|
281 | N.B.: The order of the R, beta arguments is *reversed* from the XConeMeasure
|
---|
282 | itself, since this ordering is the more natural one to use for Plugins. We
|
---|
283 | apologize in advance for any confusion this might cause.
|
---|
284 |
|
---|
285 | --------------------------------------------------------------------------------
|
---|
286 | Advanced Usage: NjettinessPlugin [NjettinessPlugin.hh]
|
---|
287 | --------------------------------------------------------------------------------
|
---|
288 |
|
---|
289 | Same as the XConePlugin, but the axes finding methods and measures are the same
|
---|
290 | as 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 | --------------------------------------------------------------------------------
|
---|
298 | Very Advanced Usage: Njettiness [Njettiness.hh]
|
---|
299 | --------------------------------------------------------------------------------
|
---|
300 |
|
---|
301 | Most users will want to use the Nsubjettiness or NjettinessPlugin classes to
|
---|
302 | access N-(sub)jettiness information. For direct access to the Njettiness class,
|
---|
303 | one can use Njettiness.hh directly. This class is in constant evolution, so
|
---|
304 | users who wish to extend its functionality should contact the authors first.
|
---|
305 |
|
---|
306 | --------------------------------------------------------------------------------
|
---|
307 | TauComponents [MeasureDefinition.hh]
|
---|
308 | --------------------------------------------------------------------------------
|
---|
309 |
|
---|
310 | For most users, they will only need the value of N-subjettiness (i.e. tau)
|
---|
311 | itself. For advanced users, they can access individual tau components (i.e.
|
---|
312 | the 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 | --------------------------------------------------------------------------------
|
---|
319 | Extra Recombiners [ExtraRecombiners.hh]
|
---|
320 | --------------------------------------------------------------------------------
|
---|
321 |
|
---|
322 | New in v2.0 are winner-take-all axes. (These have now been included in
|
---|
323 | FastJet 3.1, but we have left the code here to allow the plugin to work under
|
---|
324 | FJ 3.0). These axes are found with the help of the WinnerTakeAllRecombiner.
|
---|
325 | This class defines a new recombination scheme for clustering particles. This
|
---|
326 | scheme recombines two PseudoJets into a PseudoJet with pT of the sum of the two
|
---|
327 | input PseudoJet pTs and direction of the harder PseudoJet. This is a
|
---|
328 | "recoil-free" recombination scheme that guarantees that the axes is aligned with
|
---|
329 | one of the input particles. It is IRC safe. Axes found with the standard
|
---|
330 | E-scheme recombiner at similar to the beta = 2 minimization, while
|
---|
331 | winner-take-all is similar to the beta = 1 measure.
|
---|
332 |
|
---|
333 | New in v2.2 is the GeneralEtSchemeRecombiner, as defined in arxiv:1506.XXXX.
|
---|
334 | This functions similarly to the Et-scheme defined in Fastjet, but the reweighting
|
---|
335 | of the sum of rap and phi is parameterized by an exponent delta. Thus, delta = 1
|
---|
336 | is the normal Et-scheme recombination, delta = 2 is Et^2 recombination, and
|
---|
337 | delta = infinity is the winner-take-all recombination. This recombination scheme
|
---|
338 | is used in GenET_GenKT_Axes, and we find that optimal seed axes for minimization
|
---|
339 | can be found by using delta = 1/(beta - 1).
|
---|
340 |
|
---|
341 | Note that the WinnerTakeAllRecombiner can be used outside of Nsubjettiness
|
---|
342 | itself for jet finding. For example, the direction of anti-kT jets found
|
---|
343 | with the WinnerTakeAllRecombiner is particularly robust against soft jet
|
---|
344 | contamination. That said, this functionality is now included in FJ 3.1, so this
|
---|
345 | code is likely to be deprecated in a future version.
|
---|
346 |
|
---|
347 | --------------------------------------------------------------------------------
|
---|
348 | Technical Details
|
---|
349 | --------------------------------------------------------------------------------
|
---|
350 |
|
---|
351 | In general, the user will never need access to these header files. Here is a
|
---|
352 | brief description about how they are used to help the calculation of
|
---|
353 | N-(sub)jettiness:
|
---|
354 |
|
---|
355 | AxesDefinition.hh:
|
---|
356 |
|
---|
357 | The AxesDefinition class (and derived classes) defines the axes used in the
|
---|
358 | calculation of N-(sub)jettiness. These axes can be defined from the exclusive
|
---|
359 | jets from a kT or CA algorithm, the hardest jets from an anti-kT algorithm,
|
---|
360 | manually, or from minimization of N-jettiness. In the future, the user will be
|
---|
361 | able to write their own axes finder, though currently the interface is still
|
---|
362 | evolving. At the moment, the user should stick to the options allowed by
|
---|
363 | AxesDefinition.
|
---|
364 |
|
---|
365 | MeasureDefinition.hh:
|
---|
366 |
|
---|
367 | The MeasureDefinition class (and derived classes) defines the measure by which
|
---|
368 | N-(sub)jettiness is calculated. This measure is calculated between each
|
---|
369 | particle and its corresponding axis, and then summed and normalized to
|
---|
370 | produce N-(sub)jettiness. The default measure for this calculation is
|
---|
371 | pT*dR^beta, where dR is the rapidity-azimuth distance between the particle
|
---|
372 | and its axis, and beta is the angular exponent. Again, in the future the user
|
---|
373 | will be able to write their own measures, but for the time being, only the
|
---|
374 | predefined MeasureDefinition values should be used. Note that the one-pass
|
---|
375 | minimization algorithms are defined within MeasureDefinition, since they are
|
---|
376 | measure specific.
|
---|
377 |
|
---|
378 | --------------------------------------------------------------------------------
|
---|
379 | Known 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 | --------------------------------------------------------------------------------
|
---|