FastJet 3.0.5
SISConeSphericalPlugin.hh
00001 #ifndef __SISCONESPHERICALPLUGIN_HH__
00002 #define __SISCONESPHERICALPLUGIN_HH__
00003 
00004 #include "SISConeBasePlugin.hh"
00005 
00006 // forward declaration of the siscone classes we'll need
00007 namespace siscone_spherical{
00008   class CSphsiscone;
00009 }
00010 
00011 // questionable whether this should be in fastjet namespace or not...
00012 FASTJET_BEGIN_NAMESPACE      // defined in fastjet/internal/base.hh
00013 
00014 //----------------------------------------------------------------------
00015 //
00016 /// @ingroup plugins
00017 /// \class SISConeSphericalPlugin
00018 /// Implementation of the spherical version of the SISCone algorithm
00019 /// (plugin for fastjet v2.1 upwards)
00020 ///
00021 /// SISConeSphericalPlugin is a plugin for fastjet (v2.1 upwards) that
00022 /// provides an interface to the seedless infrared safe cone jet
00023 /// finder by Gregory Soyez and Gavin Salam.
00024 ///
00025 /// This is the version of SISCone using spherical coordinates. Compared
00026 /// to the original cylindrical version:
00027 ///
00028 ///  - Particles are within a cone if their opening angle relative to the
00029 ///    centre of the cone is less than R
00030 ///
00031 ///  - The split-merge step uses the total energy in the protojet as the
00032 ///    ordering and overlap-measure variable
00033 ///
00034 ///  - The IR safety of the split-merge step is _not_ guaranteed for
00035 ///    events consisting of two back-to-back identical heavy particles
00036 ///    that decay. This is because of potential degeneracies in the
00037 ///    ordering for the split-merge step. 
00038 ///
00039 ///    For moderate values of R the problem should not be too severe
00040 ///    (or may even be absent for some values of the overlap
00041 ///    parameter), however the user should be aware of the issue.
00042 ///
00043 ///    The default split-merge scale may change at a later date to
00044 ///    resolve this issue.
00045 ///
00046 ///
00047 /// SISCone uses geometrical techniques to exhaustively consider all
00048 /// possible distinct cones. It then finds out which ones are stable
00049 /// and sends the result to the Tevatron Run-II type split-merge
00050 /// procedure for overlapping cones.
00051 ///
00052 /// Four parameters govern the "physics" of the algorithm:
00053 ///
00054 ///  - the cone_radius (this should be self-explanatory!)
00055 ///
00056 ///  - the overlap_threshold is the parameter which dictates how much
00057 ///    two jets must overlap (E_overlap/min(E1,E2)) if they are to be 
00058 ///    merged
00059 ///
00060 ///  - Not all particles are in stable cones in the first round of
00061 ///    searching for stable cones; one can therefore optionally have the
00062 ///    the jet finder carry out additional passes of searching for
00063 ///    stable cones among particles that were in no stable cone in
00064 ///    previous passes --- the maximum number of passes carried out is
00065 ///    n_pass_max. If this is zero then additional passes are carried
00066 ///    out until no new stable cones are found.
00067 ///
00068 ///  - Protojet Emin: protojets that are below this Emin
00069 ///    (default = 0) are discarded before each iteration of the
00070 ///    split-merge loop.
00071 ///
00072 /// One parameter governs some internal algorithmic shortcuts: 
00073 ///
00074 /// - if "caching" is turned on then the last event clustered by
00075 ///   siscone is stored -- if the current event is identical and the
00076 ///   cone_radius and n_pass_max are identical, then the only part of
00077 ///   the clustering that needs to be rerun is the split-merge part,
00078 ///   leading to significant speed gains; there is a small (O(N) storage
00079 ///   and speed) penalty for caching, so it should be kept off
00080 ///   (default) if only a single overlap_threshold is used.
00081 ///
00082 /// The final jets can be accessed by requestion the
00083 /// inclusive_jets(...) from the ClusterSequence object. Note that
00084 /// these PseudoJets have their user_index() set to the index of the
00085 /// pass in which they were found (first pass = 0). NB: This does not
00086 /// currently work for jets that consist of a single particle.
00087 ///
00088 /// For further information on the details of the algorithm see the
00089 /// SISCone paper, arXiv:0704.0292 [JHEP 0705:086,2007].
00090 ///
00091 /// For documentation about the implementation, see the
00092 /// siscone/doc/html/index.html file.
00093 //
00094 class SISConeSphericalPlugin : public SISConeBasePlugin{
00095 public:
00096 
00097   /// enum for the different split-merge scale choices;
00098   /// Note that order _must_ be the same as in siscone
00099   enum SplitMergeScale {SM_E,        ///< Energy (IR unsafe with momentum conservation)
00100                         SM_Etilde    ///< sum_{i \in jet} E_i [1+sin^2(theta_iJ)]
00101   };
00102 
00103 
00104   /// Main constructor for the SISConeSpherical Plugin class.  
00105   ///
00106   ///
00107   SISConeSphericalPlugin (double cone_radius_in,
00108                           double overlap_threshold_in,
00109                           int    n_pass_max_in = 0,
00110                           double protojet_Emin_in = 0.0, 
00111                           bool   caching_in = false,
00112                           SplitMergeScale  split_merge_scale_in = SM_Etilde,
00113                           double split_merge_stopping_scale_in = 0.0){
00114     _cone_radius           =cone_radius_in;
00115     _overlap_threshold     =overlap_threshold_in;
00116     _n_pass_max            =n_pass_max_in;
00117     _protojet_Emin         =protojet_Emin_in;
00118     _caching               =caching_in;
00119     _split_merge_scale     =split_merge_scale_in;
00120     _split_merge_stopping_scale = split_merge_stopping_scale_in;
00121     _ghost_sep_scale       = 0.0;
00122     _use_E_weighted_splitting = false;
00123   }
00124 
00125   /// minimum energy for a protojet to be considered in the split-merge step
00126   /// of the algorithm
00127   double protojet_Emin  () const {return _protojet_Emin  ;}
00128 
00129   /// return the scale to be passed to SISCone as the protojet_Emin
00130   /// -- if we have a ghost separation scale that is above the
00131   /// protojet_ptmin, then the ghost_separation_scale becomes the
00132   /// relevant one to use here
00133   double protojet_or_ghost_Emin  () const {return std::max(_protojet_Emin,
00134                                                            _ghost_sep_scale);}
00135 
00136   /// indicates scale used in split-merge
00137   SplitMergeScale split_merge_scale() const {return _split_merge_scale;}
00138   /// sets scale used in split-merge
00139   void set_split_merge_scale(SplitMergeScale sms) {_split_merge_scale = sms;}
00140 
00141   /// indicate if the splittings are done using the anti-kt distance
00142   bool split_merge_use_E_weighted_splitting() const {return _use_E_weighted_splitting;}
00143   void set_split_merge_use_E_weighted_splitting(bool val) {
00144     _use_E_weighted_splitting = val;}
00145 
00146   /// overload the default as we don't provide support 
00147   /// for passive areas.
00148   virtual bool supports_ghosted_passive_areas() const {return true;}
00149   
00150   // the things that are required by base class
00151   virtual std::string description () const;
00152   virtual void run_clustering(ClusterSequence &) const ;
00153 
00154 protected:
00155   virtual void reset_stored_plugin() const;
00156 
00157 private:
00158   double _protojet_Emin;
00159   SplitMergeScale _split_merge_scale;
00160   bool _use_E_weighted_splitting;
00161 
00162   // part needed for the cache 
00163   // variables for caching the results and the input
00164   static std::auto_ptr<SISConeSphericalPlugin        > stored_plugin;
00165   static std::auto_ptr<std::vector<PseudoJet>        > stored_particles;
00166   static std::auto_ptr<siscone_spherical::CSphsiscone> stored_siscone;
00167 };
00168 
00169 //======================================================================
00170 /// @ingroup extra_info
00171 /// \class SISConeSphericalExtras
00172 /// Class that provides extra information about a SISCone clustering
00173 class SISConeSphericalExtras : public SISConeBaseExtras {
00174 public:
00175   /// constructor
00176   //  it just initialises the pass information 
00177   SISConeSphericalExtras(int nparticles)
00178     : SISConeBaseExtras(nparticles){}
00179 
00180   /// access to the siscone jet def plugin (more convenient than
00181   /// getting it from the original jet definition, because here it's
00182   /// directly of the right type (rather than the base type)
00183   const SISConeSphericalPlugin* jet_def_plugin() const {
00184     return dynamic_cast<const SISConeSphericalPlugin*>(_jet_def_plugin);
00185   }
00186 
00187 private:
00188   // let us be written to by SISConePlugin
00189   friend class SISConeSphericalPlugin;
00190 };
00191 
00192 FASTJET_END_NAMESPACE        // defined in fastjet/internal/base.hh
00193 
00194 #endif // __SISCONEPLUGIN_HH__
00195 
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends