fastjet/contrib/Nsubjettiness.hh

0001 // Nsubjettiness Package
0002 //  Questions/Comments?  jthaler@jthaler.net
0003 //
0004 //  Copyright (c) 2011-14
0005 //  Jesse Thaler, Ken Van Tilburg, Christopher K. Vermilion, and TJ Wilkason
0006 //
0007 //  $Id: Nsubjettiness.hh 822 2015-06-15 23:52:57Z jthaler $
0008 //----------------------------------------------------------------------
0009 // This file is part of FastJet contrib.
0010 //
0011 // It is free software; you can redistribute it and/or modify it under
0012 // the terms of the GNU General Public License as published by the
0013 // Free Software Foundation; either version 2 of the License, or (at
0014 // your option) any later version.
0015 //
0016 // It is distributed in the hope that it will be useful, but WITHOUT
0017 // ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
0018 // or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
0019 // License for more details.
0020 //
0021 // You should have received a copy of the GNU General Public License
0022 // along with this code. If not, see <http://www.gnu.org/licenses/>.
0023 //----------------------------------------------------------------------
0024
0025 #ifndef __FASTJET_CONTRIB_NSUBJETTINESS_HH__
0026 #define __FASTJET_CONTRIB_NSUBJETTINESS_HH__
0027
0028 #include <fastjet/internal/base.hh>
0029
0030 #include "Njettiness.hh"
0031
0032 #include "fastjet/FunctionOfPseudoJet.hh"
0033 #include <string>
0034 #include <climits>
0035
0036 FASTJET_BEGIN_NAMESPACE      // defined in fastjet/internal/base.hh
0037
0038 namespace contrib {
0039
0040 // Classes defined in this file.
0041 class Nsubjettiness;
0042 class NsubjettinessRatio;
0043
0044 ///------------------------------------------------------------------------
0045 /// \class Nsubjettiness
0046 /// \brief Implements the N-subjettiness jet shape
0047 ///
0048 /**
0049  * The N-jettiness jet shape.
0050  *
0051  * Nsubjettiness extends the concept of Njettiness to a jet shape, but other
0052  * than the set of particles considered, they are identical.  This class
0053  * wraps the core Njettiness code to provide the fastjet::FunctionOfPseudoJet
0054  * interface for convenience in larger analyses.
0055  *
0056  * The recommended AxesDefinitions are:
0057  *   KT_Axes             : exclusive kt axes
0058  *   WTA_KT_Axes         : exclusive kt with winner-take-all recombination
0059  *   OnePass_KT_Axes     : one-pass minimization from kt starting point
0060  *   OnePass_WTA_KT_Axes : one-pass min. from wta_kt starting point
0061  * More AxesDefinitions are listed in the README and defined in AxesDefinition.hh
0062  *
0063  * The recommended MeasureDefinitions are (with the corresponding parameters)
0064  *   NormalizedMeasure(beta,R0)
0065  *      :  This was the original N-subjettiness measure (dimensionless)
0066  *   UnnormalizedMeasure(beta)
0067  *      :  This is the new recommended default, same as above but without
0068  *      :  the normalization factor, and hence has units of GeV
0069  *   NormalizedCutoffMeasure(beta,R0,Rcutoff)
0070  *      :  Same as normalized_measure, but cuts off at Rcutoff
0071  *   UnnormalizedCutoffMeasure(beta,Rcutoff)
0072  *      :  Same as unnormalized_measure, but cuts off at Rcutoff
0073  * More MeasureDefinitions are listed in the README and defined in MeasureDefinition.hh
0074  *
0075  * For example, for the UnnormalizedMeasure(beta), N-subjettiness is defined as:
0076  *
0077  * tau_N = Sum_{i in jet} p_T^i min((DR_i1)^beta, (DR_i2)^beta, ...)
0078  *
0079  *   DR_ij is the distance sqrt(Delta_phi^2 + Delta_rap^2) between particle i
0080  *   and jet j.
0081  *
0082  * The NormalizedMeausure include an extra parameter R0, and the various cutoff
0083  * measures include an Rcutoff, which effectively defines an angular cutoff
0084  * similar in effect to a cone-jet radius.
0085  */
0086 class Nsubjettiness : public FunctionOfPseudoJet<double> {
0087
0088 public:
0089
0090    /// Main constructor, which takes N, the AxesDefinition, and the MeasureDefinition.
0091    /// The Definitions are given in AxesDefinition.hh and MeasureDefinition.hh
0092    Nsubjettiness(int N,
0093                  const AxesDefinition& axes_def,
0094                  const MeasureDefinition& measure_def)
0095    : _njettinessFinder(axes_def,measure_def), _N(N) {}
0096
0097    /// Returns tau_N, measured on the constituents of this jet
0098    double result(const PseudoJet& jet) const;
0099
0100    /// Returns components of tau_N, so that user can find individual tau values.
0101    TauComponents component_result(const PseudoJet& jet) const;
0102
0103    /// To set axes in manual mode
0104    void setAxes(const std::vector<fastjet::PseudoJet> & myAxes) {
0105       // Note that cross check that manual mode has been set is in Njettiness
0106         _njettinessFinder.setAxes(myAxes);
0107    }
0108
0109    /// returns seed axes used for onepass minimization (otherwise same as currentAxes)
0110    std::vector<fastjet::PseudoJet> seedAxes() const {
0111       return _njettinessFinder.seedAxes();
0112    }
0113
0114    /// returns current axes found by result() calculation
0115    std::vector<fastjet::PseudoJet> currentAxes() const {
0116       return _njettinessFinder.currentAxes();
0117    }
0118
0119    /// returns subjet regions found by result() calculation (these have valid constituents)
0120    /// Note that the axes and the subjets are not the same
0121    std::vector<fastjet::PseudoJet> currentSubjets() const {
0122       return _njettinessFinder.currentJets();
0123    }
0124
0125    /// returns components of tau_N without recalculating anything
0126    TauComponents currentTauComponents() const {
0127       return _njettinessFinder.currentTauComponents();
0128    }
0129
0130    /// returns components of tau_N without recalculating anything
0131    TauPartition currentPartition() const {
0132       return _njettinessFinder.currentPartition();
0133    }
0134
0135 private:
0136
0137    /// Core Njettiness code that is called
0138    Njettiness _njettinessFinder; // TODO:  should muck with this so result can be const without this mutable
0139    /// Number of subjets to find
0140    int _N;
0141
0142    /// Warning if the user tries to use v1.0.3 constructor.
0143    static LimitedWarning _old_constructor_warning;
0144
0145 public:
0146
0147    // The following interfaces are included for backwards compatibility, but no longer recommended.
0148    // They may be deleted in a future release
0149
0150    /// \deprecated
0151    /// Alternative constructors that define the measure via enums and parameters
0152    /// These constructors will be removed in v3.0
0153    /// Zero parameter arguments
0154    /// (Currently, no measure uses this)
0155    Nsubjettiness(int N,
0156                  Njettiness::AxesMode axes_mode,
0157                  Njettiness::MeasureMode measure_mode)
0158    : _njettinessFinder(axes_mode, measure_mode, 0), _N(N) {
0159       _old_constructor_warning.warn("Nsubjettiness:  You are using the old style constructor.  This is deprecated as of v2.1 and will be removed in v3.0.  Please use the Nsubjettiness constructor based on AxesDefinition and MeasureDefinition instead.");
0160    }
0161
0162    /// \deprecated
0163    /// Construcotr for one parameter argument
0164    /// (for unnormalized_measure, para1=beta)
0165    Nsubjettiness(int N,
0166                  Njettiness::AxesMode axes_mode,
0167                  Njettiness::MeasureMode measure_mode,
0168                  double para1)
0169    : _njettinessFinder(axes_mode, measure_mode, 1, para1), _N(N) {
0170       _old_constructor_warning.warn("Nsubjettiness:  You are using the old style constructor.  This is deprecated as of v2.1 and will be removed in v3.0.  Please use the Nsubjettiness constructor based on AxesDefinition and MeasureDefinition instead.");
0171    }
0172
0173    /// \deprecated
0174    /// Constructor for two parameter arguments
0175    /// (for normalized_measure, para1=beta, para2=R0)
0176    /// (for unnormalized_cutoff_measure, para1=beta, para2=Rcutoff)
0177    Nsubjettiness(int N,
0178                  Njettiness::AxesMode axes_mode,
0179                  Njettiness::MeasureMode measure_mode,
0180                  double para1,
0181                  double para2)
0182    : _njettinessFinder(axes_mode, measure_mode, 2, para1, para2), _N(N) {
0183       _old_constructor_warning.warn("Nsubjettiness:  You are using the old style constructor.  This is deprecated as of v2.1 and will be removed in v3.0.  Please use the Nsubjettiness constructor based on AxesDefinition and MeasureDefinition instead.");
0184    }
0185
0186    /// \deprecated
0187    /// Constructor for three parameter arguments
0188    /// (for unnormalized_cutoff_measure, para1=beta, para2=R0, para3=Rcutoff)
0189    Nsubjettiness(int N,
0190                  Njettiness::AxesMode axes_mode,
0191                  Njettiness::MeasureMode measure_mode,
0192                  double para1,
0193                  double para2,
0194                  double para3)
0195    : _njettinessFinder(axes_mode, measure_mode, 3, para1, para2, para3), _N(N) {
0196       _old_constructor_warning.warn("Nsubjettiness:  You are using the old style constructor.  This is deprecated as of v2.1 and will be removed in v3.0.  Please use the Nsubjettiness constructor based on AxesDefinition and MeasureDefinition instead.");
0197    }
0198
0199    /// \deprecated
0200    /// Old constructor for backwards compatibility with v1.0,
0201    /// where normalized_cutoff_measure was the only option
0202    Nsubjettiness(int N,
0203                  Njettiness::AxesMode axes_mode,
0204                  double beta,
0205                  double R0,
0206                  double Rcutoff=std::numeric_limits<double>::max())
0207    : _njettinessFinder(axes_mode, NormalizedCutoffMeasure(beta,R0,Rcutoff)), _N(N) {
0208       _old_constructor_warning.warn("Nsubjettiness:  You are using the old style constructor.  This is deprecated as of v2.1 and will be removed in v3.0.  Please use the Nsubjettiness constructor based on AxesDefinition and MeasureDefinition instead.");
0209    }
0210
0211 };
0212
0213
0214 ///------------------------------------------------------------------------
0215 /// \class NsubjettinessRatio
0216 /// \brief Implements ratios of N-subjettiness jet shapes
0217 ///
0218 /// NsubjettinessRatio uses the results from Nsubjettiness to calculate the ratio
0219 /// tau_N/tau_M, where N and M are specified by the user. The ratio of different tau values
0220 /// is often used in analyses, so this class is helpful to streamline code.  Note that
0221 /// manual axis mode is not supported
0222 class NsubjettinessRatio : public FunctionOfPseudoJet<double> {
0223 public:
0224
0225    /// Main constructor.  Apart from specifying both N and M, the same options as Nsubjettiness
0226    NsubjettinessRatio(int N,
0227                       int M,
0228                       const AxesDefinition & axes_def,
0229                       const MeasureDefinition & measure_def)
0230    : _nsub_numerator(N,axes_def,measure_def),
0231    _nsub_denominator(M,axes_def,measure_def) {
0232       if (axes_def.needsManualAxes()) {
0233          throw Error("NsubjettinessRatio does not support ManualAxes mode.");
0234       }
0235    }
0236
0237    /// Returns tau_N/tau_M based off the input jet using result function from Nsubjettiness
0238    double result(const PseudoJet& jet) const;
0239
0240 private:
0241
0242    Nsubjettiness _nsub_numerator;   ///< Function for numerator
0243    Nsubjettiness _nsub_denominator; ///< Function for denominator
0244
0245 public:
0246
0247    // The following interfaces are included for backwards compatibility, but no longer recommended.
0248    // They may be deprecated at some point.
0249
0250    /// \deprecated
0251    /// Old-style constructor for zero arguments
0252    /// Alternative constructor with enums and parameters
0253    /// Again, likely to be removed
0254    NsubjettinessRatio(int N,
0255                       int M,
0256                       Njettiness::AxesMode axes_mode,
0257                       Njettiness::MeasureMode measure_mode)
0258    : _nsub_numerator(N, axes_mode, measure_mode),
0259    _nsub_denominator(M, axes_mode, measure_mode) {}
0260
0261    /// \deprecated
0262    /// Old-style constructor for one argument
0263    NsubjettinessRatio(int N,
0264                       int M,
0265                       Njettiness::AxesMode axes_mode,
0266                       Njettiness::MeasureMode measure_mode,
0267                       double para1)
0268    : _nsub_numerator(N, axes_mode, measure_mode, para1),
0269    _nsub_denominator(M, axes_mode, measure_mode, para1) {}
0270
0271    /// \deprecated
0272    /// Old-style constructor for 2 arguments
0273    NsubjettinessRatio(int N,
0274                       int M,
0275                       Njettiness::AxesMode axes_mode,
0276                       Njettiness::MeasureMode measure_mode,
0277                       double para1,
0278                       double para2)
0279    : _nsub_numerator(N, axes_mode, measure_mode, para1, para2),
0280    _nsub_denominator(M, axes_mode, measure_mode, para1, para2) {}
0281
0282    /// \deprecated
0283    /// Old-style constructor for 3 arguments
0284    NsubjettinessRatio(int N,
0285                       int M,
0286                       Njettiness::AxesMode axes_mode,
0287                       Njettiness::MeasureMode measure_mode,
0288                       double para1,
0289                       double para2,
0290                       double para3)
0291    : _nsub_numerator(N, axes_mode, measure_mode, para1, para2, para3),
0292    _nsub_denominator(M, axes_mode, measure_mode, para1, para2, para3) {}
0293
0294
0295 };
0296
0297 } // namespace contrib
0298
0299 FASTJET_END_NAMESPACE
0300
0301 #endif  // __FASTJET_CONTRIB_NSUBJETTINESS_HH__