1 //FJSTARTHEADER
2 // $Id: Subtractor.hh 4442 2020-05-05 07:50:11Z soyez $
3 //
4 // Copyright (c) 2005-2020, 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
Subtractor(BackgroundEstimatorBase * bge)65   Subtractor(BackgroundEstimatorBase * bge) :
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
Subtractor()77   Subtractor() : _bge(0), _rho(_invalid_rho) { set_defaults(); }
78 
79   /// default dtor
~Subtractor()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
set_use_rho_m(bool use_rho_m_in=true)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
use_rho_m() const110   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
set_safe_mass(bool safe_mass_in=true)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
safe_mass() const125   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).
set_known_selectors(const Selector & sel_known_vertex,const Selector & sel_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
182   mutable BackgroundEstimatorBase * _bge;
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 
212