FastJet  3.0.2
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
GridMedianBackgroundEstimator.hh
1 #ifndef __GRID_MEDIAN_BACKGROUND_ESTIMATOR_HH__
2 #define __GRID_MEDIAN_BACKGROUND_ESTIMATOR_HH__
3 
4 //STARTHEADER
5 // $Id: GridMedianBackgroundEstimator.hh 2580 2011-09-13 17:25:43Z 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 
33 #include "fastjet/tools/BackgroundEstimatorBase.hh"
34 
35 FASTJET_BEGIN_NAMESPACE // defined in fastjet/internal/base.hh
36 
37 /// @ingroup tools_background
38 /// \class GridMedianBackgroundEstimator
39 ///
40 /// Background Estimator based on the median pt/area of a set of grid
41 /// cells.
42 ///
43 /// Description of the method:
44 /// This background estimator works by projecting the event onto a
45 /// grid in rapidity and azimuth. In each grid cell, the scalar pt
46 /// sum of the particles in the cell is computed. The background
47 /// density is then estimated by the median of (scalar pt sum/cell
48 /// area) for all cells.
49 ///
50 /// Parameters:
51 /// The class takes 2 arguments: the absolute rapidity extent of the
52 /// cells and the size of the grid cells. Note that the size of the cell
53 /// will be adjusted in azimuth to satisfy the 2pi periodicity and
54 /// in rapidity to match the requested rapidity extent.
55 ///
56 /// Rescaling:
57 /// It is possible to use a rescaling profile. In this case, the
58 /// profile needs to be set before setting the particles and it will
59 /// be applied to each particle (i.e. not to each cell).
60 /// Note also that in this case one needs to call rho(jet) instead of
61 /// rho() [Without rescaling, they are identical]
62 ///
63 class GridMedianBackgroundEstimator : public BackgroundEstimatorBase {
64 public:
65  /// @name constructors and destructors
66  //\{
67  //----------------------------------------------------------------
68  /// \param ymax maximal absolute rapidity extent of the grid
69  /// \param requested_grid_spacing size of the grid cell. The
70  /// "real" cell size could differ due e.g. to the 2pi
71  /// periodicity in azimuthal angle (size, not area)
72  GridMedianBackgroundEstimator(double ymax, double requested_grid_spacing) :
73  _ymin(-ymax), _ymax(ymax),
74  _requested_grid_spacing(requested_grid_spacing),
75  _has_particles(false){setup_grid();}
76  //\}
77 
78 
79  /// @name setting a new event
80  //\{
81  //----------------------------------------------------------------
82 
83  /// tell the background estimator that it has a new event, composed
84  /// of the specified particles.
85  void set_particles(const std::vector<PseudoJet> & particles);
86 
87  //\}
88 
89  /// @name retrieving fundamental information
90  //\{
91  //----------------------------------------------------------------
92 
93  /// returns rho, the median background density per unit area
94  double rho() const;
95 
96  /// returns sigma, the background fluctuations per unit area; must be
97  /// multipled by sqrt(area) to get fluctuations for a region of a
98  /// given area.
99  double sigma() const;
100 
101  /// returns rho, the background density per unit area, locally at the
102  /// position of a given jet. Note that this is not const, because a
103  /// user may then wish to query other aspects of the background that
104  /// could depend on the position of the jet last used for a rho(jet)
105  /// determination.
106  double rho(const PseudoJet & jet);
107 
108  /// returns sigma, the background fluctuations per unit area, locally at
109  /// the position of a given jet. As for rho(jet), it is non-const.
110  double sigma(const PseudoJet & jet);
111 
112  /// returns true if this background estimator has support for
113  /// determination of sigma
114  bool has_sigma() {return true;}
115 
116  /// returns the area of the grid cells (all identical, but
117  /// referred to as "mean" area for uniformity with JetMedianBGE).
118  double mean_area() const {return _cell_area;}
119  //\}
120 
121  /// @name configuring the behaviour
122  //\{
123  //----------------------------------------------------------------
124 
125  /// Set a pointer to a class that calculates the rescaling factor as
126  /// a function of the jet (position). Note that the rescaling factor
127  /// is used both in the determination of the "global" rho (the pt/A
128  /// of each jet is divided by this factor) and when asking for a
129  /// local rho (the result is multiplied by this factor).
130  ///
131  /// The BackgroundRescalingYPolynomial class can be used to get a
132  /// rescaling that depends just on rapidity.
133  ///
134  /// Note that this has to be called BEFORE any attempt to do an
135  /// actual computation
136  virtual void set_rescaling_class(const FunctionOfPseudoJet<double> * rescaling_class);
137 
138  //\}
139 
140  /// @name description
141  //\{
142  //----------------------------------------------------------------
143 
144  /// returns a textual description of the background estimator
145  std::string description() const;
146 
147  //\}
148 
149 
150 private:
151  /// configure the grid
152  void setup_grid();
153 
154  /// retrieve the grid cell index for a given PseudoJet
155  int igrid(const PseudoJet & p) const;
156 
157  /// verify that particles have been set and throw an error if not
158  void verify_particles_set() const;
159 
160  // information about the grid
161  double _ymin, _ymax, _dy, _dphi, _requested_grid_spacing, _cell_area;
162  int _ny, _nphi, _ntotal;
163 
164  // information abotu the event
165  std::vector<double> _scalar_pt;
166  bool _has_particles;
167 
168  // various warnings to let people aware of potential dangers
169  LimitedWarning _warning_rho_of_jet;
170  LimitedWarning _warning_rescaling;
171 };
172 
173 FASTJET_END_NAMESPACE // defined in fastjet/internal/base.hh
174 
175 #endif // __GRID_MEDIAN_BACKGROUND_ESTIMATOR_HH__