FastJet 3.0.2
PseudoJetStructureBase.hh
00001 //STARTHEADER
00002 // $Id: PseudoJetStructureBase.hh 2670 2011-11-11 17:01:06Z salam $
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 
00030 #ifndef __FASTJET_PSEUDOJET_STRUCTURE_BASE_HH__
00031 #define __FASTJET_PSEUDOJET_STRUCTURE_BASE_HH__
00032 
00033 #include "fastjet/internal/base.hh"
00034 
00035 #include <vector>
00036 #include <string>
00037 
00038 FASTJET_BEGIN_NAMESPACE      // defined in fastjet/internal/base.hh
00039 
00040 class PseudoJet;
00041 class ClusterSequence;
00042 class ClusterSequenceAreaBase;
00043 
00044 /// @ingroup extra_info
00045 /// \class PseudoJetStructureBase
00046 ///
00047 /// Contains any information related to the clustering that should be
00048 /// directly accessible to PseudoJet.
00049 ///
00050 /// By default, this class implements basic access to the
00051 /// ClusterSequence related to a PseudoJet (like its constituents or
00052 /// its area). But it can be overloaded in order e.g. to give access
00053 /// to the jet substructure.
00054 ///
00055 class PseudoJetStructureBase{
00056 public:
00057   /// default ctor
00058   PseudoJetStructureBase(){};
00059 
00060   /// default (virtual) dtor
00061   virtual ~PseudoJetStructureBase(){};
00062 
00063   /// description
00064   virtual std::string description() const{ return "PseudoJet with an unknown structure"; }
00065 
00066   //-------------------------------------------------------------
00067   /// @name Direct access to the associated ClusterSequence object.
00068   ///
00069   /// Get access to the associated ClusterSequence (if any)
00070   //\{
00071   //-------------------------------------------------------------
00072   /// returns true if there is an associated ClusterSequence
00073   virtual bool has_associated_cluster_sequence() const { return false;}
00074 
00075   /// get a (const) pointer to the parent ClusterSequence (NULL if
00076   /// inexistent)
00077   virtual const ClusterSequence* associated_cluster_sequence() const;
00078   
00079   /// returns true if this PseudoJet has an associated and still
00080   /// valid ClusterSequence.
00081   virtual bool has_valid_cluster_sequence() const {return false;}
00082 
00083   /// if the jet has a valid associated cluster sequence then return a
00084   /// pointer to it; otherwise throw an error
00085   virtual const ClusterSequence * validated_cs() const;
00086 
00087   /// if the jet has valid area information then return a pointer to
00088   /// the associated ClusterSequenceAreaBase object; otherwise throw an error
00089   virtual const ClusterSequenceAreaBase * validated_csab() const;
00090 
00091   //\}
00092 
00093   //-------------------------------------------------------------
00094   /// @name Methods for access to information about jet structure
00095   ///
00096   /// These allow access to jet constituents, and other jet
00097   /// subtructure information. They only work if the jet is associated
00098   /// with a ClusterSequence.
00099   //-------------------------------------------------------------
00100   //\{
00101 
00102   /// check if it has been recombined with another PseudoJet in which
00103   /// case, return its partner through the argument. Otherwise,
00104   /// 'partner' is set to 0.
00105   ///
00106   /// By default, throws an Error
00107   virtual bool has_partner(const PseudoJet &reference, PseudoJet &partner) const;
00108 
00109   /// check if it has been recombined with another PseudoJet in which
00110   /// case, return its child through the argument. Otherwise, 'child'
00111   /// is set to 0.
00112   /// 
00113   /// By default, throws an Error
00114   virtual bool has_child(const PseudoJet &reference, PseudoJet &child) const;
00115 
00116   /// check if it is the product of a recombination, in which case
00117   /// return the 2 parents through the 'parent1' and 'parent2'
00118   /// arguments. Otherwise, set these to 0.
00119   ///
00120   /// By default, throws an Error
00121   virtual bool has_parents(const PseudoJet &reference, PseudoJet &parent1, PseudoJet &parent2) const;
00122 
00123   /// check if the reference PseudoJet is contained the second one
00124   /// passed as argument.
00125   ///
00126   /// By default, throws an Error
00127   virtual bool object_in_jet(const PseudoJet &reference, const PseudoJet &jet) const;
00128 
00129 
00130   /// return true if the structure supports constituents. 
00131   ///
00132   /// false by default
00133   virtual bool has_constituents() const {return false;}
00134 
00135   /// retrieve the constituents. 
00136   ///
00137   /// By default, throws an Error
00138   virtual std::vector<PseudoJet> constituents(const PseudoJet &reference) const;
00139 
00140 
00141   /// return true if the structure supports exclusive_subjets. 
00142   virtual bool has_exclusive_subjets() const {return false;}
00143 
00144   /// return a vector of all subjets of the current jet (in the sense
00145   /// of the exclusive algorithm) that would be obtained when running
00146   /// the algorithm with the given dcut. 
00147   ///
00148   /// Time taken is O(m ln m), where m is the number of subjets that
00149   /// are found. If m gets to be of order of the total number of
00150   /// constituents in the jet, this could be substantially slower than
00151   /// just getting that list of constituents.
00152   ///
00153   /// By default, throws an Error
00154   virtual std::vector<PseudoJet> exclusive_subjets(const PseudoJet &reference, const double & dcut) const;
00155 
00156   /// return the size of exclusive_subjets(...); still n ln n with same
00157   /// coefficient, but marginally more efficient than manually taking
00158   /// exclusive_subjets.size()
00159   ///
00160   /// By default, throws an Error
00161   virtual int n_exclusive_subjets(const PseudoJet &reference, const double & dcut) const;
00162 
00163   /// return the list of subjets obtained by unclustering the supplied
00164   /// jet down to nsub subjets (or all constituents if there are fewer
00165   /// than nsub).
00166   ///
00167   /// By default, throws an Error
00168   virtual std::vector<PseudoJet> exclusive_subjets_up_to (const PseudoJet &reference, int nsub) const;
00169 
00170   /// return the dij that was present in the merging nsub+1 -> nsub 
00171   /// subjets inside this jet.
00172   ///
00173   /// By default, throws an Error
00174   virtual double exclusive_subdmerge(const PseudoJet &reference, int nsub) const;
00175 
00176   /// return the maximum dij that occurred in the whole event at the
00177   /// stage that the nsub+1 -> nsub merge of subjets occurred inside 
00178   /// this jet.
00179   ///
00180   /// By default, throws an Error
00181   virtual double exclusive_subdmerge_max(const PseudoJet &reference, int nsub) const;
00182 
00183 
00184   //-------------------------------------------------------------------
00185   // information related to the pieces of the jet
00186   //-------------------------------------------------------------------
00187   /// return true if the structure supports pieces. 
00188   ///
00189   /// false by default
00190   /// NB: "reference" is commented to avoid unused-variable compiler warnings
00191   virtual bool has_pieces(const PseudoJet & /* reference */) const {
00192     return false;}
00193 
00194   /// retrieve the pieces building the jet. 
00195   ///
00196   /// By default, throws an Error.
00197   /// NB: "reference" is commented to avoid unused-variable compiler warnings
00198   virtual std::vector<PseudoJet> pieces(const PseudoJet & /* reference */
00199                                         ) const;
00200 
00201 
00202   // the following ones require a computation of the area in the
00203   // parent ClusterSequence (See ClusterSequenceAreaBase for details)
00204   //------------------------------------------------------------------
00205 
00206   /// check if it has a defined area
00207   ///
00208   /// false by default
00209   virtual bool has_area() const {return false;}
00210 
00211   /// return the jet (scalar) area.
00212   ///
00213   /// By default, throws an Error
00214   virtual double area(const PseudoJet &reference) const;
00215 
00216   /// return the error (uncertainty) associated with the determination
00217   /// of the area of this jet.
00218   ///
00219   /// By default, throws an Error
00220   virtual double area_error(const PseudoJet &reference) const;
00221 
00222   /// return the jet 4-vector area.
00223   ///
00224   /// By default, throws an Error
00225   virtual PseudoJet area_4vector(const PseudoJet &reference) const;
00226 
00227   /// true if this jet is made exclusively of ghosts.
00228   ///
00229   /// By default, throws an Error
00230   virtual bool is_pure_ghost(const PseudoJet &reference) const;
00231 
00232   //\} --- end of jet structure -------------------------------------
00233 };
00234 
00235 FASTJET_END_NAMESPACE
00236 
00237 #endif  //  __FASTJET_PSEUDOJET_STRUCTURE_BASE_HH__
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends