FastJet 3.0.2
ClusterSequenceStructure.hh
00001 //STARTHEADER
00002 // $Id: ClusterSequenceStructure.hh 2577 2011-09-13 15:11:38Z 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_CLUSTER_SEQUENCE_STRUCTURE_HH__
00031 #define __FASTJET_CLUSTER_SEQUENCE_STRUCTURE_HH__
00032 
00033 #include "fastjet/internal/base.hh"
00034 #include "fastjet/SharedPtr.hh"
00035 #include "fastjet/PseudoJetStructureBase.hh"
00036 
00037 #include <vector>
00038 
00039 FASTJET_BEGIN_NAMESPACE      // defined in fastjet/internal/base.hh
00040 
00041 /// @ingroup extra_info
00042 /// \class ClusterSequenceStructure
00043 ///
00044 /// Contains any information related to the clustering that should be
00045 /// directly accessible to PseudoJet.
00046 ///
00047 /// By default, this class implements basic access to the
00048 /// ClusterSequence related to a PseudoJet (like its constituents or
00049 /// its area). But it can be overloaded in order e.g. to give access
00050 /// to the jet substructure.
00051 ///
00052 // Design question: Do we only put the methods that can be overloaded
00053 // or do we put everything a PJ can have access to? I think both cost
00054 // the same number of indirections. The first option limits the amount
00055 // of coding and maybe has a clearer structure. The second is more
00056 // consistent (everything related to the same thing is at the same
00057 // place) and gives better access for derived classes. We'll go for
00058 // the second option.
00059 class ClusterSequenceStructure : public PseudoJetStructureBase{
00060 public:
00061   /// default ctor
00062   ClusterSequenceStructure() : _associated_cs(NULL){}
00063 
00064   /// ctor with initialisation to a given ClusterSequence
00065   /// 
00066   /// In principle, this is reserved for initialisation by the parent
00067   /// ClusterSequence
00068   ClusterSequenceStructure(const ClusterSequence *cs){
00069     set_associated_cs(cs);
00070   };
00071 
00072   /// default (virtual) dtor
00073   virtual ~ClusterSequenceStructure();
00074 
00075   /// description
00076   virtual std::string description() const{ return "PseudoJet with an associated ClusterSequence"; }
00077 
00078   //-------------------------------------------------------------
00079   /// @name Direct access to the associated ClusterSequence object.
00080   ///
00081   /// Get access to the associated ClusterSequence (if any)
00082   //\{
00083   //-------------------------------------------------------------
00084   /// returns true if there is an associated ClusterSequence
00085   virtual bool has_associated_cluster_sequence() const{ return true;}
00086 
00087   /// get a (const) pointer to the parent ClusterSequence (NULL if
00088   /// inexistent)
00089   virtual const ClusterSequence* associated_cluster_sequence() const;
00090   
00091   /// returns true if there is a valid associated ClusterSequence
00092   virtual bool has_valid_cluster_sequence() const;
00093 
00094   /// if the jet has a valid associated cluster sequence then return a
00095   /// pointer to it; otherwise throw an error
00096   virtual const ClusterSequence * validated_cs() const;
00097 
00098   /// if the jet has valid area information then return a pointer to
00099   /// the associated ClusterSequenceAreaBase object; otherwise throw an error
00100   virtual const ClusterSequenceAreaBase * validated_csab() const;
00101 
00102   /// set the associated csw
00103   virtual void set_associated_cs(const ClusterSequence * new_cs){
00104     _associated_cs = new_cs;
00105   }
00106   //\}
00107 
00108   //-------------------------------------------------------------
00109   /// @name Methods for access to information about jet structure
00110   ///
00111   /// These allow access to jet constituents, and other jet
00112   /// subtructure information. They only work if the jet is associated
00113   /// with a ClusterSequence.
00114   //-------------------------------------------------------------
00115   //\{
00116 
00117   /// check if it has been recombined with another PseudoJet in which
00118   /// case, return its partner through the argument. Otherwise,
00119   /// 'partner' is set to 0.
00120   ///
00121   /// an Error is thrown if this PseudoJet has no currently valid
00122   /// associated ClusterSequence
00123   virtual bool has_partner(const PseudoJet &reference, PseudoJet &partner) const;
00124 
00125   /// check if it has been recombined with another PseudoJet in which
00126   /// case, return its child through the argument. Otherwise, 'child'
00127   /// is set to 0.
00128   /// 
00129   /// an Error is thrown if this PseudoJet has no currently valid
00130   /// associated ClusterSequence
00131   virtual bool has_child(const PseudoJet &reference, PseudoJet &child) const;
00132 
00133   /// check if it is the product of a recombination, in which case
00134   /// return the 2 parents through the 'parent1' and 'parent2'
00135   /// arguments. Otherwise, set these to 0.
00136   ///
00137   /// an Error is thrown if this PseudoJet has no currently valid
00138   /// associated ClusterSequence
00139   virtual bool has_parents(const PseudoJet &reference, PseudoJet &parent1, PseudoJet &parent2) const;
00140 
00141   /// check if the reference PseudoJet is contained in the second one
00142   /// passed as argument.
00143   ///
00144   /// an Error is thrown if this PseudoJet has no currently valid
00145   /// associated ClusterSequence
00146   ///
00147   /// false is returned if the 2 PseudoJet do not belong the same
00148   /// ClusterSequence
00149   virtual bool object_in_jet(const PseudoJet &reference, const PseudoJet &jet) const;
00150 
00151   /// return true if the structure supports constituents. 
00152   ///
00153   /// an Error is thrown if this PseudoJet has no currently valid
00154   /// associated ClusterSequence
00155   virtual bool has_constituents() const;
00156 
00157   /// retrieve the constituents. 
00158   ///
00159   /// an Error is thrown if this PseudoJet has no currently valid
00160   /// associated ClusterSequence
00161   virtual std::vector<PseudoJet> constituents(const PseudoJet &reference) const;
00162 
00163 
00164   /// return true if the structure supports exclusive_subjets. 
00165   ///
00166   /// an Error is thrown if this PseudoJet has no currently valid
00167   /// associated ClusterSequence
00168   virtual bool has_exclusive_subjets() const;
00169 
00170   /// return a vector of all subjets of the current jet (in the sense
00171   /// of the exclusive algorithm) that would be obtained when running
00172   /// the algorithm with the given dcut. 
00173   ///
00174   /// Time taken is O(m ln m), where m is the number of subjets that
00175   /// are found. If m gets to be of order of the total number of
00176   /// constituents in the jet, this could be substantially slower than
00177   /// just getting that list of constituents.
00178   ///
00179   /// an Error is thrown if this PseudoJet has no currently valid
00180   /// associated ClusterSequence
00181   virtual std::vector<PseudoJet> exclusive_subjets(const PseudoJet &reference, const double & dcut) const;
00182 
00183   /// return the size of exclusive_subjets(...); still n ln n with same
00184   /// coefficient, but marginally more efficient than manually taking
00185   /// exclusive_subjets.size()
00186   ///
00187   /// an Error is thrown if this PseudoJet has no currently valid
00188   /// associated ClusterSequence
00189   virtual int n_exclusive_subjets(const PseudoJet &reference, const double & dcut) const;
00190 
00191   /// return the list of subjets obtained by unclustering the supplied
00192   /// jet down to nsub subjets (or all constituents if there are fewer
00193   /// than nsub).
00194   ///
00195   /// requires nsub ln nsub time
00196   ///
00197   /// an Error is thrown if this PseudoJet has no currently valid
00198   /// associated ClusterSequence
00199   virtual std::vector<PseudoJet> exclusive_subjets_up_to (const PseudoJet &reference, int nsub) const;
00200 
00201   /// return the dij that was present in the merging nsub+1 -> nsub 
00202   /// subjets inside this jet.
00203   ///
00204   /// an Error is thrown if this PseudoJet has no currently valid
00205   /// associated ClusterSequence
00206   virtual double exclusive_subdmerge(const PseudoJet &reference, int nsub) const;
00207 
00208   /// return the maximum dij that occurred in the whole event at the
00209   /// stage that the nsub+1 -> nsub merge of subjets occurred inside 
00210   /// this jet.
00211   ///
00212   /// an Error is thrown if this PseudoJet has no currently valid
00213   /// associated ClusterSequence
00214   virtual double exclusive_subdmerge_max(const PseudoJet &reference, int nsub) const;
00215 
00216 
00217   //-------------------------------------------------------------------
00218   // information related to the pieces of the jet
00219   //-------------------------------------------------------------------
00220   /// by convention, a jet associated with a ClusterSequence will have
00221   /// its parents as pieces
00222   virtual bool has_pieces(const PseudoJet &reference) const;
00223 
00224   /// by convention, a jet associated with a ClusterSequence will have
00225   /// its parents as pieces
00226   ///
00227   /// if it has no parents, then there will only be a single piece:
00228   /// itself
00229   ///
00230   /// Note that to answer that question, we need to access the cluster
00231   /// sequence. If the cluster sequence has gone out of scope, an
00232   /// error will be thrown
00233   virtual std::vector<PseudoJet> pieces(const PseudoJet &reference) const;
00234 
00235 
00236   // the following ones require a computation of the area in the
00237   // parent ClusterSequence (See ClusterSequenceAreaBase for details)
00238   //------------------------------------------------------------------
00239 
00240   /// check if it has a defined area
00241   virtual bool has_area() const;
00242 
00243   /// return the jet (scalar) area.
00244   /// throws an Error if there is no support for area in the parent CS
00245   virtual double area(const PseudoJet &reference) const;
00246 
00247   /// return the error (uncertainty) associated with the determination
00248   /// of the area of this jet.
00249   /// throws an Error if there is no support for area in the parent CS
00250   virtual double area_error(const PseudoJet &reference) const;
00251 
00252   /// return the jet 4-vector area.
00253   /// throws an Error if there is no support for area in the parent CS
00254   virtual PseudoJet area_4vector(const PseudoJet &reference) const;
00255 
00256   /// true if this jet is made exclusively of ghosts.
00257   /// throws an Error if there is no support for area in the parent CS
00258   virtual bool is_pure_ghost(const PseudoJet &reference) const;
00259 
00260   //\} --- end of jet structure -------------------------------------
00261 
00262 protected:
00263   const ClusterSequence *_associated_cs;
00264 };
00265 
00266 FASTJET_END_NAMESPACE
00267 
00268 #endif  //  __FASTJET_CLUSTER_SEQUENCE_STRUCTURE_HH__
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends