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