1 | #ifndef __FASTJET_JETDEFINITION_HH__
|
---|
2 | #define __FASTJET_JETDEFINITION_HH__
|
---|
3 |
|
---|
4 | //FJSTARTHEADER
|
---|
5 | // $Id: JetDefinition.hh 4354 2018-04-22 07:12:37Z salam $
|
---|
6 | //
|
---|
7 | // Copyright (c) 2005-2018, Matteo Cacciari, Gavin P. Salam and Gregory Soyez
|
---|
8 | //
|
---|
9 | //----------------------------------------------------------------------
|
---|
10 | // This file is part of FastJet.
|
---|
11 | //
|
---|
12 | // FastJet is free software; you can redistribute it and/or modify
|
---|
13 | // it under the terms of the GNU General Public License as published by
|
---|
14 | // the Free Software Foundation; either version 2 of the License, or
|
---|
15 | // (at your option) any later version.
|
---|
16 | //
|
---|
17 | // The algorithms that underlie FastJet have required considerable
|
---|
18 | // development. They are described in the original FastJet paper,
|
---|
19 | // hep-ph/0512210 and in the manual, arXiv:1111.6097. If you use
|
---|
20 | // FastJet as part of work towards a scientific publication, please
|
---|
21 | // quote the version you use and include a citation to the manual and
|
---|
22 | // optionally also to hep-ph/0512210.
|
---|
23 | //
|
---|
24 | // FastJet is distributed in the hope that it will be useful,
|
---|
25 | // but WITHOUT ANY WARRANTY; without even the implied warranty of
|
---|
26 | // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
---|
27 | // GNU General Public License for more details.
|
---|
28 | //
|
---|
29 | // You should have received a copy of the GNU General Public License
|
---|
30 | // along with FastJet. If not, see <http://www.gnu.org/licenses/>.
|
---|
31 | //----------------------------------------------------------------------
|
---|
32 | //FJENDHEADER
|
---|
33 |
|
---|
34 | #include<cassert>
|
---|
35 | #include "fastjet/internal/numconsts.hh"
|
---|
36 | #include "fastjet/PseudoJet.hh"
|
---|
37 | #include "fastjet/internal/deprecated.hh"
|
---|
38 | #include<string>
|
---|
39 | #include<memory>
|
---|
40 |
|
---|
41 | FASTJET_BEGIN_NAMESPACE // defined in fastjet/internal/base.hh
|
---|
42 |
|
---|
43 | /// return a string containing information about the release
|
---|
44 | // NB: (implemented in ClusterSequence.cc but defined here because
|
---|
45 | // this is a visible location)
|
---|
46 | std::string fastjet_version_string();
|
---|
47 |
|
---|
48 | //======================================================================
|
---|
49 | /// the various options for the algorithmic strategy to adopt in
|
---|
50 | /// clustering events with kt and cambridge style algorithms.
|
---|
51 | enum Strategy {
|
---|
52 | /// Like N2MHTLazy9 in a number of respects, but does not calculate
|
---|
53 | /// ghost-ghost distances and so does not carry out ghost-ghost
|
---|
54 | /// recombination.
|
---|
55 | ///
|
---|
56 | /// If you want active ghosted areas, then this is only suitable for
|
---|
57 | /// use with the anti-kt algorithm (or genkt with negative p), and
|
---|
58 | /// does not produce any pure ghost jets. If used with active areas
|
---|
59 | /// with Kt or Cam algorithms it will actually produce a passive
|
---|
60 | /// area.
|
---|
61 | ///
|
---|
62 | /// Particles are deemed to be ghosts if their pt is below a
|
---|
63 | /// threshold (currently 1e-50, hard coded as ghost_limit in
|
---|
64 | /// LazyTiling9SeparateGhosts).
|
---|
65 | ///
|
---|
66 | /// Currently for events with a couple of thousand normal particles
|
---|
67 | /// and O(10k) ghosts, this can be quicker than N2MHTLazy9, which
|
---|
68 | /// would otherwise be the best strategy.
|
---|
69 | ///
|
---|
70 | /// New in FJ3.1
|
---|
71 | N2MHTLazy9AntiKtSeparateGhosts = -10,
|
---|
72 | /// only looks into a neighbouring tile for a particle's nearest
|
---|
73 | /// neighbour (NN) if that particle's in-tile NN is further than the
|
---|
74 | /// distance to the edge of the neighbouring tile. Uses tiles of
|
---|
75 | /// size R and a 3x3 tile grid around the particle.
|
---|
76 | /// New in FJ3.1
|
---|
77 | N2MHTLazy9 = -7,
|
---|
78 | /// Similar to N2MHTLazy9, but uses tiles of size R/2 and a 5x5 tile
|
---|
79 | /// grid around the particle.
|
---|
80 | /// New in FJ3.1
|
---|
81 | N2MHTLazy25 = -6,
|
---|
82 | /// Like to N2MHTLazy9 but uses slightly different optimizations,
|
---|
83 | /// e.g. for calculations of distance to nearest tile; as of
|
---|
84 | /// 2014-07-18 it is slightly slower and not recommended for
|
---|
85 | /// production use. To considered deprecated.
|
---|
86 | /// New in FJ3.1
|
---|
87 | N2MHTLazy9Alt = -5,
|
---|
88 | /// faster that N2Tiled above about 500 particles; differs from it
|
---|
89 | /// by retainig the di(closest j) distances in a MinHeap (sort of
|
---|
90 | /// priority queue) rather than a simple vector.
|
---|
91 | N2MinHeapTiled = -4,
|
---|
92 | /// fastest from about 50..500
|
---|
93 | N2Tiled = -3,
|
---|
94 | /// legacy
|
---|
95 | N2PoorTiled = -2,
|
---|
96 | /// fastest below 50
|
---|
97 | N2Plain = -1,
|
---|
98 | /// worse even than the usual N^3 algorithms
|
---|
99 | N3Dumb = 0,
|
---|
100 | /// automatic selection of the best (based on N), including
|
---|
101 | /// the LazyTiled strategies that are new to FJ3.1
|
---|
102 | Best = 1,
|
---|
103 | /// best of the NlnN variants -- best overall for N>10^4.
|
---|
104 | /// (Does not work for R>=2pi)
|
---|
105 | NlnN = 2,
|
---|
106 | /// legacy N ln N using 3pi coverage of cylinder.
|
---|
107 | /// (Does not work for R>=2pi)
|
---|
108 | NlnN3pi = 3,
|
---|
109 | /// legacy N ln N using 4pi coverage of cylinder
|
---|
110 | NlnN4pi = 4,
|
---|
111 | /// Chan's closest pair method (in a variant with 4pi coverage),
|
---|
112 | /// for use exclusively with the Cambridge algorithm.
|
---|
113 | /// (Does not work for R>=2pi)
|
---|
114 | NlnNCam4pi = 14,
|
---|
115 | /// Chan's closest pair method (in a variant with 2pi+2R coverage),
|
---|
116 | /// for use exclusively with the Cambridge algorithm.
|
---|
117 | /// (Does not work for R>=2pi)
|
---|
118 | NlnNCam2pi2R = 13,
|
---|
119 | /// Chan's closest pair method (in a variant with 2pi+minimal extra
|
---|
120 | /// variant), for use exclusively with the Cambridge algorithm.
|
---|
121 | /// (Does not work for R>=2pi)
|
---|
122 | NlnNCam = 12, // 2piMultD
|
---|
123 | /// the automatic strategy choice that was being made in FJ 3.0
|
---|
124 | /// (restricted to strategies that were present in FJ 3.0)
|
---|
125 | BestFJ30 = 21,
|
---|
126 | /// the plugin has been used...
|
---|
127 | plugin_strategy = 999
|
---|
128 | };
|
---|
129 |
|
---|
130 |
|
---|
131 | //======================================================================
|
---|
132 | /// \enum JetAlgorithm
|
---|
133 | /// the various families of jet-clustering algorithm
|
---|
134 | //
|
---|
135 | // [Remember to update the "is_spherical()" routine if any further
|
---|
136 | // spherical algorithms are added to the list below]
|
---|
137 | enum JetAlgorithm {
|
---|
138 | /// the longitudinally invariant kt algorithm
|
---|
139 | kt_algorithm=0,
|
---|
140 | /// the longitudinally invariant variant of the cambridge algorithm
|
---|
141 | /// (aka Aachen algoithm).
|
---|
142 | cambridge_algorithm=1,
|
---|
143 | /// like the k_t but with distance measures
|
---|
144 | /// dij = min(1/kti^2,1/ktj^2) Delta R_{ij}^2 / R^2
|
---|
145 | /// diB = 1/kti^2
|
---|
146 | antikt_algorithm=2,
|
---|
147 | /// like the k_t but with distance measures
|
---|
148 | /// dij = min(kti^{2p},ktj^{2p}) Delta R_{ij}^2 / R^2
|
---|
149 | /// diB = 1/kti^{2p}
|
---|
150 | /// where p = extra_param()
|
---|
151 | genkt_algorithm=3,
|
---|
152 | /// a version of cambridge with a special distance measure for
|
---|
153 | /// particles whose pt is < extra_param(); this is not usually
|
---|
154 | /// intended for end users, but is instead automatically selected
|
---|
155 | /// when requesting a passive Cambridge area.
|
---|
156 | cambridge_for_passive_algorithm=11,
|
---|
157 | /// a version of genkt with a special distance measure for particles
|
---|
158 | /// whose pt is < extra_param() [relevant for passive areas when p<=0]
|
---|
159 | /// ***** NB: THERE IS CURRENTLY NO IMPLEMENTATION FOR THIS ALG *******
|
---|
160 | genkt_for_passive_algorithm=13,
|
---|
161 | //.................................................................
|
---|
162 | /// the e+e- kt algorithm
|
---|
163 | ee_kt_algorithm=50,
|
---|
164 | /// the e+e- genkt algorithm (R > 2 and p=1 gives ee_kt)
|
---|
165 | ee_genkt_algorithm=53,
|
---|
166 | //.................................................................
|
---|
167 | /// any plugin algorithm supplied by the user
|
---|
168 | plugin_algorithm = 99,
|
---|
169 | //.................................................................
|
---|
170 | /// the value for the jet algorithm in a JetDefinition for which
|
---|
171 | /// no algorithm has yet been defined
|
---|
172 | undefined_jet_algorithm = 999
|
---|
173 | };
|
---|
174 |
|
---|
175 | /// make standard Les Houches nomenclature JetAlgorithm (algorithm is general
|
---|
176 | /// recipe without the parameters) backward-compatible with old JetFinder
|
---|
177 | typedef JetAlgorithm JetFinder;
|
---|
178 |
|
---|
179 | /// provide other possible names for the Cambridge/Aachen algorithm
|
---|
180 | const JetAlgorithm aachen_algorithm = cambridge_algorithm;
|
---|
181 | const JetAlgorithm cambridge_aachen_algorithm = cambridge_algorithm;
|
---|
182 |
|
---|
183 | //======================================================================
|
---|
184 | /// The various recombination schemes
|
---|
185 | ///
|
---|
186 | /// Note that the schemes that recombine with non-linear weighting of
|
---|
187 | /// the directions (e.g. pt2, winner-takes-all) are collinear safe
|
---|
188 | /// only for algorithms with a suitable ordering of the
|
---|
189 | /// recombinations: orderings in which, for particles of comparable
|
---|
190 | /// energies, small-angle clusterings take place before large-angle
|
---|
191 | /// clusterings. This property is satisfied by all gen-kt algorithms.
|
---|
192 | ///
|
---|
193 | enum RecombinationScheme {
|
---|
194 | /// summing the 4-momenta
|
---|
195 | E_scheme=0,
|
---|
196 | /// pt weighted recombination of y,phi (and summing of pt's)
|
---|
197 | /// with preprocessing to make things massless by rescaling E=|\vec p|
|
---|
198 | pt_scheme=1,
|
---|
199 | /// pt^2 weighted recombination of y,phi (and summing of pt's)
|
---|
200 | /// with preprocessing to make things massless by rescaling E=|\vec p|
|
---|
201 | pt2_scheme=2,
|
---|
202 | /// pt weighted recombination of y,phi (and summing of pt's)
|
---|
203 | /// with preprocessing to make things massless by rescaling |\vec p|->=E
|
---|
204 | Et_scheme=3,
|
---|
205 | /// pt^2 weighted recombination of y,phi (and summing of pt's)
|
---|
206 | /// with preprocessing to make things massless by rescaling |\vec p|->=E
|
---|
207 | Et2_scheme=4,
|
---|
208 | /// pt weighted recombination of y,phi (and summing of pt's), with
|
---|
209 | /// no preprocessing
|
---|
210 | BIpt_scheme=5,
|
---|
211 | /// pt^2 weighted recombination of y,phi (and summing of pt's)
|
---|
212 | /// no preprocessing
|
---|
213 | BIpt2_scheme=6,
|
---|
214 | /// pt-based Winner-Takes-All (WTA) recombination: the
|
---|
215 | /// result of the recombination has the rapidity, azimuth and mass
|
---|
216 | /// of the PseudoJet with the larger pt, and a pt equal to the
|
---|
217 | /// sum of the two pt's
|
---|
218 | WTA_pt_scheme=7,
|
---|
219 | /// mod-p-based Winner-Takes-All (WTA) recombination: the result of
|
---|
220 | /// the recombination gets the 3-vector direction and mass of the
|
---|
221 | /// PseudoJet with the larger |3-momentum| (modp), and a
|
---|
222 | /// |3-momentum| equal to the scalar sum of the two |3-momenta|.
|
---|
223 | WTA_modp_scheme=8,
|
---|
224 | // Energy-ordering can lead to dangerous situations with particles at
|
---|
225 | // rest. We instead implement the WTA_modp_scheme
|
---|
226 | //
|
---|
227 | // // energy-based Winner-Takes-All (WTA) recombination: the result of
|
---|
228 | // // the recombination gets the 3-vector direction and mass of the
|
---|
229 | // // PseudoJet with the larger energy, and an energy equal to the
|
---|
230 | // // to the sum of the two energies
|
---|
231 | // WTA_E_scheme=8,
|
---|
232 | /// for the user's external scheme
|
---|
233 | external_scheme = 99
|
---|
234 | };
|
---|
235 |
|
---|
236 |
|
---|
237 |
|
---|
238 | // forward declaration, needed in order to specify interface for the
|
---|
239 | // plugin.
|
---|
240 | class ClusterSequence;
|
---|
241 |
|
---|
242 |
|
---|
243 |
|
---|
244 |
|
---|
245 | //======================================================================
|
---|
246 | /// @ingroup basic_classes
|
---|
247 | /// \class JetDefinition
|
---|
248 | /// class that is intended to hold a full definition of the jet
|
---|
249 | /// clusterer
|
---|
250 | class JetDefinition {
|
---|
251 |
|
---|
252 | public:
|
---|
253 |
|
---|
254 | /// forward declaration of a class that allows the user to introduce
|
---|
255 | /// their own plugin
|
---|
256 | class Plugin;
|
---|
257 |
|
---|
258 | // forward declaration of a class that will provide the
|
---|
259 | // recombination scheme facilities and/or allow a user to
|
---|
260 | // extend these facilities
|
---|
261 | class Recombiner;
|
---|
262 |
|
---|
263 |
|
---|
264 | /// constructor with alternative ordering or arguments -- note that
|
---|
265 | /// we have not provided a default jet finder, to avoid ambiguous
|
---|
266 | /// JetDefinition() constructor.
|
---|
267 | JetDefinition(JetAlgorithm jet_algorithm_in,
|
---|
268 | double R_in,
|
---|
269 | RecombinationScheme recomb_scheme_in = E_scheme,
|
---|
270 | Strategy strategy_in = Best) {
|
---|
271 | *this = JetDefinition(jet_algorithm_in, R_in, recomb_scheme_in, strategy_in, 1);
|
---|
272 | }
|
---|
273 |
|
---|
274 | /// constructor for algorithms that have no free parameters
|
---|
275 | /// (e.g. ee_kt_algorithm)
|
---|
276 | JetDefinition(JetAlgorithm jet_algorithm_in,
|
---|
277 | RecombinationScheme recomb_scheme_in = E_scheme,
|
---|
278 | Strategy strategy_in = Best) {
|
---|
279 | double dummyR = 0.0;
|
---|
280 | *this = JetDefinition(jet_algorithm_in, dummyR, recomb_scheme_in, strategy_in, 0);
|
---|
281 | }
|
---|
282 |
|
---|
283 | /// constructor for algorithms that require R + one extra parameter to be set
|
---|
284 | /// (the gen-kt series for example)
|
---|
285 | JetDefinition(JetAlgorithm jet_algorithm_in,
|
---|
286 | double R_in,
|
---|
287 | double xtra_param_in,
|
---|
288 | RecombinationScheme recomb_scheme_in = E_scheme,
|
---|
289 | Strategy strategy_in = Best) {
|
---|
290 | *this = JetDefinition(jet_algorithm_in, R_in, recomb_scheme_in, strategy_in, 2);
|
---|
291 | set_extra_param(xtra_param_in);
|
---|
292 | }
|
---|
293 |
|
---|
294 |
|
---|
295 | /// constructor in a form that allows the user to provide a pointer
|
---|
296 | /// to an external recombiner class (which must remain valid for the
|
---|
297 | /// life of the JetDefinition object).
|
---|
298 | JetDefinition(JetAlgorithm jet_algorithm_in,
|
---|
299 | double R_in,
|
---|
300 | const Recombiner * recombiner_in,
|
---|
301 | Strategy strategy_in = Best) {
|
---|
302 | *this = JetDefinition(jet_algorithm_in, R_in, external_scheme, strategy_in);
|
---|
303 | _recombiner = recombiner_in;
|
---|
304 | }
|
---|
305 |
|
---|
306 |
|
---|
307 | /// constructor for case with 0 parameters (ee_kt_algorithm) and
|
---|
308 | /// and external recombiner
|
---|
309 | JetDefinition(JetAlgorithm jet_algorithm_in,
|
---|
310 | const Recombiner * recombiner_in,
|
---|
311 | Strategy strategy_in = Best) {
|
---|
312 | *this = JetDefinition(jet_algorithm_in, external_scheme, strategy_in);
|
---|
313 | _recombiner = recombiner_in;
|
---|
314 | }
|
---|
315 |
|
---|
316 | /// constructor allowing the extra parameter to be set and a pointer to
|
---|
317 | /// a recombiner
|
---|
318 | JetDefinition(JetAlgorithm jet_algorithm_in,
|
---|
319 | double R_in,
|
---|
320 | double xtra_param_in,
|
---|
321 | const Recombiner * recombiner_in,
|
---|
322 | Strategy strategy_in = Best) {
|
---|
323 | *this = JetDefinition(jet_algorithm_in, R_in, xtra_param_in, external_scheme, strategy_in);
|
---|
324 | _recombiner = recombiner_in;
|
---|
325 | }
|
---|
326 |
|
---|
327 | /// a default constructor which creates a jet definition that is in
|
---|
328 | /// a well-defined internal state, but not actually usable for jet
|
---|
329 | /// clustering.
|
---|
330 | JetDefinition() {
|
---|
331 | *this = JetDefinition(undefined_jet_algorithm, 1.0);
|
---|
332 | }
|
---|
333 |
|
---|
334 |
|
---|
335 | // /// a default constructor
|
---|
336 | // JetDefinition() {
|
---|
337 | // *this = JetDefinition(kt_algorithm, 1.0);
|
---|
338 | // }
|
---|
339 |
|
---|
340 | /// constructor based on a pointer to a user's plugin; the object
|
---|
341 | /// pointed to must remain valid for the whole duration of existence
|
---|
342 | /// of the JetDefinition and any related ClusterSequences
|
---|
343 | JetDefinition(const Plugin * plugin_in) {
|
---|
344 | _plugin = plugin_in;
|
---|
345 | _strategy = plugin_strategy;
|
---|
346 | _Rparam = _plugin->R();
|
---|
347 | _extra_param = 0.0; // a dummy value to keep static code checkers happy
|
---|
348 | _jet_algorithm = plugin_algorithm;
|
---|
349 | set_recombination_scheme(E_scheme);
|
---|
350 | }
|
---|
351 |
|
---|
352 | /// constructor to fully specify a jet-definition (together with
|
---|
353 | /// information about how algorithically to run it).
|
---|
354 | JetDefinition(JetAlgorithm jet_algorithm_in,
|
---|
355 | double R_in,
|
---|
356 | RecombinationScheme recomb_scheme_in,
|
---|
357 | Strategy strategy_in,
|
---|
358 | int nparameters_in);
|
---|
359 |
|
---|
360 | /// constructor to fully specify a jet-definition (together with
|
---|
361 | /// information about how algorithically to run it).
|
---|
362 | ///
|
---|
363 | /// the ordering of arguments here is old and deprecated (except
|
---|
364 | /// as the common constructor for internal use)
|
---|
365 | FASTJET_DEPRECATED_MSG("This argument ordering is deprecated. Use JetDefinition(alg, R, strategy, scheme[, n_parameters]) instead")
|
---|
366 | JetDefinition(JetAlgorithm jet_algorithm_in,
|
---|
367 | double R_in,
|
---|
368 | Strategy strategy_in,
|
---|
369 | RecombinationScheme recomb_scheme_in = E_scheme,
|
---|
370 | int nparameters_in = 1){
|
---|
371 | (*this) = JetDefinition(jet_algorithm_in,R_in,recomb_scheme_in,strategy_in,nparameters_in);
|
---|
372 | }
|
---|
373 |
|
---|
374 |
|
---|
375 | /// cluster the supplied particles and returns a vector of resulting
|
---|
376 | /// jets, sorted by pt (or energy in the case of spherical,
|
---|
377 | /// i.e. e+e-, algorithms). This routine currently only makes
|
---|
378 | /// sense for "inclusive" type algorithms.
|
---|
379 | template <class L>
|
---|
380 | std::vector<PseudoJet> operator()(const std::vector<L> & particles) const;
|
---|
381 |
|
---|
382 | /// R values larger than max_allowable_R are not allowed.
|
---|
383 | ///
|
---|
384 | /// We use a value of 1000, substantially smaller than
|
---|
385 | /// numeric_limits<double>::max(), to leave room for the convention
|
---|
386 | /// within PseudoJet of setting unphysical (infinite) rapidities to
|
---|
387 | /// +-(MaxRap + abs(pz())), where MaxRap is 10^5.
|
---|
388 | static const double max_allowable_R; //= 1000.0;
|
---|
389 |
|
---|
390 | /// set the recombination scheme to the one provided
|
---|
391 | void set_recombination_scheme(RecombinationScheme);
|
---|
392 |
|
---|
393 | /// set the recombiner class to the one provided
|
---|
394 | ///
|
---|
395 | /// Note that in order to associate to a jet definition a recombiner
|
---|
396 | /// from another jet definition, it is strongly recommended to use
|
---|
397 | /// the set_recombiner(const JetDefinition &) method below. The
|
---|
398 | /// latter correctly handles the situations where the jet definition
|
---|
399 | /// owns the recombiner (i.e. where delete_recombiner_when_unused
|
---|
400 | /// has been called). In such cases, using set_recombiner(const
|
---|
401 | /// Recombiner *) may lead to memory corruption.
|
---|
402 | void set_recombiner(const Recombiner * recomb) {
|
---|
403 | if (_shared_recombiner) _shared_recombiner.reset(recomb);
|
---|
404 | _recombiner = recomb;
|
---|
405 | _default_recombiner = DefaultRecombiner(external_scheme);
|
---|
406 | }
|
---|
407 |
|
---|
408 | /// set the recombiner to be the same as the one of 'other_jet_def'
|
---|
409 | ///
|
---|
410 | /// Note that this is the recommended method to associate to a jet
|
---|
411 | /// definition the recombiner from another jet definition. Compared
|
---|
412 | /// to the set_recombiner(const Recombiner *) above, it correctly
|
---|
413 | /// handles the case where the jet definition owns the recombiner
|
---|
414 | /// (i.e. where delete_recombiner_when_unused has been called)
|
---|
415 | void set_recombiner(const JetDefinition &other_jet_def);
|
---|
416 |
|
---|
417 | /// calling this tells the JetDefinition to handle the deletion of
|
---|
418 | /// the recombiner when it is no longer used. (Should not be called
|
---|
419 | /// if the recombiner was initialised from a JetDef whose recombiner
|
---|
420 | /// was already scheduled to delete itself - memory handling will
|
---|
421 | /// already be automatic across both JetDef's in that case).
|
---|
422 | void delete_recombiner_when_unused();
|
---|
423 |
|
---|
424 | /// return a pointer to the plugin
|
---|
425 | const Plugin * plugin() const {return _plugin;};
|
---|
426 |
|
---|
427 | /// calling this causes the JetDefinition to handle the deletion of the
|
---|
428 | /// plugin when it is no longer used
|
---|
429 | void delete_plugin_when_unused();
|
---|
430 |
|
---|
431 | /// return information about the definition...
|
---|
432 | JetAlgorithm jet_algorithm () const {return _jet_algorithm ;}
|
---|
433 | /// same as above for backward compatibility
|
---|
434 | JetAlgorithm jet_finder () const {return _jet_algorithm ;}
|
---|
435 | double R () const {return _Rparam ;}
|
---|
436 | // a general purpose extra parameter, whose meaning depends on
|
---|
437 | // the algorithm, and may often be unused.
|
---|
438 | double extra_param () const {return _extra_param ;}
|
---|
439 | Strategy strategy () const {return _strategy ;}
|
---|
440 | RecombinationScheme recombination_scheme() const {
|
---|
441 | return _default_recombiner.scheme();}
|
---|
442 |
|
---|
443 | /// (re)set the jet finder
|
---|
444 | void set_jet_algorithm(JetAlgorithm njf) {_jet_algorithm = njf;}
|
---|
445 | /// same as above for backward compatibility
|
---|
446 | void set_jet_finder(JetAlgorithm njf) {_jet_algorithm = njf;}
|
---|
447 | /// (re)set the general purpose extra parameter
|
---|
448 | void set_extra_param(double xtra_param) {_extra_param = xtra_param;}
|
---|
449 |
|
---|
450 | /// returns a pointer to the currently defined recombiner.
|
---|
451 | ///
|
---|
452 | /// Warning: the pointer may be to an internal recombiner (for
|
---|
453 | /// default recombination schemes), in which case if the
|
---|
454 | /// JetDefinition becomes invalid (e.g. is deleted), the pointer
|
---|
455 | /// will then point to an object that no longer exists.
|
---|
456 | ///
|
---|
457 | /// Note also that if you copy a JetDefinition with a default
|
---|
458 | /// recombination scheme, then the two copies will have distinct
|
---|
459 | /// recombiners, and return different recombiner() pointers.
|
---|
460 | const Recombiner * recombiner() const {
|
---|
461 | return _recombiner == 0 ? & _default_recombiner : _recombiner;}
|
---|
462 |
|
---|
463 | /// returns true if the current jet definitions shares the same
|
---|
464 | /// recombiner as the one passed as an argument
|
---|
465 | bool has_same_recombiner(const JetDefinition &other_jd) const;
|
---|
466 |
|
---|
467 | /// returns true if the jet definition involves an algorithm
|
---|
468 | /// intended for use on a spherical geometry (e.g. e+e- algorithms,
|
---|
469 | /// as opposed to most pp algorithms, which use a cylindrical,
|
---|
470 | /// rapidity-phi geometry).
|
---|
471 | bool is_spherical() const;
|
---|
472 |
|
---|
473 | /// return a textual description of the current jet definition
|
---|
474 | std::string description() const;
|
---|
475 |
|
---|
476 | /// returns a description not including the recombiner information
|
---|
477 | std::string description_no_recombiner() const;
|
---|
478 |
|
---|
479 | /// a short textual description of the algorithm jet_alg
|
---|
480 | static std::string algorithm_description(const JetAlgorithm jet_alg);
|
---|
481 |
|
---|
482 | /// the number of parameters associated to a given jet algorithm
|
---|
483 | static unsigned int n_parameters_for_algorithm(const JetAlgorithm jet_alg);
|
---|
484 |
|
---|
485 | public:
|
---|
486 | //======================================================================
|
---|
487 | /// @ingroup advanced_usage
|
---|
488 | /// \class Recombiner
|
---|
489 | /// An abstract base class that will provide the recombination scheme
|
---|
490 | /// facilities and/or allow a user to extend these facilities
|
---|
491 | class Recombiner {
|
---|
492 | public:
|
---|
493 | /// return a textual description of the recombination scheme
|
---|
494 | /// implemented here
|
---|
495 | virtual std::string description() const = 0;
|
---|
496 |
|
---|
497 | /// recombine pa and pb and put result into pab
|
---|
498 | virtual void recombine(const PseudoJet & pa, const PseudoJet & pb,
|
---|
499 | PseudoJet & pab) const = 0;
|
---|
500 |
|
---|
501 | /// routine called to preprocess each input jet (to make all input
|
---|
502 | /// jets compatible with the scheme requirements (e.g. massless).
|
---|
503 | virtual void preprocess(PseudoJet & ) const {};
|
---|
504 |
|
---|
505 | /// a destructor to be replaced if necessary in derived classes...
|
---|
506 | virtual ~Recombiner() {};
|
---|
507 |
|
---|
508 | /// pa += pb in the given recombination scheme. Not virtual -- the
|
---|
509 | /// user should have no reason to want to redefine this!
|
---|
510 | inline void plus_equal(PseudoJet & pa, const PseudoJet & pb) const {
|
---|
511 | // put result in a temporary location in case the recombiner
|
---|
512 | // does something funny (ours doesn't, but who knows about the
|
---|
513 | // user's)
|
---|
514 | PseudoJet pres;
|
---|
515 | recombine(pa,pb,pres);
|
---|
516 | pa = pres;
|
---|
517 | }
|
---|
518 |
|
---|
519 | };
|
---|
520 |
|
---|
521 |
|
---|
522 | //======================================================================
|
---|
523 | /// @ingroup advanced_usage
|
---|
524 | /// \class DefaultRecombiner
|
---|
525 | /// A class that will provide the recombination scheme facilities and/or
|
---|
526 | /// allow a user to extend these facilities
|
---|
527 | ///
|
---|
528 | /// This class is derived from the (abstract) class Recombiner. It
|
---|
529 | /// simply "sums" PseudoJets using a specified recombination scheme
|
---|
530 | /// (E-scheme by default)
|
---|
531 | class DefaultRecombiner : public Recombiner {
|
---|
532 | public:
|
---|
533 | DefaultRecombiner(RecombinationScheme recomb_scheme = E_scheme) :
|
---|
534 | _recomb_scheme(recomb_scheme) {}
|
---|
535 |
|
---|
536 | virtual std::string description() const FASTJET_OVERRIDE;
|
---|
537 |
|
---|
538 | /// recombine pa and pb and put result into pab
|
---|
539 | virtual void recombine(const PseudoJet & pa, const PseudoJet & pb,
|
---|
540 | PseudoJet & pab) const FASTJET_OVERRIDE;
|
---|
541 |
|
---|
542 | virtual void preprocess(PseudoJet & p) const FASTJET_OVERRIDE;
|
---|
543 |
|
---|
544 | /// return the index of the recombination scheme
|
---|
545 | RecombinationScheme scheme() const {return _recomb_scheme;}
|
---|
546 |
|
---|
547 | private:
|
---|
548 | RecombinationScheme _recomb_scheme;
|
---|
549 | };
|
---|
550 |
|
---|
551 |
|
---|
552 | //======================================================================
|
---|
553 | /// @ingroup advanced_usage
|
---|
554 | /// \class Plugin
|
---|
555 | /// a class that allows a user to introduce their own "plugin" jet
|
---|
556 | /// finder
|
---|
557 | ///
|
---|
558 | /// Note that all the plugins provided with FastJet are derived from
|
---|
559 | /// this class
|
---|
560 | class Plugin{
|
---|
561 | public:
|
---|
562 | /// return a textual description of the jet-definition implemented
|
---|
563 | /// in this plugin
|
---|
564 | virtual std::string description() const = 0;
|
---|
565 |
|
---|
566 | /// given a ClusterSequence that has been filled up with initial
|
---|
567 | /// particles, the following function should fill up the rest of the
|
---|
568 | /// ClusterSequence, using the following member functions of
|
---|
569 | /// ClusterSequence:
|
---|
570 | /// - plugin_do_ij_recombination(...)
|
---|
571 | /// - plugin_do_iB_recombination(...)
|
---|
572 | virtual void run_clustering(ClusterSequence &) const = 0;
|
---|
573 |
|
---|
574 | virtual double R() const = 0;
|
---|
575 |
|
---|
576 | /// return true if there is specific support for the measurement
|
---|
577 | /// of passive areas, in the sense that areas determined from all
|
---|
578 | /// particles below the ghost separation scale will be a passive
|
---|
579 | /// area. [If you don't understand this, ignore it!]
|
---|
580 | virtual bool supports_ghosted_passive_areas() const {return false;}
|
---|
581 |
|
---|
582 | /// set the ghost separation scale for passive area determinations
|
---|
583 | /// in future runs (strictly speaking that makes the routine
|
---|
584 | /// a non const, so related internal info must be stored as a mutable)
|
---|
585 | virtual void set_ghost_separation_scale(double scale) const;
|
---|
586 | virtual double ghost_separation_scale() const {return 0.0;}
|
---|
587 |
|
---|
588 | /// if this returns false then a warning will be given
|
---|
589 | /// whenever the user requests "exclusive" jets from the
|
---|
590 | /// cluster sequence
|
---|
591 | virtual bool exclusive_sequence_meaningful() const {return false;}
|
---|
592 |
|
---|
593 | /// returns true if the plugin implements an algorithm intended
|
---|
594 | /// for use on a spherical geometry (e.g. e+e- algorithms, as
|
---|
595 | /// opposed to most pp algorithms, which use a cylindrical,
|
---|
596 | /// rapidity-phi geometry).
|
---|
597 | virtual bool is_spherical() const {return false;}
|
---|
598 |
|
---|
599 | /// a destructor to be replaced if necessary in derived classes...
|
---|
600 | virtual ~Plugin() {};
|
---|
601 | };
|
---|
602 |
|
---|
603 | private:
|
---|
604 |
|
---|
605 |
|
---|
606 | JetAlgorithm _jet_algorithm;
|
---|
607 | double _Rparam;
|
---|
608 | double _extra_param ; ///< parameter whose meaning varies according to context
|
---|
609 | Strategy _strategy ;
|
---|
610 |
|
---|
611 | const Plugin * _plugin;
|
---|
612 | SharedPtr<const Plugin> _plugin_shared;
|
---|
613 |
|
---|
614 | // when we use our own recombiner it's useful to point to it here
|
---|
615 | // so that we don't have to worry about deleting it etc...
|
---|
616 | DefaultRecombiner _default_recombiner;
|
---|
617 | const Recombiner * _recombiner;
|
---|
618 | SharedPtr<const Recombiner> _shared_recombiner;
|
---|
619 |
|
---|
620 | };
|
---|
621 |
|
---|
622 |
|
---|
623 | //-------------------------------------------------------------------------------
|
---|
624 | // helper functions to build a jet made of pieces
|
---|
625 | //
|
---|
626 | // These functions include an options recombiner used to compute the
|
---|
627 | // total composite jet momentum
|
---|
628 | // -------------------------------------------------------------------------------
|
---|
629 |
|
---|
630 | /// build a "CompositeJet" from the vector of its pieces
|
---|
631 | ///
|
---|
632 | /// In this case, E-scheme recombination is assumed to compute the
|
---|
633 | /// total momentum
|
---|
634 | PseudoJet join(const std::vector<PseudoJet> & pieces, const JetDefinition::Recombiner & recombiner);
|
---|
635 |
|
---|
636 | /// build a MergedJet from a single PseudoJet
|
---|
637 | PseudoJet join(const PseudoJet & j1,
|
---|
638 | const JetDefinition::Recombiner & recombiner);
|
---|
639 |
|
---|
640 | /// build a MergedJet from 2 PseudoJet
|
---|
641 | PseudoJet join(const PseudoJet & j1, const PseudoJet & j2,
|
---|
642 | const JetDefinition::Recombiner & recombiner);
|
---|
643 |
|
---|
644 | /// build a MergedJet from 3 PseudoJet
|
---|
645 | PseudoJet join(const PseudoJet & j1, const PseudoJet & j2, const PseudoJet & j3,
|
---|
646 | const JetDefinition::Recombiner & recombiner);
|
---|
647 |
|
---|
648 | /// build a MergedJet from 4 PseudoJet
|
---|
649 | PseudoJet join(const PseudoJet & j1, const PseudoJet & j2, const PseudoJet & j3, const PseudoJet & j4,
|
---|
650 | const JetDefinition::Recombiner & recombiner);
|
---|
651 |
|
---|
652 |
|
---|
653 | FASTJET_END_NAMESPACE
|
---|
654 |
|
---|
655 | // include ClusterSequence which includes the implementation of the
|
---|
656 | // templated JetDefinition::operator()(...) member
|
---|
657 | #include "fastjet/ClusterSequence.hh"
|
---|
658 |
|
---|
659 |
|
---|
660 | #endif // __FASTJET_JETDEFINITION_HH__
|
---|