FastJet  3.3.3
Subtractor.hh
1 //FJSTARTHEADER
2 // $Id: Subtractor.hh 4420 2019-11-29 09:28:20Z soyez $
3 //
4 // Copyright (c) 2005-2019, 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. They are described in the original FastJet paper,
16 // hep-ph/0512210 and in the manual, arXiv:1111.6097. If you use
17 // FastJet as part of work towards a scientific publication, please
18 // quote the version you use and include a citation to the manual and
19 // optionally also to hep-ph/0512210.
20 //
21 // FastJet is distributed in the hope that it will be useful,
22 // but WITHOUT ANY WARRANTY; without even the implied warranty of
23 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
24 // GNU General Public License for more details.
25 //
26 // You should have received a copy of the GNU General Public License
27 // along with FastJet. If not, see <http://www.gnu.org/licenses/>.
28 //----------------------------------------------------------------------
29 //FJENDHEADER
30 
31 #ifndef __FASTJET_TOOLS_SUBTRACTOR_HH__
32 #define __FASTJET_TOOLS_SUBTRACTOR_HH__
33 
34 #include "fastjet/internal/base.hh" // namespace macros (include explicitly to help Doxygen)
35 #include "fastjet/tools/Transformer.hh" // to derive Subtractor from Transformer
36 #include "fastjet/tools/BackgroundEstimatorBase.hh" // used as a ctor argument
37 
38 FASTJET_BEGIN_NAMESPACE // defined in fastjet/internal/base.hh
39 
40 
41 //----------------------------------------------------------------------
42 /// @ingroup tools_background
43 /// \class Subtractor
44 /// Class that helps perform jet background subtraction.
45 ///
46 /// This class derives from Transformer and makes use of a pointer to
47 /// a BackgroundEstimatorBase object in order to determine the background
48 /// in the vicinity of a given jet and then subtract area*background from
49 /// the jet. It can also be initialised with a specific fixed value for the
50 /// background pt density.
51 ///
52 /// \section input Input conditions
53 ///
54 /// The original jet must have area support (4-vector)
55 ///
56 /// \section output Output/interface
57 ///
58 /// The underlying structure of the returned, subtracted jet
59 /// (i.e. constituents, pieces, etc.) is identical to that of the
60 /// original jet.
61 ///
62 class Subtractor : public Transformer{
63 public:
64  /// define a subtractor based on a BackgroundEstimator
66  _bge(bge), _rho(-1.0) { set_defaults(); }
67 
68  /// define a subtractor that uses a fixed value of rho, the background
69  /// pt density per unit area (which must be positive)
70  Subtractor(double rho);
71 
72  /// define a subtractor that uses a fixed value of rho and rho_m;
73  /// both must be >= 0;
74  Subtractor(double rho, double rho_m);
75 
76  /// default constructor
77  Subtractor() : _bge(0), _rho(_invalid_rho) { set_defaults(); }
78 
79  /// default dtor
80  virtual ~Subtractor(){};
81 
82  /// @name configuring the behaviour
83  //\{
84  //----------------------------------------------------------------
85 
86  /// reset all parameters to default values
87  ///
88  /// Note: by default, the rho_m term is not included and the safety
89  /// test for the mass is not done. This is mostly for backwards
90  /// compatibility with FastJet 3.0 and is highly likely to change in
91  /// a future release of FastJet
92  void set_defaults();
93 
94  /// when 'use_rho_m' is true, include in the subtraction the
95  /// correction from rho_m, the purely longitudinal,
96  /// particle-mass-induced component of the background density per
97  /// unit area
98  ///
99  /// Note: this will be switched off by default (for backwards
100  /// compatibility with FastJet 3.0) but is highly likely to change
101  /// in a future release of FastJet
102  void set_use_rho_m(bool use_rho_m_in = true){
103  if (_bge == 0 && _rho_m < 0) {
104  throw Error("Subtractor: rho_m support works only for Subtractors constructed with a background estimator or an explicit rho_m value");
105  }
106  _use_rho_m=use_rho_m_in;
107  }
108 
109  /// returns whether or not the rho_m component is used
110  bool use_rho_m() const{ return _use_rho_m;}
111 
112  /// when 'safe_mass' is true, ensure that the mass of the subtracted
113  /// 4-vector remain positive
114  ///
115  /// when true, if the subtracted mass is negative, we return a
116  /// 4-vector with 0 mass, pt and phi from the subtracted 4-vector
117  /// and the rapidity of the original, unsubtracted jet.
118  ///
119  /// Note: this will be switched off by default (for backwards
120  /// compatibility with FastJet 3.0) but is highly likely to change
121  /// in a future release of FastJet
122  void set_safe_mass(bool safe_mass_in=true){ _safe_mass=safe_mass_in;}
123 
124  /// returns whether or not safety tests on the mass are included
125  bool safe_mass() const{ return _safe_mass;}
126 
127  /// This is mostly intended for cherge-hadron-subtracted type of
128  /// events where we wich to use vertex information to improve the
129  /// subtraction.
130  ///
131  /// Given the following parameters:
132  /// \param sel_known_vertex selects the particles with a
133  /// known vertex origin
134  /// \param sel_leading_vertex amongst the particles with a
135  /// known vertex origin, select those
136  /// coming from the leading vertex
137  /// Momentum identified as coming from the leading vertex will be
138  /// kept, momentum identified as coming from a non-leading vertex
139  /// will be eliminated and a regular area-median subtraction will be
140  /// applied on the 4-vector sum of the particles with unknown vertex
141  /// origin.
142  ///
143  /// When this is set, we shall ensure that the pt of the subtracted
144  /// 4-vector is at least the pt of the particles that are known to
145  /// come from the leading vertex (if it fails, subtraction returns
146  /// the component that is known to come from the leading vertex ---
147  /// or, the original unsubtracted jet if it contains no particles
148  /// from the leading vertex). Furthermore, when safe_mass() is on, we
149  /// also impose a similar constraint on the mass of the subtracted
150  /// 4-vector (if the test fails, the longitudinal part of the
151  /// subtracted 4-vector is taken from the component that is known to
152  /// come from the leading vertex).
153  void set_known_selectors(const Selector &sel_known_vertex,
154  const Selector &sel_leading_vertex){
155  _sel_known_vertex = sel_known_vertex;
156  _sel_leading_vertex = sel_leading_vertex;
157  }
158 
159  //\}
160 
161  /// @name description and action
162  //\{
163  //----------------------------------------------------------------
164 
165  /// returns a jet that's subtracted
166  ///
167  /// \param jet the jet that is to be subtracted
168  /// \return the subtracted jet
169  virtual PseudoJet result(const PseudoJet & jet) const;
170 
171  /// class description
172  virtual std::string description() const;
173 
174  //\}
175 protected:
176  /// compute the 4-vector that should be subtracted from the given
177  /// jet
178  PseudoJet _amount_to_subtract(const PseudoJet &jet) const;
179 
180  /// the tool used to estimate the background
181  /// if has to be mutable in case its underlying selector takes a reference jet
183  /// the fixed value of rho and/or rho_m to use if the user has selected that option
184  double _rho, _rho_m;
185 
186  // configuration parameters/flags
187  bool _use_rho_m; ///< include the rho_m correction
188  bool _safe_mass; ///< ensures that the subtracted mass is +ve
189 
190  Selector _sel_known_vertex; ///< selects the particles with a
191  ///< known vertex origin
192  Selector _sel_leading_vertex; ///< amongst the particles with a
193  ///< known vertex origin, select those
194  ///< coming from the leading vertex
195 
196  /// a value of rho that is used as a default to label that the stored
197  /// rho is not valid for subtraction.
198  //
199  // NB: there are two reasons for not having the value written here:
200  // 1) that it caused problems on karnak with g++ 4.0.1 and 2) that
201  // we anyway like -infinity as a default, and since that's a function,
202  // that's not allowed in an include file.
203  static const double _invalid_rho;
204 
205  static LimitedWarning _unused_rho_m_warning;
206 };
207 
208 FASTJET_END_NAMESPACE
209 
210 #endif // __FASTJET_TOOLS_SUBTRACTOR_HH__
211 
Class that helps perform jet background subtraction.
Definition: Subtractor.hh:62
void set_known_selectors(const Selector &sel_known_vertex, const Selector &sel_leading_vertex)
This is mostly intended for cherge-hadron-subtracted type of events where we wich to use vertex infor...
Definition: Subtractor.hh:153
Selector _sel_known_vertex
selects the particles with a known vertex origin
Definition: Subtractor.hh:190
virtual ~Subtractor()
default dtor
Definition: Subtractor.hh:80
void set_safe_mass(bool safe_mass_in=true)
when &#39;safe_mass&#39; is true, ensure that the mass of the subtracted 4-vector remain positive ...
Definition: Subtractor.hh:122
double _rho
the fixed value of rho and/or rho_m to use if the user has selected that option
Definition: Subtractor.hh:184
Subtractor()
default constructor
Definition: Subtractor.hh:77
Base (abstract) class for a jet transformer.
Definition: Transformer.hh:71
class to provide facilities for giving warnings up to some maximum number of times and to provide glo...
bool use_rho_m() const
returns whether or not the rho_m component is used
Definition: Subtractor.hh:110
base class corresponding to errors that can be thrown by FastJet
Definition: Error.hh:47
void set_use_rho_m(bool use_rho_m_in=true)
when &#39;use_rho_m&#39; is true, include in the subtraction the correction from rho_m, the purely longitudin...
Definition: Subtractor.hh:102
Abstract base class that provides the basic interface for classes that estimate levels of background ...
bool _use_rho_m
include the rho_m correction
Definition: Subtractor.hh:187
bool safe_mass() const
returns whether or not safety tests on the mass are included
Definition: Subtractor.hh:125
Selector _sel_leading_vertex
amongst the particles with a known vertex origin, select those coming from the leading vertex ...
Definition: Subtractor.hh:192
Class that encodes information about cuts and other selection criteria that can be applied to PseudoJ...
Definition: Selector.hh:149
Subtractor(BackgroundEstimatorBase *bge)
define a subtractor based on a BackgroundEstimator
Definition: Subtractor.hh:65
BackgroundEstimatorBase * _bge
the tool used to estimate the background if has to be mutable in case its underlying selector takes a...
Definition: Subtractor.hh:182
static const double _invalid_rho
a value of rho that is used as a default to label that the stored rho is not valid for subtraction...
Definition: Subtractor.hh:203
Class to contain pseudojets, including minimal information of use to jet-clustering routines...
Definition: PseudoJet.hh:67
bool _safe_mass
ensures that the subtracted mass is +ve
Definition: Subtractor.hh:188