Fork me on GitHub

source: git/external/fastjet/Selector.hh@ 83ee320

Timing
Last change on this file since 83ee320 was b7b836a, checked in by Pavel Demin <pavel-demin@…>, 6 years ago

update FastJet library to 3.3.1 and FastJet Contrib library to 1.036

  • Property mode set to 100644
File size: 19.1 KB
Line 
1#ifndef __FASTJET_SELECTOR_HH__
2#define __FASTJET_SELECTOR_HH__
3
4//FJSTARTHEADER
5// $Id: Selector.hh 4354 2018-04-22 07:12:37Z salam $
6//
7// Copyright (c) 2009-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 "fastjet/PseudoJet.hh"
35#ifndef __FJCORE__
36#include "fastjet/RangeDefinition.hh" // for initialisation from a RangeDefinition
37#endif // __FJCORE__
38#include <limits>
39#include <cmath>
40
41FASTJET_BEGIN_NAMESPACE // defined in fastjet/internal/base.hh
42
43//----------------------------------------------------------------------
44/// @ingroup selectors
45/// \class Selector
46/// Class that encodes information about cuts and other selection
47/// criteria that can be applied to PseudoJet(s).
48///
49class Selector;
50//----------------------------------------------------------------------
51
52/// @ingroup selectors
53/// \class SelectorWorker
54/// default selector worker is an abstract virtual base class
55///
56/// The Selector class is only an interface, it is the SelectorWorker
57/// that really does the work. To implement various selectors, one
58/// thus has to overload this class.
59class SelectorWorker {
60public:
61 //----------------------------------------------------------
62 // fundamental info
63 //----------------------------------------------------------
64 /// default dtor
65 virtual ~SelectorWorker() {}
66
67 //----------------------------------------------------------
68 // basic operations for checking what gets selected
69 //----------------------------------------------------------
70
71 /// returns true if a given object passes the selection criterion,
72 /// and is the main function that needs to be overloaded by derived
73 /// workers.
74 ///
75 /// NB: this function is used only if applies_jet_by_jet() returns
76 /// true. If it does not, then derived classes are expected to
77 /// (re)implement the terminator function()
78 virtual bool pass(const PseudoJet & jet) const = 0;
79
80 /// For each jet that does not pass the cuts, this routine sets the
81 /// pointer to 0.
82 ///
83 /// It does not assume that the PseudoJet* passed as argument are not NULL
84 virtual void terminator(std::vector<const PseudoJet *> & jets) const {
85 for (unsigned i = 0; i < jets.size(); i++) {
86 if (jets[i] && !pass(*jets[i])) jets[i] = NULL;
87 }
88 }
89
90 /// returns true if this can be applied jet by jet
91 virtual bool applies_jet_by_jet() const {return true;}
92
93 /// returns a description of the worker
94 virtual std::string description() const {return "missing description";}
95
96
97 //----------------------------------------------------------
98 // operations for dealing with reference jets
99 //----------------------------------------------------------
100
101 /// returns true if the worker is defined with respect to a reference jet
102 virtual bool takes_reference() const { return false;}
103
104 /// sets the reference jet for the selector
105 /// NB: "reference" is commented to avoid unused-variable compiler warnings
106 virtual void set_reference(const PseudoJet & /*reference*/){
107 throw Error("set_reference(...) cannot be used for a selector worker that does not take a reference");
108 }
109
110 /// return a copy of the current object.
111 ///
112 /// This function is only called for objects that take a reference and need
113 /// not be reimplemented otherwise.
114 virtual SelectorWorker* copy(){
115 throw Error("this SelectorWorker has nothing to copy");
116 }
117
118 //----------------------------------------------------------
119 // operations for area and extent
120 //----------------------------------------------------------
121
122 /// returns the rapidity range for which it may return "true"
123 virtual void get_rapidity_extent(double & rapmin, double & rapmax) const {
124 rapmax = std::numeric_limits<double>::infinity();
125 rapmin = -rapmax;
126 }
127
128 /// check if it is a geometric selector (i.e. only puts constraints
129 /// on rapidity and azimuthal angle)
130 virtual bool is_geometric() const { return false;}
131
132 /// check if it has a finite area
133 virtual bool has_finite_area() const;
134
135 /// check if it has an analytically computable area
136 virtual bool has_known_area() const { return false;}
137
138 /// if it has a computable area, return it
139 virtual double known_area() const{
140 throw Error("this selector has no computable area");
141 }
142
143};
144
145//----------------------------------------------------------------------
146// class Selector
147//
148// Class that encodes information about cuts that
149class Selector{
150public:
151 /// default constructor produces a Selector whose action is undefined
152 /// (any attempt to use it will lead to an error)
153 Selector() {}
154
155 /// constructor that causes the Selector to use the supplied worker
156 ///
157 /// Note that the Selector takes ownership of the pointer to the
158 /// worker (and so will delete automatically when appropriate).
159 Selector(SelectorWorker * worker_in) {_worker.reset(worker_in);}
160
161#ifndef __FJCORE__
162 /// ctor from a RangeDefinition
163 ///
164 /// This is provided for backward compatibility and will be removed in
165 /// a future major release of FastJet
166 ///
167 /// Watch out that the Selector will only hold a pointer to the
168 /// range so the selector will crash if one tries to use it after
169 /// the range has gone out of scope. We thus strongly advise against
170 /// the direct use of this constructor.
171 Selector(const RangeDefinition &range);
172#endif // __FJCORE__
173
174 /// dummy virtual dtor
175 virtual ~Selector(){}
176
177 /// return true if the jet passes the selection
178 bool pass(const PseudoJet & jet) const {
179 if (!validated_worker()->applies_jet_by_jet()) {
180 throw Error("Cannot apply this selector to an individual jet");
181 }
182 return _worker->pass(jet);
183 }
184
185 /// an operator way of knowing whether a given jet passes the selection or not
186 bool operator()(const PseudoJet & jet) const {
187 return pass(jet);
188 }
189
190 /// Return a count of the objects that pass the selection.
191 ///
192 /// This will often be more efficient that getting the vector of objects that
193 /// passes and then evaluating the size of the vector
194 unsigned int count(const std::vector<PseudoJet> & jets) const;
195
196 /// Return the 4-vector sum of the objects that pass the selection.
197 ///
198 /// This will often be more efficient that getting the vector of objects that
199 /// passes and then evaluating the size of the vector
200 PseudoJet sum(const std::vector<PseudoJet> & jets) const;
201
202 /// Return the scalar pt sum of the objects that pass the selection.
203 ///
204 /// This will often be more efficient that getting the vector of objects that
205 /// passes and then evaluating the size of the vector
206 double scalar_pt_sum(const std::vector<PseudoJet> & jets) const;
207
208 /// sift the input jets into two vectors -- those that pass the selector
209 /// and those that do not
210 void sift(const std::vector<PseudoJet> & jets,
211 std::vector<PseudoJet> & jets_that_pass,
212 std::vector<PseudoJet> & jets_that_fail) const;
213
214 /// returns true if this can be applied jet by jet
215 bool applies_jet_by_jet() const {
216 return validated_worker()->applies_jet_by_jet();
217 }
218
219 /// returns a vector with the jets that pass the selection
220 std::vector<PseudoJet> operator()(const std::vector<PseudoJet> & jets) const;
221
222 /// For each jet that does not pass the cuts, this routine sets the
223 /// pointer to 0.
224 ///
225 /// It is legitimate for some (or all) of the pointers that are
226 /// passed to already be NULL.
227 virtual void nullify_non_selected(std::vector<const PseudoJet *> & jets) const {
228 validated_worker()->terminator(jets);
229 }
230
231 /// returns the rapidity range for which it may return "true"
232 void get_rapidity_extent(double &rapmin, double &rapmax) const {
233 return validated_worker()->get_rapidity_extent(rapmin, rapmax);
234 }
235
236 /// returns a textual description of the selector
237 std::string description() const {
238 return validated_worker()->description();
239 }
240
241 /// returns true if it is a geometric selector (i.e. one that only puts
242 /// constraints on rapidities and azimuthal angles)
243 bool is_geometric() const{
244 return validated_worker()->is_geometric();
245 }
246
247 /// returns true if it has a meaningful and finite area (i.e. the
248 /// Selector has the property that is_geometric() returns true and
249 /// the rapidity extent is finite).
250 bool has_finite_area() const{
251 return validated_worker()->has_finite_area();
252 }
253
254#ifndef __FJCORE__
255 /// returns the rapidity-phi area associated with the Selector
256 /// (throws InvalidArea if the area does not make sense).
257 ///
258 /// If the result is not known analytically, the area will be
259 /// estimated using a pseudo Monte Carlo method (as for jet areas),
260 /// using the default ghost area from the GhostedAreaSpec class
261 /// (0.01). The Monte Carlo estimate involves a time penalty
262 /// proportional to the ratio of the rapidity extent of the Selector
263 /// divided by the ghost area.
264 double area() const;
265
266 /// returns the rapidity-phi area associated with the Selector
267 /// (throws InvalidArea if the area does not make sense).
268 ///
269 /// The behaviour is the as with the area() call, but with the
270 /// ability to additionally specify the ghost area to be used in the
271 /// case of a Monte Carlo area evaluation.
272 ///
273 double area(double ghost_area) const;
274#endif // __FJCORE__
275
276 /// returns a (reference to) the underlying worker's shared pointer
277 const SharedPtr<SelectorWorker> & worker() const {return _worker;}
278
279 /// returns a worker if there is a valid one, otherwise throws an InvalidWorker error
280 const SelectorWorker* validated_worker() const {
281 const SelectorWorker* worker_ptr = _worker.get();
282 if (worker_ptr == 0) throw InvalidWorker();
283 return worker_ptr;
284 }
285
286 /// returns true if this can be applied jet by jet
287 bool takes_reference() const {
288 return validated_worker()->takes_reference();
289 }
290
291 /// set the reference jet for this Selector
292 const Selector & set_reference(const PseudoJet &reference){
293
294 // if the worker does not take a reference jet, do nothing
295 if (! validated_worker()->takes_reference()){
296 return *this;
297 }
298
299 // since this is a non-const operation, make sure we have a
300 // correct behaviour with respect to shared workers
301 _copy_worker_if_needed();
302
303 _worker->set_reference(reference);
304 return *this;
305 }
306
307 /// class that gets thrown when a Selector is applied despite it not
308 /// having a valid underlying worker.
309 class InvalidWorker : public Error {
310 public:
311 InvalidWorker() : Error("Attempt to use Selector with no valid underlying worker") {}
312 };
313
314 /// class that gets thrown when the area is requested from a Selector for which
315 /// the area is not meaningful
316 class InvalidArea : public Error {
317 public:
318 InvalidArea() : Error("Attempt to obtain area from Selector for which this is not meaningful") {}
319 };
320
321 // some operators (applying directly on a Selector)
322 //----------------------------------------------------------------------
323 /// For 2 Selectors a and b, a &= b is eauivalent to a = a && b;
324 Selector & operator &=(const Selector & b);
325
326 /// For 2 Selectors a and b, a |= b is eauivalent to a = a || b;
327 Selector & operator |=(const Selector & b);
328
329
330protected:
331 /// Helper for copying selector workers if needed
332 ///
333 /// The following is needed if we want to modify a selectors that
334 /// shares a worker with another selector. In that case, we need to
335 /// get another copy of the worker to avoid interferences
336 ///
337 /// Note that any non-const operation has to call this to behave
338 /// correctly w.r.t shared workers!
339 void _copy_worker_if_needed(){
340 // do nothing if there's a sinlge user of the worker
341 if (_worker.unique()) return;
342
343 // call the worker's copy
344 //std::cout << "will make a copy of " << description() << std::endl;
345 _worker.reset(_worker->copy());
346 }
347
348private:
349 SharedPtr<SelectorWorker> _worker; ///< the underlying worker
350};
351
352
353//----------------------------------------------------------------------
354// a list of specific selectors
355//----------------------------------------------------------------------
356
357/// \addtogroup selectors
358/// @{
359
360
361// fundamental selectors
362//----------------------------------------------------------------------
363
364// "identity" selector that lets everything pass
365Selector SelectorIdentity();
366
367// logical operations
368//----------------------------------------------------------------------
369
370/// logical not applied on a selector
371///
372/// This will keep objects that do not pass the 's' selector
373Selector operator!(const Selector & s);
374
375/// logical or between two selectors
376///
377/// this will keep the objects that are selected by s1 or s2
378Selector operator ||(const Selector & s1, const Selector & s2);
379
380
381/// logical and between two selectors
382///
383/// this will keep the objects that are selected by both s1 and s2
384///
385/// watch out: for both s1 and s2, the selection is applied on the
386/// original list of objects. For successive applications of two
387/// selectors (convolution/multiplication) see the operator *
388Selector operator&&(const Selector & s1, const Selector & s2);
389
390/// successive application of 2 selectors
391///
392/// Apply the selector s2, then the selector s1.
393///
394/// watch out: the operator * acts like an operator product i.e. does
395/// not commute. The order of its arguments is therefore important.
396/// Whenever they commute (in particluar, when they apply jet by
397/// jet), this would have the same effect as the logical &&.
398Selector operator*(const Selector & s1, const Selector & s2);
399
400
401// selection with kinematic cuts
402//----------------------------------------------------------------------
403Selector SelectorPtMin(double ptmin); ///< select objects with pt >= ptmin
404Selector SelectorPtMax(double ptmax); ///< select objects with pt <= ptmax
405Selector SelectorPtRange(double ptmin, double ptmax); ///< select objects with ptmin <= pt <= ptmax
406
407Selector SelectorEtMin(double Etmin); ///< select objects with Et >= Etmin
408Selector SelectorEtMax(double Etmax); ///< select objects with Et <= Etmax
409Selector SelectorEtRange(double Etmin, double Etmax); ///< select objects with Etmin <= Et <= Etmax
410
411Selector SelectorEMin(double Emin); ///< select objects with E >= Emin
412Selector SelectorEMax(double Emax); ///< select objects with E <= Emax
413Selector SelectorERange(double Emin, double Emax); ///< select objects with Emin <= E <= Emax
414
415Selector SelectorMassMin(double Mmin); ///< select objects with Mass >= Mmin
416Selector SelectorMassMax(double Mmax); ///< select objects with Mass <= Mmax
417Selector SelectorMassRange(double Mmin, double Mmax); ///< select objects with Mmin <= Mass <= Mmax
418
419Selector SelectorRapMin(double rapmin); ///< select objects with rap >= rapmin
420Selector SelectorRapMax(double rapmax); ///< select objects with rap <= rapmax
421Selector SelectorRapRange(double rapmin, double rapmax); ///< select objects with rapmin <= rap <= rapmax
422
423Selector SelectorAbsRapMin(double absrapmin); ///< select objects with |rap| >= absrapmin
424Selector SelectorAbsRapMax(double absrapmax); ///< select objects with |rap| <= absrapmax
425Selector SelectorAbsRapRange(double absrapmin, double absrapmax); ///< select objects with absrapmin <= |rap| <= absrapmax
426
427Selector SelectorEtaMin(double etamin); ///< select objects with eta >= etamin
428Selector SelectorEtaMax(double etamax); ///< select objects with eta <= etamax
429Selector SelectorEtaRange(double etamin, double etamax); ///< select objects with etamin <= eta <= etamax
430
431Selector SelectorAbsEtaMin(double absetamin); ///< select objects with |eta| >= absetamin
432Selector SelectorAbsEtaMax(double absetamax); ///< select objects with |eta| <= absetamax
433Selector SelectorAbsEtaRange(double absetamin, double absetamax); ///< select objects with absetamin <= |eta| <= absetamax
434
435Selector SelectorPhiRange(double phimin, double phimax); ///< select objects with phimin <= phi <= phimax
436
437/// select objects with rapmin <= rap <= rapmax && phimin <= phi <= phimax
438///
439/// Note that this is essentially a combination of SelectorRapRange
440/// and SelectorPhiRange. We provide it as a Selector on its own in
441/// order to use the known area (which would otherwise be lost by the &&
442/// operator)
443Selector SelectorRapPhiRange(double rapmin, double rapmax, double phimin, double phimax);
444
445/// select the n hardest objects
446Selector SelectorNHardest(unsigned int n);
447
448
449// Selectors that take (require) a reference jet.
450//----------------------------------------------------------------------
451
452/// select objets within a distance 'radius' from the location of the
453/// reference jet, set by Selector::set_reference(...)
454Selector SelectorCircle(const double radius);
455
456/// select objets with distance from the reference jet is between 'radius_in'
457/// and 'radius_out'; the reference jet is set by Selector::set_reference(...)
458Selector SelectorDoughnut(const double radius_in, const double radius_out);
459
460/// select objets within a rapidity distance 'half_width' from the
461/// location of the reference jet, set by Selector::set_reference(...)
462Selector SelectorStrip(const double half_width);
463
464/// select objets within rapidity distance 'half_rap_width' from the
465/// reference jet and azimuthal-angle distance within 'half_phi_width'; the
466/// reference jet is set by Selector::set_reference(...)
467Selector SelectorRectangle(const double half_rap_width, const double half_phi_width);
468
469
470/// select objects that carry at least a fraction "fraction" of the
471/// reference jet. The reference jet must have been set with
472/// Selector::set_reference(...)
473Selector SelectorPtFractionMin(double fraction);
474
475
476// additional (mostly helper) selectors
477//----------------------------------------------------------------------
478
479/// select PseudoJet with 0 momentum
480Selector SelectorIsZero();
481
482#ifndef __FJCORE__
483/// select objects that are (or are only made of) ghosts.
484/// PseudoJets for which has_area() are considered non-pure-ghost.
485Selector SelectorIsPureGhost();
486#endif // __FJCORE__
487
488/// @}
489
490FASTJET_END_NAMESPACE // defined in fastjet/internal/base.hh
491
492#endif // __FASTJET_SELECTOR_HH__
493
Note: See TracBrowser for help on using the repository browser.