JETAN/fastjet/siscone/siscone.h

   1 // -*- C++ -*-
   2 ///////////////////////////////////////////////////////////////////////////////
   3 // File: siscone.h                                                           //
   4 // Description: header file for the main SISCone class                       //
   5 // This file is part of the SISCone project.                                 //
   6 // For more details, see http://projects.hepforge.org/siscone                //
   7 //                                                                           //
   8 // Copyright (c) 2006 Gavin Salam and Gregory Soyez                          //
   9 //                                                                           //
  10 // This program is free software; you can redistribute it and/or modify      //
  11 // it under the terms of the GNU General Public License as published by      //
  12 // the Free Software Foundation; either version 2 of the License, or         //
  13 // (at your option) any later version.                                       //
  14 //                                                                           //
  15 // This program is distributed in the hope that it will be useful,           //
  16 // but WITHOUT ANY WARRANTY; without even the implied warranty of            //
  17 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the             //
  18 // GNU General Public License for more details.                              //
  19 //                                                                           //
  20 // You should have received a copy of the GNU General Public License         //
  21 // along with this program; if not, write to the Free Software               //
  22 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA //
  23 //                                                                           //
  24 // $Revision:: 224                                                          $//
  25 // $Date:: 2008-05-16 19:58:30 +0200 (Fri, 16 May 2008)                     $//
  26 ///////////////////////////////////////////////////////////////////////////////
  27
  28 #ifndef __SISCONE_H__
  29 #define __SISCONE_H__
  30
  31 #include "protocones.h"
  32 #include "split_merge.h"
  33
  34 namespace siscone{
  35
  36 /**
  37  * \class Csiscone
  38  * final class: gather everything to compute the jet contents.
  39  *
  40  * This is the class user should use.
  41  * It computes the jet contents of a list of particles
  42  * given a cone radius and a threshold for splitting/merging.
  43  *
  44  * After the call to 'perform', the vector jets is filled with
  45  * the jets found. the 'contents' field of each jets contains
  46  * the indices of the particles included in that jet.
  47  */
  48 class Csiscone : public Cstable_cones, public Csplit_merge{
  49  public:
  50   /// default ctor
  51   Csiscone();
  52
  53   /// default dtor
  54   ~Csiscone();
  55
  56   /**
  57    * compute the jets from a given particle set.
  58    * We are doing multiple passes such pass n_pass looks for jets among
  59    * all particles not put into jets during previous passes.
  60    * By default the number of passes is infinite (0).
  61    * \param _particles   list of particles
  62    * \param _radius      cone radius
  63    * \param _f           shared energy threshold for splitting&merging
  64    * \param _n_pass_max  maximum number of passes (0=full search)
  65    * \param _ptmin       minimum pT of the protojets
  66    * \param _split_merge_scale    the scale choice for the split-merge procedure
  67    *        NOTE: SM_pt leads to IR unsafety for some events with momentum conservation.
  68    *              SM_Et is IR safe but not boost invariant and not implemented(!)
  69    *              SM_mt is IR safe for hadronic events, but not for decays of two
  70    *                    back-to-back particles of identical mass
  71    *              SM_pttilde
  72    *                    is always IR safe, and also boost invariant (default)
  73    *
  74    * \return the number of jets found.
  75    */
  76   int compute_jets(std::vector<Cmomentum> &_particles, double _radius, double _f,
  77                    int _n_pass_max=0, double _ptmin=0.0,
  78                    Esplit_merge_scale _split_merge_scale=SM_pttilde);
  79
  80   /**
  81    * recompute the jets with a different overlap parameter.
  82    * we use the same particles and R as in the preceeding call.
  83    * \param _f           shared energy threshold for splitting&merging
  84    * \param _ptmin       minimum pT of the protojets
  85    * \param _split_merge_scale    the scale choice for the split-merge procedure
  86    *                                           split--merge variable
  87    *        NOTE: using pt leads to IR unsafety for some events with momentum
  88    *              conservation. So we strongly advise not to change the default
  89    *              value.
  90    * \return the number of jets found, -1 if recomputation not allowed.
  91    */
  92   int recompute_jets(double _f, double _ptmin = 0.0,
  93                      Esplit_merge_scale _split_merge_scale=SM_pttilde);
  94
  95   /// list of protocones found pass-by-pass
  96   std::vector<std::vector<Cmomentum> > protocones_list;
  97
  98   // random number initialisation
  99   static bool init_done;      ///< check random generator initialisation
 100
 101 #ifdef DEBUG_STABLE_CONES
 102   int nb_hash_cones_total, nb_hash_occupied_total;
 103 #endif
 104
 105  private:
 106   bool rerun_allowed;         ///< is recompute_jets allowed ?
 107 };
 108
 109
 110 // finally, a bunch of functions to access to
 111 // basic information (package name, version)
 112 //---------------------------------------------
 113
 114 /**
 115  * return SISCone package name.
 116  * This is nothing but "SISCone", it is a replacement to the
 117  * PACKAGE_NAME string defined in config.h and which is not
 118  * public by default.
 119  * \return the SISCone name as a string
 120  */
 121 std::string siscone_package_name();
 122
 123 /**
 124  * return SISCone version number.
 125  * \return a string of the form "X.Y.Z" with possible additional tag
 126  *         (alpha, beta, devel) to mention stability status
 127  */
 128 std::string siscone_version();
 129
 130 }
 131 #endif