Fork me on GitHub

source: svn/trunk/Utilities/Fastjet/plugins/SISCone/SISConePlugin.hh@ 228

Last change on this file since 228 was 11, checked in by severine ovyn, 16 years ago

Fastjet added; CDFCones directory has been changed

File size: 11.2 KB
Line 
1#ifndef __SISCONEPLUGIN_HH__
2#define __SISCONEPLUGIN_HH__
3
4#include "Utilities/Fastjet/include/fastjet/JetDefinition.hh"
5#include "Utilities/Fastjet/include/fastjet/ClusterSequence.hh" // needed for the extras we define
6#include <vector>
7#include <memory>
8#include <cmath>
9
10// put a forward declaration to the Csiscone class to avoid having to
11// include the siscone headers here
12namespace siscone {
13 class Csiscone;
14}
15
16// questionable whether this should be in fastjet namespace or not...
17FASTJET_BEGIN_NAMESPACE // defined in fastjet/internal/base.hh
18
19// another forward declaration to reduce includes
20class PseudoJet;
21
22//----------------------------------------------------------------------
23//
24/// SISConePlugin is a plugin for fastjet (v2.1 upwards) that provides
25/// an interface to the seedless infrared safe cone jet finder by
26/// Gregory Soyez and Gavin Salam.
27///
28/// As of 2006-12-26, this plugin is beta, as is the SISCone code
29/// itself.
30///
31/// SISCone uses geometrical techniques to exhaustively consider all
32/// possible distinct cones. It then finds out which ones are stable
33/// and sends the result to the Tevatron Run-II type split-merge
34/// procedure for overlapping cones.
35///
36/// Four parameters govern the "physics" of the algorithm:
37///
38/// - the cone_radius (this should be self-explanatory!)
39///
40/// - the overlap_threshold is the parameter which dictates how much
41/// two jets must overlap (pt_overlap/min(pt1,pt2)) if they are to be
42/// merged
43///
44/// - Not all particles are in stable cones in the first round of
45/// searching for stable cones; one can therefore optionally have the
46/// the jet finder carry out additional passes of searching for
47/// stable cones among particles that were in no stable cone in
48/// previous passes --- the maximum number of passes carried out is
49/// n_pass_max. If this is zero then additional passes are carried
50/// out until no new stable cones are found.
51///
52/// - Protojet ptmin: protojets that are below this ptmin
53/// (default = 0) are discarded before each iteration of the
54/// split-merge loop.
55///
56/// One parameter governs some internal algorithmic shortcuts:
57///
58/// - if "caching" is turned on then the last event clustered by
59/// siscone is stored -- if the current event is identical and the
60/// cone_radius and n_pass_mass are identical, then the only part of
61/// the clustering that needs to be rerun is the split-merge part,
62/// leading to significant speed gains; there is a small (O(N) storage
63/// and speed) penalty for caching, so it should be kept off
64/// (default) if only a single overlap_threshold is used.
65///
66/// The final jets can be accessed by requestion the
67/// inclusive_jets(...) from the ClusterSequence object. Note that
68/// these PseudoJets have their user_index() set to the index of the
69/// pass in which they were found (first pass = 0). NB: This does not
70/// currently work for jets that consist of a single particle.
71///
72/// For further information on the details of the algorithm see the
73/// SISCone paper; for documentation about the implementation, see the
74/// siscone/doc/html/index.html file.
75//
76class SISConePlugin : public JetDefinition::Plugin {
77public:
78
79 /// enum for the different split-merge scale choices;
80 /// Note that order _must_ be the same as in siscone
81 enum SplitMergeScale {SM_pt, ///< transverse momentum (E-scheme), IR unsafe
82 SM_Et, ///< transverse energy (E-scheme), not long. boost invariant
83 ///< original run-II choice [may not be implemented]
84 SM_mt, ///< transverse mass (E-scheme), IR safe except
85 ///< in decays of two identical narrow heavy particles
86 SM_pttilde ///< pt-scheme pt = \sum_{i in jet} |p_{ti}|, should
87 ///< be IR safe in all cases
88 };
89
90
91 /// Constructor for the SISCone Plugin class.
92 ///
93 /// Note: though the default value here for the overlap_threshold is
94 /// 0.5 (for backwards compatibility), there is a strong
95 /// recommendation to use a higher value, e.g. 0.75, especially in
96 /// environments with a substantial amount of underlying event or
97 /// pileup.
98 SISConePlugin (double cone_radius,
99 double overlap_threshold = 0.5,
100 int n_pass_max = 0,
101 double protojet_ptmin = 0.0,
102 bool caching = false,
103 SplitMergeScale split_merge_scale = SM_pttilde,
104 double split_merge_stopping_scale = 0.0) :
105 _cone_radius (cone_radius ),
106 _overlap_threshold (overlap_threshold ),
107 _n_pass_max (n_pass_max ),
108 _protojet_ptmin (protojet_ptmin),
109 _caching (caching),
110 _split_merge_scale (split_merge_scale),
111 _split_merge_stopping_scale (split_merge_stopping_scale),
112 _ghost_sep_scale (0.0) {}
113
114 /// Backwards compatible constructor for the SISCone Plugin class
115 SISConePlugin (double cone_radius,
116 double overlap_threshold,
117 int n_pass_max,
118 double protojet_ptmin,
119 bool caching ,
120 bool split_merge_on_transverse_mass) :
121 _cone_radius (cone_radius ),
122 _overlap_threshold (overlap_threshold ),
123 _n_pass_max (n_pass_max ),
124 _protojet_ptmin (protojet_ptmin),
125 _caching (caching),
126 _split_merge_scale (split_merge_on_transverse_mass ? SM_mt : SM_pttilde),
127 _ghost_sep_scale (0.0) {}
128
129 /// backwards compatible constructor for the SISCone Plugin class
130 /// (avoid using this in future).
131 SISConePlugin (double cone_radius,
132 double overlap_threshold,
133 int n_pass_max,
134 bool caching ) :
135 _cone_radius (cone_radius ),
136 _overlap_threshold (overlap_threshold ),
137 _n_pass_max (n_pass_max ),
138 _protojet_ptmin (0.0),
139 _caching (caching),
140 _split_merge_scale (SM_mt),
141 _ghost_sep_scale (0.0) {}
142
143 /// copy constructor
144 SISConePlugin (const SISConePlugin & plugin) {
145 *this = plugin;
146 }
147
148 /// the cone radius
149 double cone_radius () const {return _cone_radius ;}
150
151 /// Fraction of overlap energy in a jet above which jets are merged
152 /// and below which jets are split.
153 double overlap_threshold () const {return _overlap_threshold ;}
154
155 /// the maximum number of passes of stable-cone searching (<=0 is same
156 /// as infinity).
157 int n_pass_max () const {return _n_pass_max ;}
158
159 /// minimum pt for a protojet to be considered in the split-merge step
160 /// of the algorithm
161 double protojet_ptmin () const {return _protojet_ptmin ;}
162
163 /// return the scale to be passed to SISCone as the protojet_ptmin
164 /// -- if we have a ghost separation scale that is above the
165 /// protojet_ptmin, then the ghost_separation_scale becomes the
166 /// relevant one to use here
167 double protojet_or_ghost_ptmin () const {return std::max(_protojet_ptmin,
168 _ghost_sep_scale);}
169
170 /// indicates scale used in split-merge
171 SplitMergeScale split_merge_scale() const {return _split_merge_scale;}
172 /// sets scale used in split-merge
173 void set_split_merge_scale(SplitMergeScale sms) {_split_merge_scale = sms;}
174
175 /// indicates whether the split-merge orders on transverse mass or not.
176 /// retained for backwards compatibility with 2.1.0b3
177 bool split_merge_on_transverse_mass() const {return _split_merge_scale == SM_mt ;}
178 void set_split_merge_on_transverse_mass(bool val) {
179 _split_merge_scale = val ? SM_mt : SM_pt;}
180
181 /// set the "split_merge_stopping_scale": if the scale variable for
182 /// all protojets is below this, then stop the split-merge procedure
183 /// and keep only those jets found so far. This is useful in
184 /// determination of areas of hard jets because it can be used to
185 /// avoid running the split-merging on the pure ghost-part of the
186 /// event.
187 void set_split_merge_stopping_scale(double scale) {
188 _split_merge_stopping_scale = scale;}
189
190 /// return the value of the split_merge_stopping_scale (see
191 /// set_split_merge_stopping_scale(...) for description)
192 double split_merge_stopping_scale() {return _split_merge_stopping_scale;}
193
194 /// indicates whether caching is turned on or not.
195 bool caching() const {return _caching ;}
196
197 // the things that are required by base class
198 virtual std::string description () const;
199 virtual void run_clustering(ClusterSequence &) const;
200 /// the plugin mechanism's standard way of accessing the jet radius
201 virtual double R() const {return cone_radius();}
202
203 /// return true since there is specific support for the measurement
204 /// of passive areas, in the sense that areas determined from all
205 /// particles below the ghost separation scale will be a passive
206 /// area.
207 virtual bool supports_ghosted_passive_areas() const {return true;}
208
209 /// set the ghost separation scale for passive area determinations
210 /// _just_ in the next run (strictly speaking that makes the routine
211 /// a non const, so related internal info must be stored as a mutable)
212 virtual void set_ghost_separation_scale(double scale) const {
213 _ghost_sep_scale = scale;
214 }
215
216 virtual double ghost_separation_scale() const {return _ghost_sep_scale;}
217
218private:
219 double _cone_radius, _overlap_threshold;
220 int _n_pass_max;
221 double _protojet_ptmin;
222 bool _caching;//, _split_merge_on_transverse_mass;
223 SplitMergeScale _split_merge_scale;
224 double _split_merge_stopping_scale;
225
226 mutable double _ghost_sep_scale;
227
228 // variables for caching the results and the input
229 static std::auto_ptr<SISConePlugin > stored_plugin;
230 static std::auto_ptr<std::vector<PseudoJet> > stored_particles;
231 static std::auto_ptr<siscone::Csiscone > stored_siscone;
232
233};
234
235
236//======================================================================
237/// Class that provides extra information about a SISCone clustering
238class SISConeExtras : public ClusterSequence::Extras {
239public:
240 /// returns a reference to the vector of stable cones (aka protocones)
241 const std::vector<PseudoJet> & stable_cones() const {return _protocones;}
242
243 /// an old name for getting the vector of stable cones (aka protocones)
244 const std::vector<PseudoJet> & protocones() const {return _protocones;}
245
246
247 /// access to the siscone jet def plugin (more convenient than
248 /// getting it from the original jet definition, because here it's
249 /// directly of the right type (rather than the base type)
250 const SISConePlugin * jet_def_plugin() const {return _jet_def_plugin;}
251
252 /// return a brief summary of the contents of the extras object
253 /// (specifically, the number of protocones.
254 std::string description() const;
255
256 /// return the smallest difference in squared distance encountered
257 /// during splitting between a particle and two overlapping
258 /// protojets.
259 inline double most_ambiguous_split() const {return _most_ambiguous_split;}
260
261private:
262 std::vector<PseudoJet> _protocones;
263 const SISConePlugin * _jet_def_plugin;
264 double _most_ambiguous_split;
265 // let us be written to by SISConePlugin
266 friend class SISConePlugin;
267};
268
269
270FASTJET_END_NAMESPACE // defined in fastjet/internal/base.hh
271
272#endif // __SISCONEPLUGIN_HH__
273
Note: See TracBrowser for help on using the repository browser.