FastJet  3.4.0
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 SharedPtr<SISConeSphericalPlugin > stored_plugin;
169  static SharedPtr<std::vector<PseudoJet> > stored_particles;
170  static SharedPtr<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 
deals with clustering
Class that provides extra information about a SISCone clustering.
Class that provides extra information about a SISCone clustering.
const SISConeSphericalPlugin * jet_def_plugin() const
access to the siscone jet def plugin (more convenient than getting it from the original jet definitio...
SISConeSphericalExtras(int nparticles)
constructor
Implementation of the spherical version of the SISCone algorithm (plugin for fastjet v2....
SplitMergeScale
enum for the different split-merge scale choices; Note that order must be the same as in siscone
@ SM_E
Energy (IR unsafe with momentum conservation)
double protojet_Emin() const
minimum energy for a protojet to be considered in the split-merge step of the algorithm
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 t...
virtual bool is_spherical() const
returns true because this plugin is intended for spherical geometries (i.e.
SplitMergeScale split_merge_scale() const
indicates scale used in split-merge
void set_split_merge_scale(SplitMergeScale sms)
sets scale used in split-merge
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.
virtual bool supports_ghosted_passive_areas() const
overload the default as we don't provide support for passive areas.
bool split_merge_use_E_weighted_splitting() const
indicate if the splittings are done using the anti-kt distance
An implementation of shared pointers that is broadly similar to C++11 shared_ptr (https://en....
Definition: SharedPtr.hh:341