FastJet  3.0.3
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
PseudoJetStructureBase.hh
1 //STARTHEADER
2 // $Id: PseudoJetStructureBase.hh 2670 2011-11-11 17:01:06Z salam $
3 //
4 // Copyright (c) 2005-2011, Matteo Cacciari, Gavin P. Salam and Gregory Soyez
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, see <http://www.gnu.org/licenses/>.
26 //----------------------------------------------------------------------
27 //ENDHEADER
28 
29 
30 #ifndef __FASTJET_PSEUDOJET_STRUCTURE_BASE_HH__
31 #define __FASTJET_PSEUDOJET_STRUCTURE_BASE_HH__
32 
33 #include "fastjet/internal/base.hh"
34 
35 #include <vector>
36 #include <string>
37 
38 FASTJET_BEGIN_NAMESPACE // defined in fastjet/internal/base.hh
39 
40 class PseudoJet;
41 class ClusterSequence;
42 class ClusterSequenceAreaBase;
43 
44 /// @ingroup extra_info
45 /// \class PseudoJetStructureBase
46 ///
47 /// Contains any information related to the clustering that should be
48 /// directly accessible to PseudoJet.
49 ///
50 /// By default, this class implements basic access to the
51 /// ClusterSequence related to a PseudoJet (like its constituents or
52 /// its area). But it can be overloaded in order e.g. to give access
53 /// to the jet substructure.
54 ///
56 public:
57  /// default ctor
59 
60  /// default (virtual) dtor
62 
63  /// description
64  virtual std::string description() const{ return "PseudoJet with an unknown structure"; }
65 
66  //-------------------------------------------------------------
67  /// @name Direct access to the associated ClusterSequence object.
68  ///
69  /// Get access to the associated ClusterSequence (if any)
70  //\{
71  //-------------------------------------------------------------
72  /// returns true if there is an associated ClusterSequence
73  virtual bool has_associated_cluster_sequence() const { return false;}
74 
75  /// get a (const) pointer to the parent ClusterSequence (NULL if
76  /// inexistent)
77  virtual const ClusterSequence* associated_cluster_sequence() const;
78 
79  /// returns true if this PseudoJet has an associated and still
80  /// valid ClusterSequence.
81  virtual bool has_valid_cluster_sequence() const {return false;}
82 
83  /// if the jet has a valid associated cluster sequence then return a
84  /// pointer to it; otherwise throw an error
85  virtual const ClusterSequence * validated_cs() const;
86 
87  /// if the jet has valid area information then return a pointer to
88  /// the associated ClusterSequenceAreaBase object; otherwise throw an error
89  virtual const ClusterSequenceAreaBase * validated_csab() const;
90 
91  //\}
92 
93  //-------------------------------------------------------------
94  /// @name Methods for access to information about jet structure
95  ///
96  /// These allow access to jet constituents, and other jet
97  /// subtructure information. They only work if the jet is associated
98  /// with a ClusterSequence.
99  //-------------------------------------------------------------
100  //\{
101 
102  /// check if it has been recombined with another PseudoJet in which
103  /// case, return its partner through the argument. Otherwise,
104  /// 'partner' is set to 0.
105  ///
106  /// By default, throws an Error
107  virtual bool has_partner(const PseudoJet &reference, PseudoJet &partner) const;
108 
109  /// check if it has been recombined with another PseudoJet in which
110  /// case, return its child through the argument. Otherwise, 'child'
111  /// is set to 0.
112  ///
113  /// By default, throws an Error
114  virtual bool has_child(const PseudoJet &reference, PseudoJet &child) const;
115 
116  /// check if it is the product of a recombination, in which case
117  /// return the 2 parents through the 'parent1' and 'parent2'
118  /// arguments. Otherwise, set these to 0.
119  ///
120  /// By default, throws an Error
121  virtual bool has_parents(const PseudoJet &reference, PseudoJet &parent1, PseudoJet &parent2) const;
122 
123  /// check if the reference PseudoJet is contained the second one
124  /// passed as argument.
125  ///
126  /// By default, throws an Error
127  virtual bool object_in_jet(const PseudoJet &reference, const PseudoJet &jet) const;
128 
129 
130  /// return true if the structure supports constituents.
131  ///
132  /// false by default
133  virtual bool has_constituents() const {return false;}
134 
135  /// retrieve the constituents.
136  ///
137  /// By default, throws an Error
138  virtual std::vector<PseudoJet> constituents(const PseudoJet &reference) const;
139 
140 
141  /// return true if the structure supports exclusive_subjets.
142  virtual bool has_exclusive_subjets() const {return false;}
143 
144  /// return a vector of all subjets of the current jet (in the sense
145  /// of the exclusive algorithm) that would be obtained when running
146  /// the algorithm with the given dcut.
147  ///
148  /// Time taken is O(m ln m), where m is the number of subjets that
149  /// are found. If m gets to be of order of the total number of
150  /// constituents in the jet, this could be substantially slower than
151  /// just getting that list of constituents.
152  ///
153  /// By default, throws an Error
154  virtual std::vector<PseudoJet> exclusive_subjets(const PseudoJet &reference, const double & dcut) const;
155 
156  /// return the size of exclusive_subjets(...); still n ln n with same
157  /// coefficient, but marginally more efficient than manually taking
158  /// exclusive_subjets.size()
159  ///
160  /// By default, throws an Error
161  virtual int n_exclusive_subjets(const PseudoJet &reference, const double & dcut) const;
162 
163  /// return the list of subjets obtained by unclustering the supplied
164  /// jet down to nsub subjets (or all constituents if there are fewer
165  /// than nsub).
166  ///
167  /// By default, throws an Error
168  virtual std::vector<PseudoJet> exclusive_subjets_up_to (const PseudoJet &reference, int nsub) const;
169 
170  /// return the dij that was present in the merging nsub+1 -> nsub
171  /// subjets inside this jet.
172  ///
173  /// By default, throws an Error
174  virtual double exclusive_subdmerge(const PseudoJet &reference, int nsub) const;
175 
176  /// return the maximum dij that occurred in the whole event at the
177  /// stage that the nsub+1 -> nsub merge of subjets occurred inside
178  /// this jet.
179  ///
180  /// By default, throws an Error
181  virtual double exclusive_subdmerge_max(const PseudoJet &reference, int nsub) const;
182 
183 
184  //-------------------------------------------------------------------
185  // information related to the pieces of the jet
186  //-------------------------------------------------------------------
187  /// return true if the structure supports pieces.
188  ///
189  /// false by default
190  /// NB: "reference" is commented to avoid unused-variable compiler warnings
191  virtual bool has_pieces(const PseudoJet & /* reference */) const {
192  return false;}
193 
194  /// retrieve the pieces building the jet.
195  ///
196  /// By default, throws an Error.
197  /// NB: "reference" is commented to avoid unused-variable compiler warnings
198  virtual std::vector<PseudoJet> pieces(const PseudoJet & /* reference */
199  ) const;
200 
201 
202  // the following ones require a computation of the area in the
203  // parent ClusterSequence (See ClusterSequenceAreaBase for details)
204  //------------------------------------------------------------------
205 
206  /// check if it has a defined area
207  ///
208  /// false by default
209  virtual bool has_area() const {return false;}
210 
211  /// return the jet (scalar) area.
212  ///
213  /// By default, throws an Error
214  virtual double area(const PseudoJet &reference) const;
215 
216  /// return the error (uncertainty) associated with the determination
217  /// of the area of this jet.
218  ///
219  /// By default, throws an Error
220  virtual double area_error(const PseudoJet &reference) const;
221 
222  /// return the jet 4-vector area.
223  ///
224  /// By default, throws an Error
225  virtual PseudoJet area_4vector(const PseudoJet &reference) const;
226 
227  /// true if this jet is made exclusively of ghosts.
228  ///
229  /// By default, throws an Error
230  virtual bool is_pure_ghost(const PseudoJet &reference) const;
231 
232  //\} --- end of jet structure -------------------------------------
233 };
234 
235 FASTJET_END_NAMESPACE
236 
237 #endif // __FASTJET_PSEUDOJET_STRUCTURE_BASE_HH__