include/fastjet/ClusterSequenceArea.hh

0001 //FJSTARTHEADER
0002 // $Id$
0003 //
0004 // Copyright (c) 2006-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_CLUSTERSEQUENCEAREA_HH__
0032 #define __FASTJET_CLUSTERSEQUENCEAREA_HH__
0033
0034 #include "fastjet/ClusterSequenceAreaBase.hh"
0035 #include "fastjet/ClusterSequenceActiveArea.hh"
0036 #include "fastjet/ClusterSequenceActiveAreaExplicitGhosts.hh"
0037 #include "fastjet/ClusterSequencePassiveArea.hh"
0038 #include "fastjet/ClusterSequenceVoronoiArea.hh"
0039 #include "fastjet/AreaDefinition.hh"
0040
0041 FASTJET_BEGIN_NAMESPACE
0042
0043 /// @ingroup area_classes
0044 /// \class ClusterSequenceArea
0045 /// General class for user to obtain ClusterSequence with additional
0046 /// area information.
0047 ///
0048 /// Based on the area_def, it automatically dispatches the work to the
0049 /// appropriate actual ClusterSequenceAreaBase-derived-class to do the
0050 /// real work.
0051 class ClusterSequenceArea : public ClusterSequenceAreaBase {
0052 public:
0053   /// main constructor
0054   template<class L> ClusterSequenceArea
0055          (const std::vector<L> & pseudojets,
0056       const JetDefinition & jet_def_in,
0057       const AreaDefinition & area_def_in)  : _area_def(area_def_in) {
0058     initialize_and_run_cswa(pseudojets, jet_def_in);
0059   }
0060
0061   /// constructor with a GhostedAreaSpec
0062   template<class L> ClusterSequenceArea
0063          (const std::vector<L> & pseudojets,
0064       const JetDefinition & jet_def_in,
0065       const GhostedAreaSpec & ghost_spec)   : _area_def(ghost_spec){
0066     initialize_and_run_cswa(pseudojets, jet_def_in);
0067   }
0068
0069   /// constructor with a VoronoiAreaSpec
0070   template<class L> ClusterSequenceArea
0071          (const std::vector<L> & pseudojets,
0072       const JetDefinition & jet_def_in,
0073       const VoronoiAreaSpec & voronoi_spec)   : _area_def(voronoi_spec){
0074     initialize_and_run_cswa(pseudojets, jet_def_in);
0075   }
0076
0077   /// return a reference to the area definition
0078   const AreaDefinition & area_def() const {return _area_def;}
0079
0080
0081   /// return the area associated with the given jet
0082   virtual double area       (const PseudoJet & jet) const FASTJET_OVERRIDE{
0083     return _area_base->area(jet);}
0084
0085   /// return the error (uncertainty) associated with the determination
0086   /// of the area of this jet
0087   virtual double area_error (const PseudoJet & jet) const FASTJET_OVERRIDE{
0088     return _area_base->area_error(jet);}
0089
0090   /// return the 4-vector area
0091   virtual PseudoJet area_4vector(const PseudoJet & jet) const FASTJET_OVERRIDE{
0092     return _area_base->area_4vector(jet);}
0093
0094   // /// return the total area, up to |y|<maxrap, that is free of jets
0095   // virtual double empty_area(double maxrap) const {
0096   //   return _area_base->empty_area(maxrap);}
0097   //
0098   // /// return something similar to the number of pure ghost jets
0099   // /// in the given rapidity range in an active area case.
0100   // /// For the local implementation we return empty_area/(0.55 pi R^2),
0101   // /// based on measured properties of ghost jets with kt and cam. Note
0102   // /// that the number returned is a double.
0103   // virtual double n_empty_jets(double maxrap) const {
0104   //   return _area_base->n_empty_jets(maxrap);
0105
0106   /// return the total area, corresponding to the given selector, that
0107   /// is free of jets
0108   ///
0109   /// The selector needs to have a finite area and be applicable jet by
0110   /// jet (see the BackgroundEstimator and Subtractor tools for more
0111   /// advanced usage)
0112   virtual double empty_area(const Selector & selector) const FASTJET_OVERRIDE{
0113     return _area_base->empty_area(selector);}
0114
0115   /// return something similar to the number of pure ghost jets
0116   /// in the given rap-phi range in an active area case.
0117   /// For the local implementation we return empty_area/(0.55 pi R^2),
0118   /// based on measured properties of ghost jets with kt and cam. Note
0119   /// that the number returned is a double.
0120   ///
0121   /// The selector needs to have a finite area and be applicable jet by
0122   /// jet (see the BackgroundEstimator and Subtractor tools for more
0123   /// advanced usage)
0124   virtual double n_empty_jets(const Selector & selector) const FASTJET_OVERRIDE{
0125     return _area_base->n_empty_jets(selector);
0126   }
0127
0128   /// true if a jet is made exclusively of ghosts
0129   virtual bool is_pure_ghost(const PseudoJet & jet) const FASTJET_OVERRIDE{
0130     return _area_base->is_pure_ghost(jet);
0131   }
0132
0133   /// true if this ClusterSequence has explicit ghosts
0134   virtual bool has_explicit_ghosts() const FASTJET_OVERRIDE{
0135     return _area_base->has_explicit_ghosts();
0136   }
0137
0138
0139   /// overload version of what's in the ClusterSequenceAreaBase class, which
0140   /// additionally checks compatibility between "selector" and region in which
0141   /// ghosts are thrown.
0142   ///
0143   /// The selector needs to have a finite area and be applicable jet by
0144   /// jet (see the BackgroundEstimator and Subtractor tools for more
0145   /// advanced usage)
0146   //FASTJET_DEPRECATED_MSG("ClusterSequenceArea::get_median_rho_and_sigma(...) is deprecated since FastJet 3.0. Use the BackgroundEstimator series of tools instead")
0147   virtual void get_median_rho_and_sigma(const std::vector<PseudoJet> & all_jets,
0148                     const Selector & selector,
0149                                         bool use_area_4vector,
0150                                         double & median, double & sigma,
0151                                         double & mean_area,
0152                     bool all_are_incl = false) const FASTJET_OVERRIDE{
0153     _warn_if_range_unsuitable(selector);
0154     ClusterSequenceAreaBase::_get_median_rho_and_sigma(
0155                                  all_jets, selector, use_area_4vector,
0156                  median, sigma, mean_area, all_are_incl);
0157   }
0158
0159   /// overload version of what's in the ClusterSequenceAreaBase class,
0160   /// which actually just does the same thing as the base version (but
0161   /// since we've overridden the 5-argument version above, we have to
0162   /// override the 4-argument version too.
0163   //FASTJET_DEPRECATED_MSG("ClusterSequenceArea::get_median_rho_and_sigma(...) is deprecated since FastJet 3.0. Use the BackgroundEstimator series of tools instead")
0164   virtual void get_median_rho_and_sigma(const Selector & selector,
0165                                         bool use_area_4vector,
0166                                         double & median, double & sigma) const FASTJET_OVERRIDE{
0167     ClusterSequenceAreaBase::_get_median_rho_and_sigma(selector,use_area_4vector,
0168                                                        median,sigma);
0169   }
0170
0171   /// overload version of what's in the ClusterSequenceAreaBase class,
0172   /// which actually just does the same thing as the base version (but
0173   /// since we've overridden the multi-argument version above, we have to
0174   /// override the 5-argument version too.
0175   //FASTJET_DEPRECATED_MSG("ClusterSequenceArea::get_median_rho_and_sigma(...) is deprecated since FastJet 3.0. Use the BackgroundEstimator series of tools instead")
0176   virtual void get_median_rho_and_sigma(const Selector & selector,
0177                                         bool use_area_4vector,
0178                                         double & median, double & sigma,
0179                     double & mean_area) const FASTJET_OVERRIDE{
0180     ClusterSequenceAreaBase::_get_median_rho_and_sigma(selector,use_area_4vector,
0181                                                        median,sigma, mean_area);
0182   }
0183
0184
0185   /// overload version of what's in the ClusterSequenceAreaBase class, which
0186   /// additionally checks compatibility between "range" and region in which
0187   /// ghosts are thrown.
0188   //FASTJET_DEPRECATED_MSG("ClusterSequenceArea::parabolic_pt_per_unit_area(...) is deprecated since FastJet 3.0. Use the BackgroundEstimator series of tools instead")
0189   virtual void parabolic_pt_per_unit_area(double & a, double & b,
0190                                           const Selector & selector,
0191                                           double exclude_above=-1.0,
0192                                           bool use_area_4vector=false) const FASTJET_OVERRIDE{
0193     return _parabolic_pt_per_unit_area(a,b,selector,exclude_above,use_area_4vector);
0194   }
0195
0196
0197 private:
0198
0199   /// print a warning if the range is unsuitable for the current
0200   /// calculation of the area (e.g. because ghosts do not extend
0201   /// far enough).
0202   void _warn_if_range_unsuitable(const Selector & selector) const;
0203
0204   template<class L> void initialize_and_run_cswa (
0205                                  const std::vector<L> & pseudojets,
0206                                  const JetDefinition & jet_def);
0207
0208   SharedPtr<ClusterSequenceAreaBase> _area_base;
0209   AreaDefinition _area_def;
0210   static LimitedWarning _range_warnings;
0211   static LimitedWarning _explicit_ghosts_repeats_warnings;
0212
0213   // the following set of private methods are all deprecated. Their
0214   // role is simply to hide the corresponding methods (without the
0215   // first underscore) from the public interface so that they can be
0216   // used internally until all the deprecated methods are removed.
0217   // DO NOT USE ANY OF THESE METHODS: THEY ARE DEPRECATED AND WILL BE
0218   // REMOVED.
0219   virtual void _parabolic_pt_per_unit_area(double & a, double & b,
0220                                           const Selector & selector,
0221                                           double exclude_above=-1.0,
0222                                           bool use_area_4vector=false) const FASTJET_OVERRIDE {
0223     _warn_if_range_unsuitable(selector);
0224     ClusterSequenceAreaBase::_parabolic_pt_per_unit_area(
0225                                 a,b,selector, exclude_above, use_area_4vector);
0226   }
0227
0228 };
0229
0230 //----------------------------------------------------------------------
0231 template<class L> void ClusterSequenceArea::initialize_and_run_cswa(
0232            const std::vector<L> & pseudojets,
0233            const JetDefinition  & jet_def_in)
0234  {
0235
0236   ClusterSequenceAreaBase * _area_base_ptr;
0237   switch(_area_def.area_type()) {
0238   case active_area:
0239     _area_base_ptr = new ClusterSequenceActiveArea(pseudojets,
0240                                                    jet_def_in,
0241                                                    _area_def.ghost_spec());
0242     break;
0243   case active_area_explicit_ghosts:
0244     if (_area_def.ghost_spec().repeat() != 1)
0245       _explicit_ghosts_repeats_warnings.warn("Requested active area with explicit ghosts with repeat != 1; only 1 set of ghosts will be used");
0246     _area_base_ptr = new ClusterSequenceActiveAreaExplicitGhosts(pseudojets,
0247                                                    jet_def_in,
0248                                                    _area_def.ghost_spec());
0249     break;
0250   case voronoi_area:
0251     _area_base_ptr = new ClusterSequenceVoronoiArea(pseudojets,
0252                                                    jet_def_in,
0253                                                    _area_def.voronoi_spec());
0254     break;
0255   case one_ghost_passive_area:
0256     _area_base_ptr = new ClusterSequence1GhostPassiveArea(pseudojets,
0257                             jet_def_in,
0258                             _area_def.ghost_spec());
0259     break;
0260   case passive_area:
0261     _area_base_ptr = new ClusterSequencePassiveArea(pseudojets,
0262                             jet_def_in,
0263                             _area_def.ghost_spec());
0264     break;
0265   default:
0266     std::ostringstream err;
0267     err << "Error: unrecognized area_type in ClusterSequenceArea:"
0268     << _area_def.area_type();
0269     throw Error(err.str());
0270     //exit(-1);
0271   }
0272   // now copy across the information from the area base class
0273   _area_base = SharedPtr<ClusterSequenceAreaBase>(_area_base_ptr);
0274   transfer_from_sequence(*_area_base);
0275 }
0276
0277 FASTJET_END_NAMESPACE
0278
0279 #endif // __FASTJET_CLUSTERSEQUENCEAREA_HH__
0280
0281