FastJet  3.0.6
WrappedStructure.hh
1 //STARTHEADER
2 // $Id: WrappedStructure.hh 2577 2011-09-13 15:11:38Z 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_WRAPPED_STRUCTURE_HH__
31 #define __FASTJET_WRAPPED_STRUCTURE_HH__
32 
33 #include "fastjet/PseudoJetStructureBase.hh"
34 #include "fastjet/Error.hh"
35 
36 FASTJET_BEGIN_NAMESPACE // defined in fastjet/internal/base.hh
37 
38 /// @ingroup extra_info
39 /// \class WrappedStructure
40 ///
41 /// This wraps a (shared) pointer to an underlying structure
42 ///
43 /// The typical use-case is when a PseusoJet needs to share its
44 /// structure with another PseudoJet but also include extra
45 /// information in its structure. For the memory management to be
46 /// handled properly, it should hold a shared pointer to the shared
47 /// structure. This is what this class ensures. Deriving a structure
48 /// from this class would then allow for the implementation of the
49 /// extra features.
50 ///
52 public:
53  /// default ctor
54  /// the argument is the structure we need to wrap
56  : _structure(to_be_shared){
57  if (!_structure())
58  throw Error("Trying to construct a wrapped structure around an empty (NULL) structure");
59  }
60 
61  /// default (virtual) dtor
62  virtual ~WrappedStructure(){}
63 
64  /// description
65  virtual std::string description() const{
66  return "PseudoJet wrapping the structure ("+_structure->description()+")";
67  }
68 
69  //-------------------------------------------------------------
70  /// @name Direct access to the associated ClusterSequence object.
71  ///
72  /// Get access to the associated ClusterSequence (if any)
73  //\{
74  //-------------------------------------------------------------
75  /// returns true if there is an associated ClusterSequence
76  virtual bool has_associated_cluster_sequence() const {
77  return _structure->has_associated_cluster_sequence();
78  }
79 
80  /// get a (const) pointer to the parent ClusterSequence (NULL if
81  /// inexistent)
83  return _structure->associated_cluster_sequence();
84  }
85 
86  /// returns true if this PseudoJet has an associated and still
87  /// valid ClusterSequence.
88  virtual bool has_valid_cluster_sequence() const {
89  return _structure->has_valid_cluster_sequence();
90  }
91 
92  /// if the jet has a valid associated cluster sequence then return a
93  /// pointer to it; otherwise throw an error
94  virtual const ClusterSequence * validated_cs() const{
95  return _structure->validated_cs();
96  }
97 
98  /// if the jet has valid area information then return a pointer to
99  /// the associated ClusterSequenceAreaBase object; otherwise throw an error
100  virtual const ClusterSequenceAreaBase * validated_csab() const{
101  return _structure->validated_csab();
102  }
103 
104  //\}
105 
106  //-------------------------------------------------------------
107  /// @name Methods for access to information about jet structure
108  ///
109  /// These allow access to jet constituents, and other jet
110  /// subtructure information. They only work if the jet is associated
111  /// with a ClusterSequence.
112  //-------------------------------------------------------------
113  //\{
114 
115  /// check if it has been recombined with another PseudoJet in which
116  /// case, return its partner through the argument. Otherwise,
117  /// 'partner' is set to 0.
118  ///
119  /// By default, throws an Error
120  virtual bool has_partner(const PseudoJet &reference, PseudoJet &partner) const{
121  return _structure->has_partner(reference, partner);
122  }
123 
124  /// check if it has been recombined with another PseudoJet in which
125  /// case, return its child through the argument. Otherwise, 'child'
126  /// is set to 0.
127  ///
128  /// By default, throws an Error
129  virtual bool has_child(const PseudoJet &reference, PseudoJet &child) const{
130  return _structure->has_child(reference, child);
131  }
132 
133  /// check if it is the product of a recombination, in which case
134  /// return the 2 parents through the 'parent1' and 'parent2'
135  /// arguments. Otherwise, set these to 0.
136  ///
137  /// By default, throws an Error
138  virtual bool has_parents(const PseudoJet &reference, PseudoJet &parent1, PseudoJet &parent2) const{
139  return _structure->has_parents(reference, parent1, parent2);
140  }
141 
142  /// check if the reference PseudoJet is contained the second one
143  /// passed as argument.
144  ///
145  /// By default, throws an Error
146  virtual bool object_in_jet(const PseudoJet &reference, const PseudoJet &jet) const{
147  return _structure->object_in_jet(reference, jet);
148  }
149 
150 
151  /// return true if the structure supports constituents.
152  ///
153  /// false by default
154  virtual bool has_constituents() const {
155  return _structure->has_constituents();
156  }
157 
158  /// retrieve the constituents.
159  ///
160  /// By default, throws an Error
161  virtual std::vector<PseudoJet> constituents(const PseudoJet &reference) const{
162  return _structure->constituents(reference);
163  }
164 
165  /// return true if the structure supports exclusive_subjets.
166  virtual bool has_exclusive_subjets() const {
167  return _structure->has_exclusive_subjets();
168  }
169 
170  /// return a vector of all subjets of the current jet (in the sense
171  /// of the exclusive algorithm) that would be obtained when running
172  /// the algorithm with the given dcut.
173  ///
174  /// Time taken is O(m ln m), where m is the number of subjets that
175  /// are found. If m gets to be of order of the total number of
176  /// constituents in the jet, this could be substantially slower than
177  /// just getting that list of constituents.
178  ///
179  /// By default, throws an Error
180  virtual std::vector<PseudoJet> exclusive_subjets(const PseudoJet &reference, const double & dcut) const{
181  return _structure->exclusive_subjets(reference, dcut);
182  }
183 
184  /// return the size of exclusive_subjets(...); still n ln n with same
185  /// coefficient, but marginally more efficient than manually taking
186  /// exclusive_subjets.size()
187  ///
188  /// By default, throws an Error
189  virtual int n_exclusive_subjets(const PseudoJet &reference, const double & dcut) const{
190  return _structure->n_exclusive_subjets(reference, dcut);
191  }
192 
193  /// return the list of subjets obtained by unclustering the supplied
194  /// jet down to n subjets (or all constituents if there are fewer
195  /// than n).
196  ///
197  /// By default, throws an Error
198  virtual std::vector<PseudoJet> exclusive_subjets_up_to (const PseudoJet &reference, int nsub) const{
199  return _structure->exclusive_subjets_up_to (reference, nsub);
200  }
201 
202  /// return the dij that was present in the merging nsub+1 -> nsub
203  /// subjets inside this jet.
204  ///
205  /// By default, throws an Error
206  virtual double exclusive_subdmerge(const PseudoJet &reference, int nsub) const{
207  return _structure->exclusive_subdmerge(reference, nsub);
208  }
209 
210  /// return the maximum dij that occurred in the whole event at the
211  /// stage that the nsub+1 -> nsub merge of subjets occurred inside
212  /// this jet.
213  ///
214  /// By default, throws an Error
215  virtual double exclusive_subdmerge_max(const PseudoJet &reference, int nsub) const{
216  return _structure->exclusive_subdmerge_max(reference, nsub);
217  }
218 
219 
220  //-------------------------------------------------------------------
221  // information related to the pieces of the jet
222  //-------------------------------------------------------------------
223  /// return true if the structure supports pieces.
224  ///
225  /// false by default
226  virtual bool has_pieces(const PseudoJet &reference) const {
227  return _structure->has_pieces(reference);
228  }
229 
230  /// retrieve the pieces building the jet.
231  ///
232  /// By default, throws an Error
233  virtual std::vector<PseudoJet> pieces(const PseudoJet &reference) const{
234  return _structure->pieces(reference);
235  }
236 
237  // the following ones require a computation of the area in the
238  // parent ClusterSequence (See ClusterSequenceAreaBase for details)
239  //------------------------------------------------------------------
240 
241  /// check if it has a defined area
242  ///
243  /// false by default
244  virtual bool has_area() const {
245  return _structure->has_area();
246  }
247 
248  /// return the jet (scalar) area.
249  ///
250  /// By default, throws an Error
251  virtual double area(const PseudoJet &reference) const{
252  return _structure->area(reference);
253  }
254 
255  /// return the error (uncertainty) associated with the determination
256  /// of the area of this jet.
257  ///
258  /// By default, throws an Error
259  virtual double area_error(const PseudoJet &reference) const{
260  return _structure->area_error(reference);
261  }
262 
263  /// return the jet 4-vector area.
264  ///
265  /// By default, throws an Error
266  virtual PseudoJet area_4vector(const PseudoJet &reference) const{
267  return _structure->area_4vector(reference);
268  }
269 
270  /// true if this jet is made exclusively of ghosts.
271  ///
272  /// By default, throws an Error
273  virtual bool is_pure_ghost(const PseudoJet &reference) const{
274  return _structure->is_pure_ghost(reference);
275  }
276 
277  //\} --- end of jet structure -------------------------------------
278 
279 protected:
280  SharedPtr<PseudoJetStructureBase> _structure; ///< the wrapped structure
281 };
282 
283 FASTJET_END_NAMESPACE
284 
285 #endif // __FASTJET_PSEUDOJET_STRUCTURE_BASE_HH__
virtual bool has_constituents() const
return true if the structure supports constituents.
WrappedStructure(const SharedPtr< PseudoJetStructureBase > &to_be_shared)
default ctor the argument is the structure we need to wrap
virtual PseudoJet area_4vector() const
return the jet 4-vector area.
Definition: PseudoJet.cc:718
deals with clustering
virtual const ClusterSequence * associated_cluster_sequence() const
get a (const) pointer to the parent ClusterSequence (NULL if inexistent)
virtual std::vector< PseudoJet > pieces(const PseudoJet &reference) const
retrieve the pieces building the jet.
virtual bool is_pure_ghost(const PseudoJet &reference) const
true if this jet is made exclusively of ghosts.
virtual double exclusive_subdmerge(const PseudoJet &reference, int nsub) const
return the dij that was present in the merging nsub+1 -> nsub subjets inside this jet...
virtual ~WrappedStructure()
default (virtual) dtor
virtual double area(const PseudoJet &reference) const
return the jet (scalar) area.
virtual int n_exclusive_subjets(const PseudoJet &reference, const double &dcut) const
return the size of exclusive_subjets(...); still n ln n with same coefficient, but marginally more ef...
This wraps a (shared) pointer to an underlying structure.
virtual bool has_pieces(const PseudoJet &reference) const
return true if the structure supports pieces.
Contains any information related to the clustering that should be directly accessible to PseudoJet...
virtual double exclusive_subdmerge_max(const PseudoJet &reference, int nsub) const
return the maximum dij that occurred in the whole event at the stage that the nsub+1 -> nsub merge of...
virtual std::vector< PseudoJet > exclusive_subjets_up_to(const PseudoJet &reference, int nsub) const
return the list of subjets obtained by unclustering the supplied jet down to n subjets (or all consti...
virtual bool object_in_jet(const PseudoJet &reference, const PseudoJet &jet) const
check if the reference PseudoJet is contained the second one passed as argument.
virtual double area_error(const PseudoJet &reference) const
return the error (uncertainty) associated with the determination of the area of this jet...
virtual bool has_child(const PseudoJet &reference, PseudoJet &child) const
check if it has been recombined with another PseudoJet in which case, return its child through the ar...
base class that sets interface for extensions of ClusterSequence that provide information about the a...
virtual PseudoJet area_4vector(const PseudoJet &reference) const
return the jet 4-vector area.
base class corresponding to errors that can be thrown by FastJet
Definition: Error.hh:41
virtual const ClusterSequence * validated_cs() const
if the jet has a valid associated cluster sequence then return a pointer to it; otherwise throw an er...
virtual std::vector< PseudoJet > exclusive_subjets(const PseudoJet &reference, const double &dcut) const
return a vector of all subjets of the current jet (in the sense of the exclusive algorithm) that woul...
an implementation of C++0x shared pointers (or boost&#39;s)
Definition: SharedPtr.hh:114
virtual bool has_valid_cluster_sequence() const
returns true if this PseudoJet has an associated and still valid ClusterSequence. ...
virtual const ClusterSequenceAreaBase * validated_csab() const
if the jet has valid area information then return a pointer to the associated ClusterSequenceAreaBase...
virtual bool has_exclusive_subjets() const
return true if the structure supports exclusive_subjets.
virtual bool has_partner(const PseudoJet &reference, PseudoJet &partner) const
check if it has been recombined with another PseudoJet in which case, return its partner through the ...
virtual std::vector< PseudoJet > constituents(const PseudoJet &reference) const
retrieve the constituents.
virtual std::string description() const
description
virtual bool has_area() const
check if it has a defined area
SharedPtr< PseudoJetStructureBase > _structure
the wrapped structure
Class to contain pseudojets, including minimal information of use to jet-clustering routines...
Definition: PseudoJet.hh:65
virtual bool has_associated_cluster_sequence() const
returns true if there is an associated ClusterSequence
virtual bool has_parents(const PseudoJet &reference, PseudoJet &parent1, PseudoJet &parent2) const
check if it is the product of a recombination, in which case return the 2 parents through the &#39;parent...