FastJet  3.0.6
ClusterSequenceStructure.hh
1 //STARTHEADER
2 // $Id: ClusterSequenceStructure.hh 3071 2013-04-01 12:52:46Z cacciari $
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_CLUSTER_SEQUENCE_STRUCTURE_HH__
31 #define __FASTJET_CLUSTER_SEQUENCE_STRUCTURE_HH__
32 
33 #include "fastjet/internal/base.hh"
34 #include "fastjet/SharedPtr.hh"
35 #include "fastjet/PseudoJetStructureBase.hh"
36 
37 #include <vector>
38 
39 FASTJET_BEGIN_NAMESPACE // defined in fastjet/internal/base.hh
40 
41 /// @ingroup extra_info
42 /// \class ClusterSequenceStructure
43 ///
44 /// Contains any information related to the clustering that should be
45 /// directly accessible to PseudoJet.
46 ///
47 /// By default, this class implements basic access to the
48 /// ClusterSequence related to a PseudoJet (like its constituents or
49 /// its area). But it can be overloaded in order e.g. to give access
50 /// to the jet substructure.
51 ///
52 // Design question: Do we only put the methods that can be overloaded
53 // or do we put everything a PJ can have access to? I think both cost
54 // the same number of indirections. The first option limits the amount
55 // of coding and maybe has a clearer structure. The second is more
56 // consistent (everything related to the same thing is at the same
57 // place) and gives better access for derived classes. We'll go for
58 // the second option.
60 public:
61  /// default ctor
62  ClusterSequenceStructure() : _associated_cs(NULL){}
63 
64  /// ctor with initialisation to a given ClusterSequence
65  ///
66  /// In principle, this is reserved for initialisation by the parent
67  /// ClusterSequence
69  set_associated_cs(cs);
70  };
71 
72  /// default (virtual) dtor
73  virtual ~ClusterSequenceStructure();
74 
75  /// description
76  virtual std::string description() const{ return "PseudoJet with an associated ClusterSequence"; }
77 
78  //-------------------------------------------------------------
79  /// @name Direct access to the associated ClusterSequence object.
80  ///
81  /// Get access to the associated ClusterSequence (if any)
82  //\{
83  //-------------------------------------------------------------
84  /// returns true if there is an associated ClusterSequence
85  virtual bool has_associated_cluster_sequence() const{ return true;}
86 
87  /// get a (const) pointer to the parent ClusterSequence (NULL if
88  /// inexistent)
89  virtual const ClusterSequence* associated_cluster_sequence() const;
90 
91  /// returns true if there is a valid associated ClusterSequence
92  virtual bool has_valid_cluster_sequence() const;
93 
94  /// if the jet has a valid associated cluster sequence then return a
95  /// pointer to it; otherwise throw an error
96  virtual const ClusterSequence * validated_cs() const;
97 
98 #ifndef __FJCORE__
99  /// if the jet has valid area information then return a pointer to
100  /// the associated ClusterSequenceAreaBase object; otherwise throw an error
101  virtual const ClusterSequenceAreaBase * validated_csab() const;
102 #endif // __FJCORE__
103 
104  /// set the associated csw
105  virtual void set_associated_cs(const ClusterSequence * new_cs){
106  _associated_cs = new_cs;
107  }
108  //\}
109 
110  //-------------------------------------------------------------
111  /// @name Methods for access to information about jet structure
112  ///
113  /// These allow access to jet constituents, and other jet
114  /// subtructure information. They only work if the jet is associated
115  /// with a ClusterSequence.
116  //-------------------------------------------------------------
117  //\{
118 
119  /// check if it has been recombined with another PseudoJet in which
120  /// case, return its partner through the argument. Otherwise,
121  /// 'partner' is set to 0.
122  ///
123  /// an Error is thrown if this PseudoJet has no currently valid
124  /// associated ClusterSequence
125  virtual bool has_partner(const PseudoJet &reference, PseudoJet &partner) const;
126 
127  /// check if it has been recombined with another PseudoJet in which
128  /// case, return its child through the argument. Otherwise, 'child'
129  /// is set to 0.
130  ///
131  /// an Error is thrown if this PseudoJet has no currently valid
132  /// associated ClusterSequence
133  virtual bool has_child(const PseudoJet &reference, PseudoJet &child) const;
134 
135  /// check if it is the product of a recombination, in which case
136  /// return the 2 parents through the 'parent1' and 'parent2'
137  /// arguments. Otherwise, set these to 0.
138  ///
139  /// an Error is thrown if this PseudoJet has no currently valid
140  /// associated ClusterSequence
141  virtual bool has_parents(const PseudoJet &reference, PseudoJet &parent1, PseudoJet &parent2) const;
142 
143  /// check if the reference PseudoJet is contained in the second one
144  /// passed as argument.
145  ///
146  /// an Error is thrown if this PseudoJet has no currently valid
147  /// associated ClusterSequence
148  ///
149  /// false is returned if the 2 PseudoJet do not belong the same
150  /// ClusterSequence
151  virtual bool object_in_jet(const PseudoJet &reference, const PseudoJet &jet) const;
152 
153  /// return true if the structure supports constituents.
154  ///
155  /// an Error is thrown if this PseudoJet has no currently valid
156  /// associated ClusterSequence
157  virtual bool has_constituents() const;
158 
159  /// retrieve the constituents.
160  ///
161  /// an Error is thrown if this PseudoJet has no currently valid
162  /// associated ClusterSequence
163  virtual std::vector<PseudoJet> constituents(const PseudoJet &reference) const;
164 
165 
166  /// return true if the structure supports exclusive_subjets.
167  ///
168  /// an Error is thrown if this PseudoJet has no currently valid
169  /// associated ClusterSequence
170  virtual bool has_exclusive_subjets() const;
171 
172  /// return a vector of all subjets of the current jet (in the sense
173  /// of the exclusive algorithm) that would be obtained when running
174  /// the algorithm with the given dcut.
175  ///
176  /// Time taken is O(m ln m), where m is the number of subjets that
177  /// are found. If m gets to be of order of the total number of
178  /// constituents in the jet, this could be substantially slower than
179  /// just getting that list of constituents.
180  ///
181  /// an Error is thrown if this PseudoJet has no currently valid
182  /// associated ClusterSequence
183  virtual std::vector<PseudoJet> exclusive_subjets(const PseudoJet &reference, const double & dcut) const;
184 
185  /// return the size of exclusive_subjets(...); still n ln n with same
186  /// coefficient, but marginally more efficient than manually taking
187  /// exclusive_subjets.size()
188  ///
189  /// an Error is thrown if this PseudoJet has no currently valid
190  /// associated ClusterSequence
191  virtual int n_exclusive_subjets(const PseudoJet &reference, const double & dcut) const;
192 
193  /// return the list of subjets obtained by unclustering the supplied
194  /// jet down to nsub subjets (or all constituents if there are fewer
195  /// than nsub).
196  ///
197  /// requires nsub ln nsub time
198  ///
199  /// an Error is thrown if this PseudoJet has no currently valid
200  /// associated ClusterSequence
201  virtual std::vector<PseudoJet> exclusive_subjets_up_to (const PseudoJet &reference, int nsub) const;
202 
203  /// return the dij that was present in the merging nsub+1 -> nsub
204  /// subjets inside this jet.
205  ///
206  /// an Error is thrown if this PseudoJet has no currently valid
207  /// associated ClusterSequence
208  virtual double exclusive_subdmerge(const PseudoJet &reference, int nsub) const;
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  /// an Error is thrown if this PseudoJet has no currently valid
215  /// associated ClusterSequence
216  virtual double exclusive_subdmerge_max(const PseudoJet &reference, int nsub) const;
217 
218 
219  //-------------------------------------------------------------------
220  // information related to the pieces of the jet
221  //-------------------------------------------------------------------
222  /// by convention, a jet associated with a ClusterSequence will have
223  /// its parents as pieces
224  virtual bool has_pieces(const PseudoJet &reference) const;
225 
226  /// by convention, a jet associated with a ClusterSequence will have
227  /// its parents as pieces
228  ///
229  /// if it has no parents, then there will only be a single piece:
230  /// itself
231  ///
232  /// Note that to answer that question, we need to access the cluster
233  /// sequence. If the cluster sequence has gone out of scope, an
234  /// error will be thrown
235  virtual std::vector<PseudoJet> pieces(const PseudoJet &reference) const;
236 
237 
238  // the following ones require a computation of the area in the
239  // parent ClusterSequence (See ClusterSequenceAreaBase for details)
240  //------------------------------------------------------------------
241 #ifndef __FJCORE__
242 
243  /// check if it has a defined area
244  virtual bool has_area() const;
245 
246  /// return the jet (scalar) area.
247  /// throws an Error if there is no support for area in the parent CS
248  virtual double area(const PseudoJet &reference) const;
249 
250  /// return the error (uncertainty) associated with the determination
251  /// of the area of this jet.
252  /// throws an Error if there is no support for area in the parent CS
253  virtual double area_error(const PseudoJet &reference) const;
254 
255  /// return the jet 4-vector area.
256  /// throws an Error if there is no support for area in the parent CS
257  virtual PseudoJet area_4vector(const PseudoJet &reference) const;
258 
259  /// true if this jet is made exclusively of ghosts.
260  /// throws an Error if there is no support for area in the parent CS
261  virtual bool is_pure_ghost(const PseudoJet &reference) const;
262 
263 #endif // __FJCORE__
264  //\} --- end of jet structure -------------------------------------
265 
266 protected:
267  const ClusterSequence *_associated_cs;
268 };
269 
270 FASTJET_END_NAMESPACE
271 
272 #endif // __FASTJET_CLUSTER_SEQUENCE_STRUCTURE_HH__
fastjet::ClusterSequence
Definition: ClusterSequence.hh:59
fastjet::ClusterSequenceStructure::description
virtual std::string description() const
description
Definition: ClusterSequenceStructure.hh:76
fastjet::ClusterSequenceStructure::set_associated_cs
virtual void set_associated_cs(const ClusterSequence *new_cs)
set the associated csw
Definition: ClusterSequenceStructure.hh:105
fastjet::PseudoJetStructureBase
Definition: PseudoJetStructureBase.hh:57
fastjet::PseudoJet
Definition: PseudoJet.hh:65
fastjet::ClusterSequenceAreaBase
Definition: ClusterSequenceAreaBase.hh:45
fastjet::ClusterSequenceStructure::ClusterSequenceStructure
ClusterSequenceStructure(const ClusterSequence *cs)
ctor with initialisation to a given ClusterSequence
Definition: ClusterSequenceStructure.hh:68
fastjet::ClusterSequenceStructure::has_associated_cluster_sequence
virtual bool has_associated_cluster_sequence() const
returns true if there is an associated ClusterSequence
Definition: ClusterSequenceStructure.hh:85
fastjet::ClusterSequenceStructure
Definition: ClusterSequenceStructure.hh:59
fastjet::ClusterSequenceStructure::ClusterSequenceStructure
ClusterSequenceStructure()
default ctor
Definition: ClusterSequenceStructure.hh:62