JETAN/fastjet/fastjet/CDFMidPointPlugin.hh

   1 //STARTHEADER
   2 // $Id: CDFMidPointPlugin.hh 1186 2008-04-04 16:15:39Z salam $
   3 //
   4 // Copyright (c) 2005-2006, Matteo Cacciari and Gavin Salam
   5 //
   6 //----------------------------------------------------------------------
   7 // This file is part of FastJet.
   8 //
   9 //  FastJet is free software; you can redistribute it and/or modify
  10 //  it under the terms of the GNU General Public License as published by
  11 //  the Free Software Foundation; either version 2 of the License, or
  12 //  (at your option) any later version.
  13 //
  14 //  The algorithms that underlie FastJet have required considerable
  15 //  development and are described in hep-ph/0512210. If you use
  16 //  FastJet as part of work towards a scientific publication, please
  17 //  include a citation to the FastJet paper.
  18 //
  19 //  FastJet is distributed in the hope that it will be useful,
  20 //  but WITHOUT ANY WARRANTY; without even the implied warranty of
  21 //  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22 //  GNU General Public License for more details.
  23 //
  24 //  You should have received a copy of the GNU General Public License
  25 //  along with FastJet; if not, write to the Free Software
  26 //  Foundation, Inc.:
  27 //      59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  28 //----------------------------------------------------------------------
  29 //ENDHEADER
  30
  31 #ifndef __CDFMIDPOINTPLUGIN_HH__
  32 #define __CDFMIDPOINTPLUGIN_HH__
  33
  34 #include "fastjet/JetDefinition.hh"
  35
  36 // questionable whether this should be in fastjet namespace or not...
  37
  38 namespace fastjet {      // defined in fastjet/internal/base.hh
  39
  40 //----------------------------------------------------------------------
  41 //
  42 /// CDFMidPointPlugin is a plugin for fastjet (v2.1 upwards) that
  43 /// provides an interface to the CDF version of Run-II iterative cone
  44 /// algorithm with midpoint seeds (also known as the Iterative Legacy
  45 /// Cone Algorithm, ILCA).
  46 ///
  47 /// The CDF code has been taken from Joey Huston's webpage
  48 /// http://www.pa.msu.edu/~huston/Les_Houches_2005/Les_Houches_SM.html
  49 ///
  50 /// Note that the CDF midpoint code contains options that go beyond
  51 /// those described in the Tevatron run-II document (hep-ex/0005012),
  52 /// notably search-cones, as described in hep-ph/0111434, and
  53 /// midpoints bewteen multiplets of stable cones.
  54 ///
  55 /// Additionally, the version of the CDF midpoint code distributed
  56 /// here has been modified by the FastJet authors, so as to allow one
  57 /// to choose the scale used in the split-merge step.
  58 //
  59 //----------------------------------------------------------------------
  60 class CDFMidPointPlugin : public JetDefinition::Plugin {
  61 public:
  62   /// the choice of scale to be used in the split-merge step
  63   // NB: just replicates what we've added to the CDF midpoint code
  64   enum SplitMergeScale {SM_pt, SM_Et, SM_mt, SM_pttilde};
  65
  66   ///
  67   /// A CDFMidPointPlugin constructor that looks like the one provided
  68   /// by CDF. Its arguments should have the following meaning:
  69   ///
  70   /// - seed_threshold: minimum pt for a particle to be considered
  71   ///   a seed of the iteration.
  72   ///
  73   /// - cone_radius: standard meaning
  74   ///
  75   /// - cone_area_fraction: stable-cones are searched for with a
  76   ///   radius Rsearch = R * sqrt(cone_area_fraction), and then
  77   ///   expanded to size R afterwards; note (hep-ph/0610012) that this
  78   ///   introduces IR unsafety at NLO for X+2-jet observables (where X
  79   ///   any hard object).
  80   ///
  81   /// - max_pair_size: "midpoints" can be added between pairs of
  82   ///   stable cones, triplets of stable cones, etc.; max_pair_size
  83   ///   indicates the maximum number of stable cones that are
  84   ///   assembled when adding midpoints.
  85   ///
  86   /// - max_iterations: the maximum number of iterations to carry out
  87   ///   when looking for a stable cone.
  88   ///
  89   /// - overlap_threshold: if
  90   ///     (overlapping_Et)/(Et_of_softer_protojet) < overlap_threshold,
  91   ///   overlapping jets are split, otherwise they are merged.
  92   ///
  93   /// - sm_scale: a choice for the scale to be used in the split-merge
  94   ///   step (both for ordering the momenta and quantifying the
  95   ///   overlap); the three options are
  96   ///
  97   ///    . SM_pt: pt (default -- source of small IR safety issue in purely
  98   ///      hadronic events)
  99   ///
 100   ///    . SM_Et: Et (not boost invariant, reduces to mt at zero rapidity and
 101   ///      to pt and infinite rapidity)
 102   ///
 103   ///    . SM_mt: transverse mass = sqrt(m^2+pt^2)
 104   ///
 105   CDFMidPointPlugin (
 106                      double seed_threshold     ,
 107                      double cone_radius        ,
 108                      double cone_area_fraction ,
 109                      int    max_pair_size      ,
 110                      int    max_iterations     ,
 111                      double overlap_threshold  ,
 112                      SplitMergeScale sm_scale = SM_pt) :
 113     _seed_threshold     (seed_threshold     ),
 114     _cone_radius        (cone_radius        ),
 115     _cone_area_fraction (cone_area_fraction ),
 116     _max_pair_size      (max_pair_size      ),
 117     _max_iterations     (max_iterations     ),
 118     _overlap_threshold  (overlap_threshold  ),
 119     _sm_scale           (sm_scale)             {}
 120
 121   /// a compact constructor
 122   ///
 123   /// NB: as of version 2.4, the default value for the
 124   /// overlap_threshold threshold has been removed, to avoid
 125   /// misleading people into using the value of 0.5 without thinking,
 126   /// which is known to have adverse effects in high-noise
 127   /// environments. A recommended value is 0.75.
 128   CDFMidPointPlugin (double   cone_radius,
 129                      double   overlap_threshold,// = 0.5,
 130                      double   seed_threshold = 1.0,
 131                      double   cone_area_fraction = 1.0) :
 132     _seed_threshold     (seed_threshold     ),
 133     _cone_radius        (cone_radius        ),
 134     _cone_area_fraction (cone_area_fraction ),
 135     _max_pair_size      (2                  ),
 136     _max_iterations     (100                ),
 137     _overlap_threshold  (overlap_threshold  ),
 138     _sm_scale           (SM_pt)                {}
 139
 140
 141   // some functions to return info about parameters
 142   double seed_threshold     () const {return _seed_threshold     ;}
 143   double cone_radius        () const {return _cone_radius        ;}
 144   double cone_area_fraction () const {return _cone_area_fraction ;}
 145   int    max_pair_size      () const {return _max_pair_size      ;}
 146   int    max_iterations     () const {return _max_iterations     ;}
 147   double overlap_threshold  () const {return _overlap_threshold  ;}
 148
 149
 150   // the things that are required by base class
 151   virtual std::string description () const;
 152   virtual void run_clustering(ClusterSequence &) const;
 153   /// the plugin mechanism's standard way of accessing the jet radius
 154   virtual double R() const {return cone_radius();}
 155
 156 private:
 157
 158   double _seed_threshold    ;
 159   double _cone_radius       ;
 160   double _cone_area_fraction;
 161   int    _max_pair_size     ;
 162   int    _max_iterations    ;
 163   double _overlap_threshold ;
 164   SplitMergeScale _sm_scale ;
 165 };
 166
 167 } // fastjet namespace
 168
 169 #endif // __CDFMIDPOINTPLUGIN_HH__