FastJet  3.1.3
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Modules Pages
SISConeSphericalPlugin.hh
1 #ifndef __SISCONESPHERICALPLUGIN_HH__
2 #define __SISCONESPHERICALPLUGIN_HH__
3 
4 #include "SISConeBasePlugin.hh"
5 
6 // forward declaration of the siscone classes we'll need
7 namespace siscone_spherical{
8  class CSphsiscone;
9 }
10 
11 // questionable whether this should be in fastjet namespace or not...
12 FASTJET_BEGIN_NAMESPACE // defined in fastjet/internal/base.hh
13 
14 //----------------------------------------------------------------------
15 //
16 /// @ingroup plugins
17 /// \class SISConeSphericalPlugin
18 /// Implementation of the spherical version of the SISCone algorithm
19 /// (plugin for fastjet v2.1 upwards)
20 ///
21 /// SISConeSphericalPlugin is a plugin for fastjet (v2.1 upwards) that
22 /// provides an interface to the seedless infrared safe cone jet
23 /// finder by Gregory Soyez and Gavin Salam.
24 ///
25 /// This is the version of SISCone using spherical coordinates. Compared
26 /// to the original cylindrical version:
27 ///
28 /// - Particles are within a cone if their opening angle relative to the
29 /// centre of the cone is less than R
30 ///
31 /// - The split-merge step uses the total energy in the protojet as the
32 /// ordering and overlap-measure variable
33 ///
34 /// - The IR safety of the split-merge step is _not_ guaranteed for
35 /// events consisting of two back-to-back identical heavy particles
36 /// that decay. This is because of potential degeneracies in the
37 /// ordering for the split-merge step.
38 ///
39 /// For moderate values of R the problem should not be too severe
40 /// (or may even be absent for some values of the overlap
41 /// parameter), however the user should be aware of the issue.
42 ///
43 /// The default split-merge scale may change at a later date to
44 /// resolve this issue.
45 ///
46 ///
47 /// SISCone uses geometrical techniques to exhaustively consider all
48 /// possible distinct cones. It then finds out which ones are stable
49 /// and sends the result to the Tevatron Run-II type split-merge
50 /// procedure for overlapping cones.
51 ///
52 /// Four parameters govern the "physics" of the algorithm:
53 ///
54 /// - the cone_radius (this should be self-explanatory!)
55 ///
56 /// - the overlap_threshold is the parameter which dictates how much
57 /// two jets must overlap (E_overlap/min(E1,E2)) if they are to be
58 /// merged
59 ///
60 /// - Not all particles are in stable cones in the first round of
61 /// searching for stable cones; one can therefore optionally have the
62 /// the jet finder carry out additional passes of searching for
63 /// stable cones among particles that were in no stable cone in
64 /// previous passes --- the maximum number of passes carried out is
65 /// n_pass_max. If this is zero then additional passes are carried
66 /// out until no new stable cones are found.
67 ///
68 /// - Protojet Emin: protojets that are below this Emin
69 /// (default = 0) are discarded before each iteration of the
70 /// split-merge loop.
71 ///
72 /// One parameter governs some internal algorithmic shortcuts:
73 ///
74 /// - if "caching" is turned on then the last event clustered by
75 /// siscone is stored -- if the current event is identical and the
76 /// cone_radius and n_pass_max are identical, then the only part of
77 /// the clustering that needs to be rerun is the split-merge part,
78 /// leading to significant speed gains; there is a small (O(N) storage
79 /// and speed) penalty for caching, so it should be kept off
80 /// (default) if only a single overlap_threshold is used.
81 ///
82 /// The final jets can be accessed by requestion the
83 /// inclusive_jets(...) from the ClusterSequence object. Note that
84 /// these PseudoJets have their user_index() set to the index of the
85 /// pass in which they were found (first pass = 0). NB: This does not
86 /// currently work for jets that consist of a single particle.
87 ///
88 /// For further information on the details of the algorithm see the
89 /// SISCone paper, arXiv:0704.0292 [JHEP 0705:086,2007].
90 ///
91 /// For documentation about the implementation, see the
92 /// siscone/doc/html/index.html file.
93 //
94 class SISConeSphericalPlugin : public SISConeBasePlugin{
95 public:
96 
97  /// enum for the different split-merge scale choices;
98  /// Note that order _must_ be the same as in siscone
99  enum SplitMergeScale {SM_E, ///< Energy (IR unsafe with momentum conservation)
100  SM_Etilde ///< sum_{i \in jet} E_i [1+sin^2(theta_iJ)]
101  };
102 
103 
104  /// Main constructor for the SISConeSpherical Plugin class.
105  ///
106  ///
107  SISConeSphericalPlugin (double cone_radius_in,
108  double overlap_threshold_in,
109  int n_pass_max_in = 0,
110  double protojet_Emin_in = 0.0,
111  bool caching_in = false,
112  SplitMergeScale split_merge_scale_in = SM_Etilde,
113  double split_merge_stopping_scale_in = 0.0){
114  _cone_radius =cone_radius_in;
115  _overlap_threshold =overlap_threshold_in;
116  _n_pass_max =n_pass_max_in;
117  _protojet_Emin =protojet_Emin_in;
118  _caching =caching_in;
119  _split_merge_scale =split_merge_scale_in;
120  _split_merge_stopping_scale = split_merge_stopping_scale_in;
121  _ghost_sep_scale = 0.0;
122  _use_E_weighted_splitting = false;
123  }
124 
125  /// minimum energy for a protojet to be considered in the split-merge step
126  /// of the algorithm
127  double protojet_Emin () const {return _protojet_Emin ;}
128 
129  /// return the scale to be passed to SISCone as the protojet_Emin
130  /// -- if we have a ghost separation scale that is above the
131  /// protojet_ptmin, then the ghost_separation_scale becomes the
132  /// relevant one to use here
133  double protojet_or_ghost_Emin () const {return std::max(_protojet_Emin,
134  _ghost_sep_scale);}
135 
136  /// indicates scale used in split-merge
137  SplitMergeScale split_merge_scale() const {return _split_merge_scale;}
138  /// sets scale used in split-merge
139  void set_split_merge_scale(SplitMergeScale sms) {_split_merge_scale = sms;}
140 
141  /// indicate if the splittings are done using the anti-kt distance
142  bool split_merge_use_E_weighted_splitting() const {return _use_E_weighted_splitting;}
143  void set_split_merge_use_E_weighted_splitting(bool val) {
144  _use_E_weighted_splitting = val;}
145 
146  /// overload the default as we don't provide support
147  /// for passive areas.
148  virtual bool supports_ghosted_passive_areas() const {return true;}
149 
150  // the things that are required by base class
151  virtual std::string description () const;
152  virtual void run_clustering(ClusterSequence &) const ;
153 
154  /// returns true because this plugin is intended for spherical
155  /// geometries (i.e. it's an e+e- algorithm).
156  virtual bool is_spherical() const {return true;}
157 
158 protected:
159  virtual void reset_stored_plugin() const;
160 
161 private:
162  double _protojet_Emin;
163  SplitMergeScale _split_merge_scale;
164  bool _use_E_weighted_splitting;
165 
166  // part needed for the cache
167  // variables for caching the results and the input
168  static std::auto_ptr<SISConeSphericalPlugin > stored_plugin;
169  static std::auto_ptr<std::vector<PseudoJet> > stored_particles;
170  static std::auto_ptr<siscone_spherical::CSphsiscone> stored_siscone;
171 };
172 
173 //======================================================================
174 /// @ingroup extra_info
175 /// \class SISConeSphericalExtras
176 /// Class that provides extra information about a SISCone clustering
178 public:
179  /// constructor
180  // it just initialises the pass information
181  SISConeSphericalExtras(int nparticles)
182  : SISConeBaseExtras(nparticles){}
183 
184  /// access to the siscone jet def plugin (more convenient than
185  /// getting it from the original jet definition, because here it's
186  /// directly of the right type (rather than the base type)
188  return dynamic_cast<const SISConeSphericalPlugin*>(_jet_def_plugin);
189  }
190 
191 private:
192  // let us be written to by SISConePlugin
193  friend class SISConeSphericalPlugin;
194 };
195 
196 FASTJET_END_NAMESPACE // defined in fastjet/internal/base.hh
197 
198 #endif // __SISCONEPLUGIN_HH__
199 
const SISConeSphericalPlugin * jet_def_plugin() const
access to the siscone jet def plugin (more convenient than getting it from the original jet definitio...
double protojet_or_ghost_Emin() const
return the scale to be passed to SISCone as the protojet_Emin – if we have a ghost separation scale ...
SplitMergeScale
enum for the different split-merge scale choices; Note that order must be the same as in siscone ...
deals with clustering
SISConeSphericalPlugin(double cone_radius_in, double overlap_threshold_in, int n_pass_max_in=0, double protojet_Emin_in=0.0, bool caching_in=false, SplitMergeScale split_merge_scale_in=SM_Etilde, double split_merge_stopping_scale_in=0.0)
Main constructor for the SISConeSpherical Plugin class.
Class that provides extra information about a SISCone clustering.
Implementation of the spherical version of the SISCone algorithm (plugin for fastjet v2...
virtual bool supports_ghosted_passive_areas() const
overload the default as we don't provide support for passive areas.
double protojet_Emin() const
minimum energy for a protojet to be considered in the split-merge step of the algorithm ...
bool split_merge_use_E_weighted_splitting() const
indicate if the splittings are done using the anti-kt distance
virtual bool is_spherical() const
returns true because this plugin is intended for spherical geometries (i.e.
SISConeSphericalExtras(int nparticles)
constructor
void set_split_merge_scale(SplitMergeScale sms)
sets scale used in split-merge
Class that provides extra information about a SISCone clustering.
SplitMergeScale split_merge_scale() const
indicates scale used in split-merge