FastJet  3.3.3
CDFMidPointPlugin.hh
1 //FJSTARTHEADER
2 // $Id: CDFMidPointPlugin.hh 4420 2019-11-29 09:28:20Z soyez $
3 //
4 // Copyright (c) 2005-2019, Matteo Cacciari, Gavin P. Salam and Gregory Soyez
5 //
6 //----------------------------------------------------------------------
7 // This file is part of FastJet.
8 //
9 // FastJet is free software; you can redistribute it and/or modify
10 // it under the terms of the GNU General Public License as published by
11 // the Free Software Foundation; either version 2 of the License, or
12 // (at your option) any later version.
13 //
14 // The algorithms that underlie FastJet have required considerable
15 // development. They are described in the original FastJet paper,
16 // hep-ph/0512210 and in the manual, arXiv:1111.6097. If you use
17 // FastJet as part of work towards a scientific publication, please
18 // quote the version you use and include a citation to the manual and
19 // optionally also to hep-ph/0512210.
20 //
21 // FastJet is distributed in the hope that it will be useful,
22 // but WITHOUT ANY WARRANTY; without even the implied warranty of
23 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
24 // GNU General Public License for more details.
25 //
26 // You should have received a copy of the GNU General Public License
27 // along with FastJet. If not, see <http://www.gnu.org/licenses/>.
28 //----------------------------------------------------------------------
29 //FJENDHEADER
30 
31 #ifndef __CDFMIDPOINTPLUGIN_HH__
32 #define __CDFMIDPOINTPLUGIN_HH__
33 
34 #include "fastjet/JetDefinition.hh"
35 
36 // questionable whether this should be in fastjet namespace or not...
37 
38 FASTJET_BEGIN_NAMESPACE // defined in fastjet/internal/base.hh
39 
40 //----------------------------------------------------------------------
41 //
42 /// @ingroup plugins
43 /// \class CDFMidPointPlugin
44 /// Implementation of the MidPoint algorithm from CDF (plugin for
45 /// fastjet-v2.1 upwards)
46 ///
47 /// A plugin for fastjet-v2.1 that provides an interface to the CDF
48 /// midpoint algorithm
49 ///
50 /// CDFMidPointPlugin is a plugin for fastjet (v2.1 upwards) that
51 /// provides an interface to the CDF version of Run-II iterative cone
52 /// algorithm with midpoint seeds (also known as the Iterative Legacy
53 /// Cone Algorithm, ILCA).
54 ///
55 /// The CDF code has been taken from Joey Huston's webpage
56 /// http://www.pa.msu.edu/~huston/Les_Houches_2005/Les_Houches_SM.html
57 ///
58 /// Note that the CDF midpoint code contains options that go beyond
59 /// those described in the Tevatron run-II document (hep-ex/0005012),
60 /// notably search-cones, as described in hep-ph/0111434, and
61 /// midpoints bewteen multiplets of stable cones.
62 ///
63 /// Additionally, the version of the CDF midpoint code distributed
64 /// here has been modified by the FastJet authors, so as to allow one
65 /// to choose the scale used in the split-merge step.
66 //
67 //----------------------------------------------------------------------
69 public:
70  /// the choice of scale to be used in the split-merge step
71  // NB: just replicates what we've added to the CDF midpoint code
72  enum SplitMergeScale {SM_pt, SM_Et, SM_mt, SM_pttilde};
73 
74  ///
75  /// A CDFMidPointPlugin constructor that looks like the one provided
76  /// by CDF. Its arguments should have the following meaning:
77  ///
78  /// - seed_threshold: minimum pt for a particle to be considered
79  /// a seed of the iteration.
80  ///
81  /// - cone_radius: standard meaning
82  ///
83  /// - cone_area_fraction: stable-cones are searched for with a
84  /// radius Rsearch = R * sqrt(cone_area_fraction), and then
85  /// expanded to size R afterwards; note (hep-ph/0610012) that this
86  /// introduces IR unsafety at NLO for X+2-jet observables (where X
87  /// any hard object).
88  ///
89  /// - max_pair_size: "midpoints" can be added between pairs of
90  /// stable cones, triplets of stable cones, etc.; max_pair_size
91  /// indicates the maximum number of stable cones that are
92  /// assembled when adding midpoints.
93  ///
94  /// - max_iterations: the maximum number of iterations to carry out
95  /// when looking for a stable cone.
96  ///
97  /// - overlap_threshold: if
98  /// (overlapping_Et)/(Et_of_softer_protojet) < overlap_threshold,
99  /// overlapping jets are split, otherwise they are merged.
100  ///
101  /// - sm_scale: a choice for the scale to be used in the split-merge
102  /// step (both for ordering the momenta and quantifying the
103  /// overlap); the three options are
104  ///
105  /// . SM_pt: pt (default -- source of small IR safety issue in purely
106  /// hadronic events)
107  ///
108  /// . SM_Et: Et (not boost invariant, reduces to mt at zero rapidity and
109  /// to pt and infinite rapidity)
110  ///
111  /// . SM_mt: transverse mass = sqrt(m^2+pt^2)
112  ///
114  double seed_threshold_in ,
115  double cone_radius_in ,
116  double cone_area_fraction_in ,
117  int max_pair_size_in ,
118  int max_iterations_in ,
119  double overlap_threshold_in ,
120  SplitMergeScale sm_scale_in = SM_pt) :
121  _seed_threshold (seed_threshold_in ),
122  _cone_radius (cone_radius_in ),
123  _cone_area_fraction (cone_area_fraction_in ),
124  _max_pair_size (max_pair_size_in ),
125  _max_iterations (max_iterations_in ),
126  _overlap_threshold (overlap_threshold_in ),
127  _sm_scale (sm_scale_in) {}
128 
129  /// a compact constructor
130  ///
131  /// NB: as of version 2.4, the default value for the
132  /// overlap_threshold threshold has been removed, to avoid
133  /// misleading people into using the value of 0.5 without thinking,
134  /// which is known to have adverse effects in high-noise
135  /// environments. A recommended value is 0.75.
136  CDFMidPointPlugin (double cone_radius_in,
137  double overlap_threshold_in,// = 0.5,
138  double seed_threshold_in = 1.0,
139  double cone_area_fraction_in = 1.0) :
140  _seed_threshold (seed_threshold_in ),
141  _cone_radius (cone_radius_in ),
142  _cone_area_fraction (cone_area_fraction_in ),
143  _max_pair_size (2 ),
144  _max_iterations (100 ),
145  _overlap_threshold (overlap_threshold_in ),
146  _sm_scale (SM_pt) {}
147 
148 
149  // some functions to return info about parameters
150  double seed_threshold () const {return _seed_threshold ;}
151  double cone_radius () const {return _cone_radius ;}
152  double cone_area_fraction () const {return _cone_area_fraction ;}
153  int max_pair_size () const {return _max_pair_size ;}
154  int max_iterations () const {return _max_iterations ;}
155  double overlap_threshold () const {return _overlap_threshold ;}
156 
157 
158  // the things that are required by base class
159  virtual std::string description () const;
160  virtual void run_clustering(ClusterSequence &) const;
161  /// the plugin mechanism's standard way of accessing the jet radius
162  virtual double R() const {return cone_radius();}
163 
164 private:
165 
166  double _seed_threshold ;
167  double _cone_radius ;
168  double _cone_area_fraction;
169  int _max_pair_size ;
170  int _max_iterations ;
171  double _overlap_threshold ;
172  SplitMergeScale _sm_scale ;
173 
174  static bool _first_time;
175 
176  /// print a banner for reference to the 3rd-party code
177  void _print_banner(std::ostream *ostr) const;
178 };
179 
180 FASTJET_END_NAMESPACE // defined in fastjet/internal/base.hh
181 
182 #endif // __CDFMIDPOINTPLUGIN_HH__
deals with clustering
CDFMidPointPlugin(double cone_radius_in, double overlap_threshold_in, double seed_threshold_in=1.0, double cone_area_fraction_in=1.0)
a compact constructor
CDFMidPointPlugin(double seed_threshold_in, double cone_radius_in, double cone_area_fraction_in, int max_pair_size_in, int max_iterations_in, double overlap_threshold_in, SplitMergeScale sm_scale_in=SM_pt)
A CDFMidPointPlugin constructor that looks like the one provided by CDF.
SplitMergeScale
the choice of scale to be used in the split-merge step
a class that allows a user to introduce their own "plugin" jet finder
Implementation of the MidPoint algorithm from CDF (plugin for fastjet-v2.1 upwards) ...
virtual double R() const
the plugin mechanism&#39;s standard way of accessing the jet radius