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