FastJet  3.3.0
PseudoJetStructureBase.hh
1 #ifndef __FASTJET_PSEUDOJET_STRUCTURE_BASE_HH__
2 #define __FASTJET_PSEUDOJET_STRUCTURE_BASE_HH__
3 
4 //FJSTARTHEADER
5 // $Id: PseudoJetStructureBase.hh 3433 2014-07-23 08:17:03Z salam $
6 //
7 // Copyright (c) 2005-2014, Matteo Cacciari, Gavin P. Salam and Gregory Soyez
8 //
9 //----------------------------------------------------------------------
10 // This file is part of FastJet.
11 //
12 // FastJet is free software; you can redistribute it and/or modify
13 // it under the terms of the GNU General Public License as published by
14 // the Free Software Foundation; either version 2 of the License, or
15 // (at your option) any later version.
16 //
17 // The algorithms that underlie FastJet have required considerable
18 // development. They are described in the original FastJet paper,
19 // hep-ph/0512210 and in the manual, arXiv:1111.6097. If you use
20 // FastJet as part of work towards a scientific publication, please
21 // quote the version you use and include a citation to the manual and
22 // optionally also to hep-ph/0512210.
23 //
24 // FastJet is distributed in the hope that it will be useful,
25 // but WITHOUT ANY WARRANTY; without even the implied warranty of
26 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
27 // GNU General Public License for more details.
28 //
29 // You should have received a copy of the GNU General Public License
30 // along with FastJet. If not, see <http://www.gnu.org/licenses/>.
31 //----------------------------------------------------------------------
32 //FJENDHEADER
33 
34 
35 #include "fastjet/internal/base.hh"
36 
37 #include <vector>
38 #include <string>
39 
40 FASTJET_BEGIN_NAMESPACE // defined in fastjet/internal/base.hh
41 
42 class PseudoJet;
43 class ClusterSequence;
44 #ifndef __FJCORE__
45 class ClusterSequenceAreaBase;
46 #endif // __FJCORE__
47 
48 /// @ingroup extra_info
49 /// \class PseudoJetStructureBase
50 ///
51 /// Contains any information related to the clustering that should be
52 /// directly accessible to PseudoJet.
53 ///
54 /// By default, this class implements basic access to the
55 /// ClusterSequence related to a PseudoJet (like its constituents or
56 /// its area). But it can be overloaded in order e.g. to give access
57 /// to the jet substructure.
58 ///
60 public:
61  /// default ctor
63 
64  /// default (virtual) dtor
66 
67  /// description
68  virtual std::string description() const{ return "PseudoJet with an unknown structure"; }
69 
70  //-------------------------------------------------------------
71  /// @name Direct access to the associated ClusterSequence object.
72  ///
73  /// Get access to the associated ClusterSequence (if any)
74  //\{
75  //-------------------------------------------------------------
76  /// returns true if there is an associated ClusterSequence
77  virtual bool has_associated_cluster_sequence() const { return false;}
78 
79  /// get a (const) pointer to the parent ClusterSequence (NULL if
80  /// inexistent)
81  virtual const ClusterSequence* associated_cluster_sequence() const;
82 
83  /// returns true if this PseudoJet has an associated and still
84  /// valid ClusterSequence.
85  virtual bool has_valid_cluster_sequence() const {return false;}
86 
87  /// if the jet has a valid associated cluster sequence then return a
88  /// pointer to it; otherwise throw an error
89  virtual const ClusterSequence * validated_cs() const;
90 
91 #ifndef __FJCORE__
92  /// if the jet has valid area information then return a pointer to
93  /// the associated ClusterSequenceAreaBase object; otherwise throw an error
94  virtual const ClusterSequenceAreaBase * validated_csab() const;
95 #endif
96 
97  //\}
98 
99  //-------------------------------------------------------------
100  /// @name Methods for access to information about jet structure
101  ///
102  /// These allow access to jet constituents, and other jet
103  /// subtructure information. They only work if the jet is associated
104  /// with a ClusterSequence.
105  //-------------------------------------------------------------
106  //\{
107 
108  /// check if it has been recombined with another PseudoJet in which
109  /// case, return its partner through the argument. Otherwise,
110  /// 'partner' is set to 0.
111  ///
112  /// By default, throws an Error
113  virtual bool has_partner(const PseudoJet &reference, PseudoJet &partner) const;
114 
115  /// check if it has been recombined with another PseudoJet in which
116  /// case, return its child through the argument. Otherwise, 'child'
117  /// is set to 0.
118  ///
119  /// By default, throws an Error
120  virtual bool has_child(const PseudoJet &reference, PseudoJet &child) const;
121 
122  /// check if it is the product of a recombination, in which case
123  /// return the 2 parents through the 'parent1' and 'parent2'
124  /// arguments. Otherwise, set these to 0.
125  ///
126  /// By default, throws an Error
127  virtual bool has_parents(const PseudoJet &reference, PseudoJet &parent1, PseudoJet &parent2) const;
128 
129  /// check if the reference PseudoJet is contained the second one
130  /// passed as argument.
131  ///
132  /// By default, throws an Error
133  virtual bool object_in_jet(const PseudoJet &reference, const PseudoJet &jet) const;
134 
135 
136  /// return true if the structure supports constituents.
137  ///
138  /// false by default
139  virtual bool has_constituents() const {return false;}
140 
141  /// retrieve the constituents.
142  ///
143  /// By default, throws an Error
144  virtual std::vector<PseudoJet> constituents(const PseudoJet &reference) const;
145 
146 
147  /// return true if the structure supports exclusive_subjets.
148  virtual bool has_exclusive_subjets() const {return false;}
149 
150  /// return a vector of all subjets of the current jet (in the sense
151  /// of the exclusive algorithm) that would be obtained when running
152  /// the algorithm with the given dcut.
153  ///
154  /// Time taken is O(m ln m), where m is the number of subjets that
155  /// are found. If m gets to be of order of the total number of
156  /// constituents in the jet, this could be substantially slower than
157  /// just getting that list of constituents.
158  ///
159  /// By default, throws an Error
160  ///
161  /// Note: in a future major release of FastJet (4 or higher),
162  /// "const double & dcut" may be replaced with "const double dcut",
163  /// requiring a modification of derived classes that overload
164  /// this function.
165  virtual std::vector<PseudoJet> exclusive_subjets(const PseudoJet &reference, const double & dcut) const;
166 
167  /// return the size of exclusive_subjets(...); still n ln n with same
168  /// coefficient, but marginally more efficient than manually taking
169  /// exclusive_subjets.size()
170  ///
171  /// By default, throws an Error
172  ///
173  /// Note: in a future major release of FastJet (4 or higher),
174  /// "const double & dcut" may be replaced with "const double dcut",
175  /// requiring a modification of derived classes that overload
176  /// this function.
177  virtual int n_exclusive_subjets(const PseudoJet &reference, const double & dcut) const;
178 
179  /// return the list of subjets obtained by unclustering the supplied
180  /// jet down to nsub subjets (or all constituents if there are fewer
181  /// than nsub).
182  ///
183  /// By default, throws an Error
184  virtual std::vector<PseudoJet> exclusive_subjets_up_to (const PseudoJet &reference, int nsub) const;
185 
186  /// return the dij that was present in the merging nsub+1 -> nsub
187  /// subjets inside this jet.
188  ///
189  /// By default, throws an Error
190  virtual double exclusive_subdmerge(const PseudoJet &reference, int nsub) const;
191 
192  /// return the maximum dij that occurred in the whole event at the
193  /// stage that the nsub+1 -> nsub merge of subjets occurred inside
194  /// this jet.
195  ///
196  /// By default, throws an Error
197  virtual double exclusive_subdmerge_max(const PseudoJet &reference, int nsub) const;
198 
199 
200  //-------------------------------------------------------------------
201  // information related to the pieces of the jet
202  //-------------------------------------------------------------------
203  /// return true if the structure supports pieces.
204  ///
205  /// false by default
206  /// NB: "reference" is commented to avoid unused-variable compiler warnings
207  virtual bool has_pieces(const PseudoJet & /* reference */) const {
208  return false;}
209 
210  /// retrieve the pieces building the jet.
211  ///
212  /// By default, throws an Error.
213  /// NB: "reference" is commented to avoid unused-variable compiler warnings
214  virtual std::vector<PseudoJet> pieces(const PseudoJet & /* reference */
215  ) const;
216 
217 
218  // the following ones require a computation of the area in the
219  // parent ClusterSequence (See ClusterSequenceAreaBase for details)
220  //------------------------------------------------------------------
221 #ifndef __FJCORE__
222 
223  /// check if it has a defined area
224  ///
225  /// false by default
226  virtual bool has_area() const {return false;}
227 
228  /// return the jet (scalar) area.
229  ///
230  /// By default, throws an Error
231  virtual double area(const PseudoJet &reference) const;
232 
233  /// return the error (uncertainty) associated with the determination
234  /// of the area of this jet.
235  ///
236  /// By default, throws an Error
237  virtual double area_error(const PseudoJet &reference) const;
238 
239  /// return the jet 4-vector area.
240  ///
241  /// By default, throws an Error
242  virtual PseudoJet area_4vector(const PseudoJet &reference) const;
243 
244  /// true if this jet is made exclusively of ghosts.
245  ///
246  /// By default, throws an Error
247  virtual bool is_pure_ghost(const PseudoJet &reference) const;
248 
249 #endif // __FJCORE__
250  //\} --- end of jet structure -------------------------------------
251 };
252 
253 FASTJET_END_NAMESPACE
254 
255 #endif // __FASTJET_PSEUDOJET_STRUCTURE_BASE_HH__
virtual bool has_valid_cluster_sequence() const
returns true if this PseudoJet has an associated and still valid ClusterSequence. ...
virtual bool has_associated_cluster_sequence() const
returns true if there is an associated ClusterSequence
deals with clustering
virtual bool has_area() const
check if it has a defined area
Contains any information related to the clustering that should be directly accessible to PseudoJet...
virtual bool has_pieces(const PseudoJet &) const
return true if the structure supports pieces.
base class that sets interface for extensions of ClusterSequence that provide information about the a...
virtual ~PseudoJetStructureBase()
default (virtual) dtor
virtual std::string description() const
description
virtual bool has_exclusive_subjets() const
return true if the structure supports exclusive_subjets.
Class to contain pseudojets, including minimal information of use to jet-clustering routines...
Definition: PseudoJet.hh:67
virtual bool has_constituents() const
return true if the structure supports constituents.