FastJet  3.0.3
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
ClusterSequenceStructure.hh
1 //STARTHEADER
2 // $Id: ClusterSequenceStructure.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_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  /// 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 
102  /// set the associated csw
103  virtual void set_associated_cs(const ClusterSequence * new_cs){
104  _associated_cs = new_cs;
105  }
106  //\}
107 
108  //-------------------------------------------------------------
109  /// @name Methods for access to information about jet structure
110  ///
111  /// These allow access to jet constituents, and other jet
112  /// subtructure information. They only work if the jet is associated
113  /// with a ClusterSequence.
114  //-------------------------------------------------------------
115  //\{
116 
117  /// check if it has been recombined with another PseudoJet in which
118  /// case, return its partner through the argument. Otherwise,
119  /// 'partner' is set to 0.
120  ///
121  /// an Error is thrown if this PseudoJet has no currently valid
122  /// associated ClusterSequence
123  virtual bool has_partner(const PseudoJet &reference, PseudoJet &partner) const;
124 
125  /// check if it has been recombined with another PseudoJet in which
126  /// case, return its child through the argument. Otherwise, 'child'
127  /// is set to 0.
128  ///
129  /// an Error is thrown if this PseudoJet has no currently valid
130  /// associated ClusterSequence
131  virtual bool has_child(const PseudoJet &reference, PseudoJet &child) const;
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  /// an Error is thrown if this PseudoJet has no currently valid
138  /// associated ClusterSequence
139  virtual bool has_parents(const PseudoJet &reference, PseudoJet &parent1, PseudoJet &parent2) const;
140 
141  /// check if the reference PseudoJet is contained in the second one
142  /// passed as argument.
143  ///
144  /// an Error is thrown if this PseudoJet has no currently valid
145  /// associated ClusterSequence
146  ///
147  /// false is returned if the 2 PseudoJet do not belong the same
148  /// ClusterSequence
149  virtual bool object_in_jet(const PseudoJet &reference, const PseudoJet &jet) const;
150 
151  /// return true if the structure supports constituents.
152  ///
153  /// an Error is thrown if this PseudoJet has no currently valid
154  /// associated ClusterSequence
155  virtual bool has_constituents() const;
156 
157  /// retrieve the constituents.
158  ///
159  /// an Error is thrown if this PseudoJet has no currently valid
160  /// associated ClusterSequence
161  virtual std::vector<PseudoJet> constituents(const PseudoJet &reference) const;
162 
163 
164  /// return true if the structure supports exclusive_subjets.
165  ///
166  /// an Error is thrown if this PseudoJet has no currently valid
167  /// associated ClusterSequence
168  virtual bool has_exclusive_subjets() const;
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  /// an Error is thrown if this PseudoJet has no currently valid
180  /// associated ClusterSequence
181  virtual std::vector<PseudoJet> exclusive_subjets(const PseudoJet &reference, const double & dcut) const;
182 
183  /// return the size of exclusive_subjets(...); still n ln n with same
184  /// coefficient, but marginally more efficient than manually taking
185  /// exclusive_subjets.size()
186  ///
187  /// an Error is thrown if this PseudoJet has no currently valid
188  /// associated ClusterSequence
189  virtual int n_exclusive_subjets(const PseudoJet &reference, const double & dcut) const;
190 
191  /// return the list of subjets obtained by unclustering the supplied
192  /// jet down to nsub subjets (or all constituents if there are fewer
193  /// than nsub).
194  ///
195  /// requires nsub ln nsub time
196  ///
197  /// an Error is thrown if this PseudoJet has no currently valid
198  /// associated ClusterSequence
199  virtual std::vector<PseudoJet> exclusive_subjets_up_to (const PseudoJet &reference, int nsub) const;
200 
201  /// return the dij that was present in the merging nsub+1 -> nsub
202  /// subjets inside this jet.
203  ///
204  /// an Error is thrown if this PseudoJet has no currently valid
205  /// associated ClusterSequence
206  virtual double exclusive_subdmerge(const PseudoJet &reference, int nsub) const;
207 
208  /// return the maximum dij that occurred in the whole event at the
209  /// stage that the nsub+1 -> nsub merge of subjets occurred inside
210  /// this jet.
211  ///
212  /// an Error is thrown if this PseudoJet has no currently valid
213  /// associated ClusterSequence
214  virtual double exclusive_subdmerge_max(const PseudoJet &reference, int nsub) const;
215 
216 
217  //-------------------------------------------------------------------
218  // information related to the pieces of the jet
219  //-------------------------------------------------------------------
220  /// by convention, a jet associated with a ClusterSequence will have
221  /// its parents as pieces
222  virtual bool has_pieces(const PseudoJet &reference) const;
223 
224  /// by convention, a jet associated with a ClusterSequence will have
225  /// its parents as pieces
226  ///
227  /// if it has no parents, then there will only be a single piece:
228  /// itself
229  ///
230  /// Note that to answer that question, we need to access the cluster
231  /// sequence. If the cluster sequence has gone out of scope, an
232  /// error will be thrown
233  virtual std::vector<PseudoJet> pieces(const PseudoJet &reference) const;
234 
235 
236  // the following ones require a computation of the area in the
237  // parent ClusterSequence (See ClusterSequenceAreaBase for details)
238  //------------------------------------------------------------------
239 
240  /// check if it has a defined area
241  virtual bool has_area() const;
242 
243  /// return the jet (scalar) area.
244  /// throws an Error if there is no support for area in the parent CS
245  virtual double area(const PseudoJet &reference) const;
246 
247  /// return the error (uncertainty) associated with the determination
248  /// of the area of this jet.
249  /// throws an Error if there is no support for area in the parent CS
250  virtual double area_error(const PseudoJet &reference) const;
251 
252  /// return the jet 4-vector area.
253  /// throws an Error if there is no support for area in the parent CS
254  virtual PseudoJet area_4vector(const PseudoJet &reference) const;
255 
256  /// true if this jet is made exclusively of ghosts.
257  /// throws an Error if there is no support for area in the parent CS
258  virtual bool is_pure_ghost(const PseudoJet &reference) const;
259 
260  //\} --- end of jet structure -------------------------------------
261 
262 protected:
263  const ClusterSequence *_associated_cs;
264 };
265 
266 FASTJET_END_NAMESPACE
267 
268 #endif // __FASTJET_CLUSTER_SEQUENCE_STRUCTURE_HH__