FastJet  3.0.6
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
Pruner.hh
1 #ifndef __FASTJET_TOOLS_PRUNER_HH__
2 #define __FASTJET_TOOLS_PRUNER_HH__
3 
4 //STARTHEADER
5 // $Id: Pruner.hh 2616 2011-09-30 18:03:40Z salam $
6 //
7 // Copyright (c) 2005-2011, 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 and are described in hep-ph/0512210. If you use
19 // FastJet as part of work towards a scientific publication, please
20 // include a citation to the FastJet paper.
21 //
22 // FastJet is distributed in the hope that it will be useful,
23 // but WITHOUT ANY WARRANTY; without even the implied warranty of
24 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
25 // GNU General Public License for more details.
26 //
27 // You should have received a copy of the GNU General Public License
28 // along with FastJet. If not, see <http://www.gnu.org/licenses/>.
29 //----------------------------------------------------------------------
30 //ENDHEADER
31 
32 #include "fastjet/ClusterSequence.hh"
33 #include "fastjet/WrappedStructure.hh"
34 #include "fastjet/tools/Transformer.hh"
35 #include <iostream>
36 #include <string>
37 
38 FASTJET_BEGIN_NAMESPACE // defined in fastjet/internal/base.hh
39 
40 // fwd declarations
41 class Pruner;
42 class PrunerStructure;
43 class PruningRecombiner;
44 class PruningPlugin;
45 
46 //----------------------------------------------------------------------
47 /// @ingroup tools_generic
48 /// \class Pruner
49 /// Transformer that prunes a jet
50 ///
51 /// This transformer prunes a jet according to the ideas presented in
52 /// arXiv:0903.5081 (S.D. Ellis, C.K. Vermilion and J.R. Walsh).
53 ///
54 /// The jet's constituents are reclustered with a user-specified jet
55 /// definition, with the modification that objects i and j are only
56 /// recombined if at least one of the following two criteria is
57 /// satisfied:
58 ///
59 /// - the geometric distance between i and j is smaller than 'Rcut'
60 /// with Rcut = Rcut_factor*2m/pt (Rcut_factor is a parameter of
61 /// the Pruner and m and pt obtained from the jet being pruned)
62 /// - the transverse momenta of i and j are at least 'zcut' p_t(i+j)
63 ///
64 /// If both these criteria fail, i and j are not recombined, the
65 /// harder of i and j is kept, and the softer is rejected.
66 ///
67 /// Usage:
68 /// \code
69 /// Pruner pruner(jet_def, zcut, Rcut_factor);
70 /// PseudoJet pruned_jet = pruner(jet);
71 /// \endcode
72 ///
73 /// The pruned_jet has a valid associated cluster sequence. In addition
74 /// the subjets of the original jet that have been vetoed by pruning
75 /// (i.e. have been 'pruned away') can be accessed using
76 ///
77 /// \code
78 /// vector<PseudoJet> rejected_subjets = pruned_jet.structure_of<Pruner>().rejected();
79 /// \endcode
80 ///
81 /// If the re-clustering happens to find more than a single inclusive
82 /// jet (this should normally not happen if the radius of the jet
83 /// definition used for the reclustering was set large enough),
84 /// the hardest of these jets is retured as the result of the
85 /// Pruner. The other jets can be accessed through
86 ///
87 /// \code
88 /// vector<PseudoJet> extra_jets = pruned_jet.structure_of<Pruner>().extra_jets();
89 /// \endcode
90 ///
91 /// Instead of using Rcut_factor and zcut, one can alternatively
92 /// construct a Pruner by passing two (pointers to) functions of
93 /// PseudoJet that dynamically compute the Rcut and zcut to
94 /// be used for the jet being pruned.
95 ///
96 /// When the jet being pruned has area support and explicit ghosts,
97 /// the resulting pruned jet will likewise have area.
98 ///
99 //----------------------------------------------------------------------
100 class Pruner : public Transformer{
101 public:
102  /// minimal constructor, which takes a jet algorithm, sets the radius
103  /// to JetDefinition::max_allowable_R (practically equivalent to
104  /// infinity) and also tries to use a recombiner based on the one in
105  /// the jet definition of the particular jet being pruned.
106  ///
107  /// \param jet_alg the jet algorithm for the internal clustering
108  /// \param zcut pt-fraction cut in the pruning
109  /// \param Rcut_factor the angular distance cut in the pruning will be
110  /// Rcut_factor * 2m/pt
111  Pruner(const JetAlgorithm jet_alg, double zcut, double Rcut_factor)
112  : _jet_def(jet_alg, JetDefinition::max_allowable_R),
113  _zcut(zcut), _Rcut_factor(Rcut_factor),
114  _zcut_dyn(0), _Rcut_dyn(0), _get_recombiner_from_jet(true) {}
115 
116 
117  /// alternative ctor in which the full reclustering jet definition can
118  /// be specified.
119  ///
120  /// \param jet_def the jet definition for the internal clustering
121  /// \param zcut pt-fraction cut in the pruning
122  /// \param Rcut_factor the angular distance cut in the pruning will be
123  /// Rcut_factor * 2m/pt
124  Pruner(const JetDefinition &jet_def, double zcut, double Rcut_factor)
125  : _jet_def(jet_def),
126  _zcut(zcut), _Rcut_factor(Rcut_factor),
127  _zcut_dyn(0), _Rcut_dyn(0), _get_recombiner_from_jet(false) {}
128 
129 
130  /// alternative ctor in which the pt-fraction cut and angular distance
131  /// cut are functions of the jet being pruned.
132  ///
133  /// \param jet_def the jet definition for the internal clustering
134  /// \param zcut_dyn dynamic pt-fraction cut in the pruning
135  /// \param Rcut_dyn dynamic angular distance cut in the pruning
136  Pruner(const JetDefinition &jet_def,
137  FunctionOfPseudoJet<double> *zcut_dyn,
138  FunctionOfPseudoJet<double> *Rcut_dyn);
139 
140  /// action on a single jet
141  virtual PseudoJet result(const PseudoJet &jet) const;
142 
143  /// description
144  virtual std::string description() const;
145 
146  // the type of the associated structure
147  typedef PrunerStructure StructureType;
148 
149 private:
150  /// check if the jet has explicit_ghosts (knowing that there is an
151  /// area support)
152  bool _check_explicit_ghosts(const PseudoJet &jet) const;
153 
154  /// return a pointer to a "common" recombiner if there is one,
155  /// alternatively a null pointer.
156  const JetDefinition::Recombiner * _get_common_recombiner(const PseudoJet &jet) const;
157 
158  JetDefinition _jet_def; ///< the internal jet definition
159  double _zcut; ///< the pt-fraction cut
160  double _Rcut_factor; ///< the angular separation cut factor
161  FunctionOfPseudoJet<double> *_zcut_dyn; ///< dynamic zcut
162  FunctionOfPseudoJet<double> *_Rcut_dyn; ///< dynamic Rcut
163  bool _get_recombiner_from_jet; ///< true for minimal constructor,
164  ///< causes recombiner to be set equal
165  ///< to that already used in the jet
166  ///< (if it can be deduced)
167 };
168 
169 
170 //----------------------------------------------------------------------
171 /// @ingroup tools_generic
172 /// \class PrunerStructure
173 /// The structure associated with a PseudoJet thas has gone through a
174 /// Pruner transformer
175 //----------------------------------------------------------------------
177 public:
178  /// default ctor
179  /// \param result_jet the jet for which we have to keep the structure
180  PrunerStructure(const PseudoJet & result_jet)
181  : WrappedStructure(result_jet.structure_shared_ptr()){}
182 
183  /// description
184  virtual std::string description() const{ return "Pruned PseudoJet";}
185 
186  /// return the constituents that have been rejected
187  std::vector<PseudoJet> rejected() const{
188  return validated_cs()->childless_pseudojets();
189  }
190 
191  /// return the other jets that may have been found along with the
192  /// result of the pruning
193  /// The resulting vector is sorted in pt
194  std::vector<PseudoJet> extra_jets() const;
195 
196 protected:
197  friend class Pruner; ///< to allow setting the internal information
198 };
199 
200 //----------------------------------------------------------------------
201 /// \if internal_doc
202 /// @ingroup internal
203 /// \class PruningRecombiner
204 /// recombines the objects that are not vetoed by pruning
205 ///
206 /// This recombiner only recombines, using the provided 'recombiner',
207 /// objects (i and j) that pass at least one of the following two criteria:
208 ///
209 /// - the geometric distance between i and j is smaller than 'Rcut'
210 /// - the transverse momenta of i and j are at least 'zcut' p_t(i+j)
211 ///
212 /// If both these criteria fail, the hardest of i and j is kept and
213 /// the softest is rejected.
214 ///
215 /// Note that this in not meant for standalone use [in particular
216 /// because it could lead to memory issues due to the rejected indices
217 /// stored internally].
218 ///
219 /// \endif
220 class PruningRecombiner : public JetDefinition::Recombiner{
221 public:
222  /// ctor
223  /// \param zcut transverse momentum fraction cut
224  /// \param Rcut angular separation cut
225  /// \param recomb pointer to a recombiner to use to cluster pairs
226  PruningRecombiner(double zcut, double Rcut,
227  const JetDefinition::Recombiner *recombiner)
228  : _zcut2(zcut*zcut), _Rcut2(Rcut*Rcut),
229  _recombiner(recombiner){}
230 
231  /// perform a recombination taking into account the pruning
232  /// conditions
233  virtual void recombine(const PseudoJet &pa,
234  const PseudoJet &pb,
235  PseudoJet &pab) const;
236 
237  /// returns the description of the recombiner
238  virtual std::string description() const;
239 
240  /// return the history indices that have been pruned away
241  const std::vector<unsigned int> & rejected() const{ return _rejected;}
242 
243  /// clears the list of rejected indices
244  ///
245  /// If one decides to use this recombiner standalone, one has to
246  /// call this after each clustering in order for the rejected() vector
247  /// to remain sensible and not grow to infinite size.
248  void clear_rejected(){ _rejected.clear();}
249 
250 private:
251  double _zcut2; ///< transverse momentum fraction cut (squared)
252  double _Rcut2; ///< angular separation cut (squared)
253  const JetDefinition::Recombiner *_recombiner; ///< the underlying recombiner to use
254  mutable std::vector<unsigned int> _rejected; ///< list of rejected history indices
255 };
256 
257 
258 //----------------------------------------------------------------------
259 /// \if internal_doc
260 /// @ingroup internal
261 /// \class PruningPlugin
262 /// FastJet internal plugin that clusters the particles using the
263 /// PruningRecombiner.
264 ///
265 /// See PruningRecombiner for a description of what pruning does.
266 ///
267 /// Note that this is an internal FastJet class used by the Pruner
268 /// transformer and it is not meant to be used as a standalone clustering
269 /// tool.
270 ///
271 /// \endif
272 //----------------------------------------------------------------------
273 class PruningPlugin : public JetDefinition::Plugin{
274 public:
275  /// ctor
276  /// \param jet_def the jet definition to be used for the
277  /// internal clustering
278  /// \param zcut transverse momentum fraction cut
279  /// \param Rcut angular separation cut
280  PruningPlugin(const JetDefinition &jet_def, double zcut, double Rcut)
281  : _jet_def(jet_def), _zcut(zcut), _Rcut(Rcut){}
282 
283  /// the actual clustering work for the plugin
284  virtual void run_clustering(ClusterSequence &input_cs) const;
285 
286  /// description of the plugin
287  virtual std::string description() const;
288 
289  /// returns the radius
290  virtual double R() const {return _jet_def.R();}
291 
292 private:
293  JetDefinition _jet_def; ///< the internal jet definition
294  double _zcut; ///< transverse momentum fraction cut
295  double _Rcut; ///< angular separation cut
296 };
297 
298 
299 
300 FASTJET_END_NAMESPACE // defined in fastjet/internal/base.hh
301 
302 #endif // __FASTJET_TOOLS_PRUNER_HH__
Pruner(const JetDefinition &jet_def, double zcut, double Rcut_factor)
alternative ctor in which the full reclustering jet definition can be specified.
Definition: Pruner.hh:124
virtual void recombine(const PseudoJet &pa, const PseudoJet &pb, PseudoJet &pab) const =0
recombine pa and pb and put result into pab
This wraps a (shared) pointer to an underlying structure.
Base (abstract) class for a jet transformer.
Definition: Transformer.hh:69
std::vector< PseudoJet > rejected() const
return the constituents that have been rejected
Definition: Pruner.hh:187
Transformer that prunes a jet.
Definition: Pruner.hh:100
PrunerStructure(const PseudoJet &result_jet)
default ctor
Definition: Pruner.hh:180
The structure associated with a PseudoJet thas has gone through a Pruner transformer.
Definition: Pruner.hh:176
virtual std::string description() const
description
Definition: Pruner.hh:184
Pruner(const JetAlgorithm jet_alg, double zcut, double Rcut_factor)
minimal constructor, which takes a jet algorithm, sets the radius to JetDefinition::max_allowable_R (...
Definition: Pruner.hh:111
virtual std::string description() const =0
return a textual description of the recombination scheme implemented here
An abstract base class that will provide the recombination scheme facilities and/or allow a user to e...
JetAlgorithm
the various families of jet-clustering algorithm
Class to contain pseudojets, including minimal information of use to jet-clustering routines...
Definition: PseudoJet.hh:65
class that is intended to hold a full definition of the jet clusterer