FastJet 3.0.0
SISConePlugin.hh
00001 #ifndef __SISCONEPLUGIN_HH__
00002 #define __SISCONEPLUGIN_HH__
00003 
00004 #include "SISConeBasePlugin.hh"
00005 
00006 // forward declaration of the siscone classes we'll need
00007 namespace siscone{
00008   class Csiscone;
00009 }
00010 
00011 
00012 FASTJET_BEGIN_NAMESPACE      // defined in fastjet/internal/base.hh
00013 
00014 //----------------------------------------------------------------------
00015 //
00016 /// @ingroup plugins
00017 /// \class SISConePlugin
00018 /// Implementation of the SISCone algorithm (plugin for fastjet v2.1 upwards)
00019 ///
00020 /// SISConePlugin is a plugin for fastjet (v2.1 upwards) that provides
00021 /// an interface to the seedless infrared safe cone jet finder by
00022 /// Gregory Soyez and Gavin Salam.
00023 ///
00024 /// SISCone uses geometrical techniques to exhaustively consider all
00025 /// possible distinct cones. It then finds out which ones are stable
00026 /// and sends the result to the Tevatron Run-II type split-merge
00027 /// procedure for overlapping cones.
00028 ///
00029 /// Four parameters govern the "physics" of the algorithm:
00030 ///
00031 ///  - the cone_radius (this should be self-explanatory!)
00032 ///
00033 ///  - the overlap_threshold is the parameter which dictates how much
00034 ///    two jets must overlap (pt_overlap/min(pt1,pt2)) if they are to be 
00035 ///    merged
00036 ///
00037 ///  - Not all particles are in stable cones in the first round of
00038 ///    searching for stable cones; one can therefore optionally have the
00039 ///    the jet finder carry out additional passes of searching for
00040 ///    stable cones among particles that were in no stable cone in
00041 ///    previous passes --- the maximum number of passes carried out is
00042 ///    n_pass_max. If this is zero then additional passes are carried
00043 ///    out until no new stable cones are found.
00044 ///
00045 ///  - Protojet ptmin: protojets that are below this ptmin
00046 ///    (default = 0) are discarded before each iteration of the
00047 ///    split-merge loop.
00048 ///
00049 /// One parameter governs some internal algorithmic shortcuts: 
00050 ///
00051 /// - if "caching" is turned on then the last event clustered by
00052 ///   siscone is stored -- if the current event is identical and the
00053 ///   cone_radius and n_pass_mass are identical, then the only part of
00054 ///   the clustering that needs to be rerun is the split-merge part,
00055 ///   leading to significant speed gains; there is a small (O(N) storage
00056 ///   and speed) penalty for caching, so it should be kept off
00057 ///   (default) if only a single overlap_threshold is used.
00058 ///
00059 /// The final jets can be accessed by requestion the
00060 /// inclusive_jets(...) from the ClusterSequence object. Note that
00061 /// these PseudoJets have their user_index() set to the index of the
00062 /// pass in which they were found (first pass = 0). NB: This does not
00063 /// currently work for jets that consist of a single particle.
00064 ///
00065 /// For further information on the details of the algorithm see the
00066 /// SISCone paper, arXiv:0704.0292 [JHEP 0705:086,2007].
00067 ///
00068 /// For documentation about the implementation, see the
00069 /// siscone/doc/html/index.html file.
00070 //
00071 class SISConePlugin : public SISConeBasePlugin{
00072 public:
00073 
00074   /// enum for the different split-merge scale choices;
00075   /// Note that order _must_ be the same as in siscone
00076   enum SplitMergeScale {SM_pt,     ///< transverse momentum (E-scheme), IR unsafe
00077                         SM_Et,     ///< transverse energy (E-scheme), not long. boost invariant
00078                                    ///< original run-II choice [may not be implemented]
00079                         SM_mt,     ///< transverse mass (E-scheme), IR safe except
00080                                    ///< in decays of two identical narrow heavy particles
00081                         SM_pttilde ///< pt-scheme pt = \sum_{i in jet} |p_{ti}|, should
00082                                    ///< be IR safe in all cases
00083   };
00084 
00085 
00086   /// Main constructor for the SISCone Plugin class.  
00087   ///
00088   /// Note: wrt version prior to 2.4 this constructor differs in that a 
00089   /// the default value has been removed for overlap_threshold. The
00090   /// former has been removed because the old default of 0.5 was found
00091   /// to be unsuitable in high-noise environments; so the user should
00092   /// now explicitly think about the value for this -- we recommend
00093   /// 0.75.
00094   ///
00095   SISConePlugin (double cone_radius,
00096                  double overlap_threshold,
00097                  int    n_pass_max = 0,
00098                  double protojet_ptmin = 0.0, 
00099                  bool   caching = false,
00100                  SplitMergeScale  split_merge_scale = SM_pttilde,
00101                  double split_merge_stopping_scale = 0.0){
00102     _cone_radius           = cone_radius;
00103     _overlap_threshold     = overlap_threshold;
00104     _n_pass_max            = n_pass_max;
00105     _protojet_ptmin        = protojet_ptmin;
00106     _caching               = caching;   
00107     _split_merge_scale     = split_merge_scale;
00108     _split_merge_stopping_scale = split_merge_stopping_scale;
00109     _ghost_sep_scale       = 0.0;
00110     _use_pt_weighted_splitting = false;}
00111 
00112 
00113   /// Backwards compatible constructor for the SISCone Plugin class
00114   SISConePlugin (double cone_radius,
00115                  double overlap_threshold,
00116                  int    n_pass_max,
00117                  double protojet_ptmin, 
00118                  bool   caching ,
00119                  bool   split_merge_on_transverse_mass){
00120     _cone_radius           = cone_radius;
00121     _overlap_threshold     = overlap_threshold;
00122     _n_pass_max            = n_pass_max;
00123     _protojet_ptmin        = protojet_ptmin;
00124     _caching               = caching;   
00125     _split_merge_stopping_scale = 0.0;
00126     _split_merge_scale     = split_merge_on_transverse_mass ? SM_mt : SM_pttilde;
00127     _ghost_sep_scale       = 0.0;}
00128   
00129   /// backwards compatible constructor for the SISCone Plugin class
00130   /// (avoid using this in future).
00131   SISConePlugin (double cone_radius,
00132                  double overlap_threshold,
00133                  int    n_pass_max,
00134                  bool   caching ) {
00135     _cone_radius           = cone_radius;
00136     _overlap_threshold     = overlap_threshold;
00137     _n_pass_max            = n_pass_max;
00138     _protojet_ptmin        = 0.0;
00139     _caching               = caching;   
00140     _split_merge_scale     = SM_mt;
00141     _split_merge_stopping_scale = 0.0;
00142     _ghost_sep_scale       = 0.0;
00143     _use_pt_weighted_splitting = false;}
00144 
00145   /// minimum pt for a protojet to be considered in the split-merge step
00146   /// of the algorithm
00147   double protojet_ptmin  () const {return _protojet_ptmin  ;}
00148 
00149   /// return the scale to be passed to SISCone as the protojet_ptmin
00150   /// -- if we have a ghost separation scale that is above the
00151   /// protojet_ptmin, then the ghost_separation_scale becomes the
00152   /// relevant one to use here
00153   double protojet_or_ghost_ptmin  () const {return std::max(_protojet_ptmin,
00154                                                             _ghost_sep_scale);}
00155 
00156   /// indicates scale used in split-merge
00157   SplitMergeScale split_merge_scale() const {return _split_merge_scale;}
00158   /// sets scale used in split-merge
00159   void set_split_merge_scale(SplitMergeScale sms) {_split_merge_scale = sms;}
00160 
00161   /// indicates whether the split-merge orders on transverse mass or not.
00162   /// retained for backwards compatibility with 2.1.0b3
00163   bool split_merge_on_transverse_mass() const {return _split_merge_scale == SM_mt ;}
00164   void set_split_merge_on_transverse_mass(bool val) {
00165     _split_merge_scale = val  ? SM_mt : SM_pt;}
00166 
00167   /// indicates whether the split-merge orders on transverse mass or not.
00168   /// retained for backwards compatibility with 2.1.0b3
00169   bool split_merge_use_pt_weighted_splitting() const {return _use_pt_weighted_splitting;}
00170   void set_split_merge_use_pt_weighted_splitting(bool val) {
00171     _use_pt_weighted_splitting = val;}
00172 
00173   // the things that are required by base class
00174   virtual std::string description () const;
00175   virtual void run_clustering(ClusterSequence &) const ;
00176 
00177 protected:
00178   virtual void reset_stored_plugin() const;
00179 
00180 private:
00181   double _protojet_ptmin;
00182   SplitMergeScale _split_merge_scale;
00183 
00184   bool _use_pt_weighted_splitting;
00185 
00186   // part needed for the cache 
00187   // variables for caching the results and the input
00188   static std::auto_ptr<SISConePlugin          > stored_plugin;
00189   static std::auto_ptr<std::vector<PseudoJet> > stored_particles;
00190   static std::auto_ptr<siscone::Csiscone      > stored_siscone;
00191 };
00192 
00193 
00194 //======================================================================
00195 /// @ingroup extra_info
00196 /// \class SISConeExtras
00197 /// Class that provides extra information about a SISCone clustering
00198 class SISConeExtras : public SISConeBaseExtras {
00199 public:
00200   /// constructor
00201   //  it just initialises the pass information 
00202   SISConeExtras(int nparticles)
00203     : SISConeBaseExtras(nparticles){}
00204 
00205   /// access to the siscone jet def plugin (more convenient than
00206   /// getting it from the original jet definition, because here it's
00207   /// directly of the right type (rather than the base type)
00208   const SISConePlugin* jet_def_plugin() const {
00209     return dynamic_cast<const SISConePlugin*>(_jet_def_plugin);
00210   }
00211 
00212 private:
00213   // let us be written to by SISConePlugin
00214   friend class SISConePlugin;
00215 };
00216 
00217 FASTJET_END_NAMESPACE        // defined in fastjet/internal/base.hh
00218 
00219 #endif // __SISCONEPLUGIN_HH__
00220 
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends