FastJet 3.0.2
CDFMidPointPlugin.hh
00001 //STARTHEADER
00002 // $Id: CDFMidPointPlugin.hh 2758 2011-11-24 08:31:58Z soyez $
00003 //
00004 // Copyright (c) 2005-2011, Matteo Cacciari, Gavin P. Salam and Gregory Soyez
00005 //
00006 //----------------------------------------------------------------------
00007 // This file is part of FastJet.
00008 //
00009 //  FastJet is free software; you can redistribute it and/or modify
00010 //  it under the terms of the GNU General Public License as published by
00011 //  the Free Software Foundation; either version 2 of the License, or
00012 //  (at your option) any later version.
00013 //
00014 //  The algorithms that underlie FastJet have required considerable
00015 //  development and are described in hep-ph/0512210. If you use
00016 //  FastJet as part of work towards a scientific publication, please
00017 //  include a citation to the FastJet paper.
00018 //
00019 //  FastJet is distributed in the hope that it will be useful,
00020 //  but WITHOUT ANY WARRANTY; without even the implied warranty of
00021 //  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00022 //  GNU General Public License for more details.
00023 //
00024 //  You should have received a copy of the GNU General Public License
00025 //  along with FastJet. If not, see <http://www.gnu.org/licenses/>.
00026 //----------------------------------------------------------------------
00027 //ENDHEADER
00028 
00029 #ifndef __CDFMIDPOINTPLUGIN_HH__
00030 #define __CDFMIDPOINTPLUGIN_HH__
00031 
00032 #include "fastjet/JetDefinition.hh"
00033 
00034 // questionable whether this should be in fastjet namespace or not...
00035 
00036 FASTJET_BEGIN_NAMESPACE      // defined in fastjet/internal/base.hh
00037 
00038 //----------------------------------------------------------------------
00039 //
00040 /// @ingroup plugins
00041 /// \class CDFMidPointPlugin
00042 /// Implementation of the MidPoint algorithm from CDF (plugin for
00043 /// fastjet-v2.1 upwards)
00044 ///
00045 /// A plugin for fastjet-v2.1 that provides an interface to the CDF
00046 /// midpoint algorithm
00047 ///
00048 /// CDFMidPointPlugin is a plugin for fastjet (v2.1 upwards) that
00049 /// provides an interface to the CDF version of Run-II iterative cone
00050 /// algorithm with midpoint seeds (also known as the Iterative Legacy
00051 /// Cone Algorithm, ILCA).
00052 ///
00053 /// The CDF code has been taken from Joey Huston's webpage
00054 /// http://www.pa.msu.edu/~huston/Les_Houches_2005/Les_Houches_SM.html
00055 ///
00056 /// Note that the CDF midpoint code contains options that go beyond
00057 /// those described in the Tevatron run-II document (hep-ex/0005012),
00058 /// notably search-cones, as described in hep-ph/0111434, and
00059 /// midpoints bewteen multiplets of stable cones.
00060 ///
00061 /// Additionally, the version of the CDF midpoint code distributed
00062 /// here has been modified by the FastJet authors, so as to allow one
00063 /// to choose the scale used in the split-merge step.
00064 //
00065 //----------------------------------------------------------------------
00066 class CDFMidPointPlugin : public JetDefinition::Plugin {
00067 public:
00068   /// the choice of scale to be used in the split-merge step
00069   // NB: just replicates what we've added to the CDF midpoint code
00070   enum SplitMergeScale {SM_pt, SM_Et, SM_mt, SM_pttilde};
00071 
00072   ///
00073   /// A CDFMidPointPlugin constructor that looks like the one provided
00074   /// by CDF. Its arguments should have the following meaning:
00075   ///
00076   /// - seed_threshold: minimum pt for a particle to be considered 
00077   ///   a seed of the iteration.
00078   ///
00079   /// - cone_radius: standard meaning
00080   ///
00081   /// - cone_area_fraction: stable-cones are searched for with a
00082   ///   radius Rsearch = R * sqrt(cone_area_fraction), and then
00083   ///   expanded to size R afterwards; note (hep-ph/0610012) that this
00084   ///   introduces IR unsafety at NLO for X+2-jet observables (where X
00085   ///   any hard object).
00086   ///
00087   /// - max_pair_size: "midpoints" can be added between pairs of
00088   ///   stable cones, triplets of stable cones, etc.; max_pair_size
00089   ///   indicates the maximum number of stable cones that are
00090   ///   assembled when adding midpoints.
00091   ///
00092   /// - max_iterations: the maximum number of iterations to carry out
00093   ///   when looking for a stable cone.
00094   ///
00095   /// - overlap_threshold: if
00096   ///     (overlapping_Et)/(Et_of_softer_protojet) < overlap_threshold,
00097   ///   overlapping jets are split, otherwise they are merged.
00098   ///
00099   /// - sm_scale: a choice for the scale to be used in the split-merge
00100   ///   step (both for ordering the momenta and quantifying the
00101   ///   overlap); the three options are
00102   ///
00103   ///    . SM_pt: pt (default -- source of small IR safety issue in purely
00104   ///      hadronic events)
00105   ///
00106   ///    . SM_Et: Et (not boost invariant, reduces to mt at zero rapidity and
00107   ///      to pt and infinite rapidity)
00108   ///
00109   ///    . SM_mt: transverse mass = sqrt(m^2+pt^2)
00110   ///
00111   CDFMidPointPlugin (
00112                      double seed_threshold_in     ,      
00113                      double cone_radius_in        ,
00114                      double cone_area_fraction_in ,
00115                      int    max_pair_size_in      ,
00116                      int    max_iterations_in     ,
00117                      double overlap_threshold_in  ,
00118                      SplitMergeScale sm_scale_in = SM_pt) :
00119     _seed_threshold     (seed_threshold_in     ),    
00120     _cone_radius        (cone_radius_in        ),
00121     _cone_area_fraction (cone_area_fraction_in ),
00122     _max_pair_size      (max_pair_size_in      ),
00123     _max_iterations     (max_iterations_in     ),
00124     _overlap_threshold  (overlap_threshold_in  ),
00125     _sm_scale           (sm_scale_in)             {}
00126 
00127   /// a compact constructor
00128   ///
00129   /// NB: as of version 2.4, the default value for the
00130   /// overlap_threshold threshold has been removed, to avoid
00131   /// misleading people into using the value of 0.5 without thinking,
00132   /// which is known to have adverse effects in high-noise
00133   /// environments. A recommended value is 0.75.
00134   CDFMidPointPlugin (double   cone_radius_in, 
00135                      double   overlap_threshold_in,// = 0.5, 
00136                      double   seed_threshold_in = 1.0,       
00137                      double   cone_area_fraction_in = 1.0) : 
00138     _seed_threshold     (seed_threshold_in     ),    
00139     _cone_radius        (cone_radius_in        ),
00140     _cone_area_fraction (cone_area_fraction_in ),
00141     _max_pair_size      (2                     ),
00142     _max_iterations     (100                   ),
00143     _overlap_threshold  (overlap_threshold_in  ),
00144     _sm_scale           (SM_pt)                {}
00145 
00146 
00147   // some functions to return info about parameters
00148   double seed_threshold     () const {return _seed_threshold     ;}
00149   double cone_radius        () const {return _cone_radius        ;}
00150   double cone_area_fraction () const {return _cone_area_fraction ;}
00151   int    max_pair_size      () const {return _max_pair_size      ;}
00152   int    max_iterations     () const {return _max_iterations     ;}
00153   double overlap_threshold  () const {return _overlap_threshold  ;}
00154 
00155 
00156   // the things that are required by base class
00157   virtual std::string description () const;
00158   virtual void run_clustering(ClusterSequence &) const;
00159   /// the plugin mechanism's standard way of accessing the jet radius
00160   virtual double R() const {return cone_radius();}
00161                       
00162 private:
00163 
00164   double _seed_threshold    ;
00165   double _cone_radius       ;
00166   double _cone_area_fraction;
00167   int    _max_pair_size     ;
00168   int    _max_iterations    ;
00169   double _overlap_threshold ;
00170   SplitMergeScale _sm_scale ;
00171 
00172   static bool _first_time;
00173 
00174   /// print a banner for reference to the 3rd-party code
00175   void _print_banner(std::ostream *ostr) const;
00176 };
00177 
00178 FASTJET_END_NAMESPACE      // defined in fastjet/internal/base.hh
00179 
00180 #endif // __CDFMIDPOINTPLUGIN_HH__
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends