include/fastjet/RangeDefinition.hh

0001 //FJSTARTHEADER
0002 // $Id$
0003 //
0004 // Copyright (c) 2005-2021, Matteo Cacciari, Gavin P. Salam and Gregory Soyez
0005 //
0006 //----------------------------------------------------------------------
0007 // This file is part of FastJet.
0008 //
0009 //  FastJet is free software; you can redistribute it and/or modify
0010 //  it under the terms of the GNU General Public License as published by
0011 //  the Free Software Foundation; either version 2 of the License, or
0012 //  (at your option) any later version.
0013 //
0014 //  The algorithms that underlie FastJet have required considerable
0015 //  development. They are described in the original FastJet paper,
0016 //  hep-ph/0512210 and in the manual, arXiv:1111.6097. If you use
0017 //  FastJet as part of work towards a scientific publication, please
0018 //  quote the version you use and include a citation to the manual and
0019 //  optionally also to hep-ph/0512210.
0020 //
0021 //  FastJet is distributed in the hope that it will be useful,
0022 //  but WITHOUT ANY WARRANTY; without even the implied warranty of
0023 //  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
0024 //  GNU General Public License for more details.
0025 //
0026 //  You should have received a copy of the GNU General Public License
0027 //  along with FastJet. If not, see <http://www.gnu.org/licenses/>.
0028 //----------------------------------------------------------------------
0029 //FJENDHEADER
0030
0031 #ifndef __FASTJET_RANGEDEFINITION_HH__
0032 #define __FASTJET_RANGEDEFINITION_HH__
0033
0034 #include "fastjet/PseudoJet.hh"
0035 #include "fastjet/Error.hh"
0036 #include "fastjet/LimitedWarning.hh"
0037 #include "fastjet/internal/deprecated.hh"
0038 #include<sstream>
0039 #include<iostream>
0040 #include<string>
0041
0042 FASTJET_BEGIN_NAMESPACE      // defined in fastjet/internal/base.hh
0043
0044 //----------------------------------------------------------------------
0045 //
0046 /// @ingroup area_classes
0047 /// \class RangeDefinition
0048 /// class for holding a range definition specification, given by limits
0049 /// on rapidity and azimuth.
0050 ///
0051 class RangeDefinition {
0052 public:
0053   /// default constructor
0054   FASTJET_DEPRECATED_MSG("RangeDefinition is deprecated since FastJet 3.0. Use the Selector mechanism instead",
0055   RangeDefinition()) { _warn_deprecated(); }
0056
0057   /// constructor for a range definition given by |y|<rapmax
0058   FASTJET_DEPRECATED_MSG("RangeDefinition is deprecated since FastJet 3.0. Use the Selector mechanism instead",
0059   RangeDefinition(double rapmax)) {  _warn_deprecated();
0060                      assert ( rapmax > 0.0 );
0061                      _rapmax = rapmax;
0062              _rapmin = -rapmax;
0063              _phimin = 0.0;
0064              _phimax = twopi;
0065              _total_area = 2.0*rapmax*twopi;
0066                      _phispan = _phimax-_phimin; }
0067
0068   /// destructor does nothing
0069   virtual ~RangeDefinition() {}
0070
0071   /// constructor for a range definition given by
0072   /// rapmin <= y <= rapmax, phimin <= phi <= phimax
0073   RangeDefinition(double rapmin, double rapmax,
0074                   double phimin = 0.0, double phimax = twopi) {
0075                      _warn_deprecated();
0076                      assert ( rapmin < rapmax);
0077                      assert ( phimin < phimax);
0078                      assert ( phimin > -twopi );
0079                      assert ( phimax < 2*twopi);
0080                      _rapmax = rapmax;
0081              _rapmin = rapmin;
0082              _phimin = phimin;
0083              _phimax = phimax;
0084              if (_phimax-_phimin > twopi)
0085                _total_area = (_rapmax - _rapmin)*twopi;
0086              else
0087                _total_area = (_rapmax - _rapmin)*(_phimax - _phimin);
0088                      _phispan = _phimax-_phimin; }
0089
0090   /// returns true if the range is localizable (i.e. set_position is
0091   /// meant to do something meaningful).
0092   ///
0093   /// This version of the class is not localizable and so it returns
0094   /// false.
0095   ///
0096   /// For localizable classes override this function with a function
0097   /// that returns true
0098   virtual inline bool is_localizable() const { return false; }
0099
0100
0101   /// place the range on the rap-phi position
0102   ///
0103   /// THIS DOES NOT DO ANYTHING FOR THIS CLASS AND IS ONLY THERE
0104   /// TO FACILITATE DERIVED CLASSES
0105   ///
0106   /// DON'T NECESSARILY COUNT ON IT IN THE FUTURE EITHER???
0107   inline void set_position(const double & rap, const double & phi) {
0108      if (! is_localizable() ) {
0109        std::ostringstream err;
0110        err << description() <<
0111          "\nThis range is not localizable. set_position() should not be used on it.";
0112        throw Error(err.str());
0113      } else {
0114        _rapjet = rap;
0115        _phijet = phi;
0116      }
0117   }
0118
0119   /// place the range on the jet position
0120   inline void set_position(const PseudoJet & jet) {
0121      set_position(jet.rap(),jet.phi());
0122   }
0123
0124   /// return bool according to whether the jet is within the given range
0125   inline bool is_in_range(const PseudoJet & jet) const {
0126     double rap = jet.rap();
0127     double phi = jet.phi();
0128     return is_in_range(rap,phi);
0129   }
0130
0131   /// return bool according to whether a (rap,phi) point is in range
0132   virtual inline bool is_in_range(double rap, double phi) const {
0133     double dphi=phi-_phimin;
0134     if (dphi >= twopi) dphi -= twopi;
0135     if (dphi < 0)      dphi += twopi;
0136     return  ( rap  >= _rapmin &&
0137           rap  <= _rapmax &&
0138           dphi <= _phispan );
0139   }
0140
0141   /// return the minimal and maximal rapidity of this range; remember to
0142   /// replace this if you write a derived class with more complex ranges;
0143   virtual inline void get_rap_limits(double & rapmin, double & rapmax) const {
0144     rapmin = _rapmin;
0145     rapmax = _rapmax;
0146   }
0147
0148   /// area of the range region
0149   virtual inline double area() const { return _total_area; }
0150
0151   /// textual description of range
0152   virtual inline std::string description() const {
0153     std::ostringstream ostr;
0154     ostr << "Range: " << _rapmin << " <= y <= "   << _rapmax << ", "
0155                       << _phimin << " <= phi <= " << _phimax ;
0156     return ostr.str();
0157 }
0158
0159 protected:
0160   double _total_area;  // total area of specified range
0161
0162   /// calculate, and set  _total_area, by calculating which of points on
0163   /// a grid (npoints * npoints from -rapmax..rapmax,0..2pi) are contained
0164   /// in the range; it takes a reasonable time with rapmax = 10,
0165   /// npoints = 100.
0166   void _numerical_total_area(double rapmax, int npoints) ;
0167   double _rapjet,_phijet; // jet position. only used in localizable derived classes
0168
0169 private:
0170   double _rapmin,_rapmax,_phimin,_phimax,_phispan;
0171
0172   static LimitedWarning _warnings_deprecated;
0173
0174   /// the use of RangeDefinition is deprecated since FastJet version
0175   /// 3.0 onwards. Please use Selector instead.
0176   /// RangeDefinition is only provided for backward compatibility
0177   /// reasons and is not guaranteed to work in future releases of
0178   /// FastJet.
0179   void _warn_deprecated() const;
0180 };
0181
0182 FASTJET_END_NAMESPACE        // defined in fastjet/internal/base.hh
0183
0184 #endif // __FASTJET_RANGEDEFINITION_HH__