Index: external/fastjet/contribs/Nsubjettiness/Nsubjettiness.hh
===================================================================
--- external/fastjet/contribs/Nsubjettiness/Nsubjettiness.hh	(revision 35cdc461e095e63247ab9dded070d76bc2c888e2)
+++ external/fastjet/contribs/Nsubjettiness/Nsubjettiness.hh	(revision 8713dee253b44fe1d26e1aad36beeb66152508c4)
@@ -5,5 +5,5 @@
 //  Jesse Thaler, Ken Van Tilburg, Christopher K. Vermilion, and TJ Wilkason
 //
-//  $Id: Nsubjettiness.hh 670 2014-06-06 01:24:42Z jthaler $
+//  $Id: Nsubjettiness.hh 822 2015-06-15 23:52:57Z jthaler $
 //----------------------------------------------------------------------
 // This file is part of FastJet contrib.
@@ -38,36 +38,56 @@
 namespace contrib {
 
-//------------------------------------------------------------------------
+// Classes defined in this file.
+class Nsubjettiness;
+class NsubjettinessRatio;
+   
+///------------------------------------------------------------------------
 /// \class Nsubjettiness
-/// Nsubjettiness extends the concept of Njettiness to a jet shape, but other
-/// than the set of particles considered, they are identical.  This class
-/// wraps the core Njettiness code to provide the fastjet::FunctionOfPseudoJet
-/// interface for convenience in larger analyses.  See NjettinessPlugin.hh for
-/// definitions of tau_N and the constructor options.
+/// \brief Implements the N-subjettiness jet shape
+///
+/**
+ * The N-jettiness jet shape.
+ *
+ * Nsubjettiness extends the concept of Njettiness to a jet shape, but other
+ * than the set of particles considered, they are identical.  This class
+ * wraps the core Njettiness code to provide the fastjet::FunctionOfPseudoJet
+ * interface for convenience in larger analyses.
+ *
+ * The recommended AxesDefinitions are:
+ *   KT_Axes             : exclusive kt axes
+ *   WTA_KT_Axes         : exclusive kt with winner-take-all recombination
+ *   OnePass_KT_Axes     : one-pass minimization from kt starting point
+ *   OnePass_WTA_KT_Axes : one-pass min. from wta_kt starting point
+ * More AxesDefinitions are listed in the README and defined in AxesDefinition.hh
+ *
+ * The recommended MeasureDefinitions are (with the corresponding parameters)
+ *   NormalizedMeasure(beta,R0)
+ *      :  This was the original N-subjettiness measure (dimensionless)
+ *   UnnormalizedMeasure(beta)
+ *      :  This is the new recommended default, same as above but without
+ *      :  the normalization factor, and hence has units of GeV
+ *   NormalizedCutoffMeasure(beta,R0,Rcutoff)
+ *      :  Same as normalized_measure, but cuts off at Rcutoff
+ *   UnnormalizedCutoffMeasure(beta,Rcutoff)
+ *      :  Same as unnormalized_measure, but cuts off at Rcutoff
+ * More MeasureDefinitions are listed in the README and defined in MeasureDefinition.hh
+ *
+ * For example, for the UnnormalizedMeasure(beta), N-subjettiness is defined as:
+ *
+ * tau_N = Sum_{i in jet} p_T^i min((DR_i1)^beta, (DR_i2)^beta, ...)
+ *
+ *   DR_ij is the distance sqrt(Delta_phi^2 + Delta_rap^2) between particle i
+ *   and jet j.
+ *
+ * The NormalizedMeausure include an extra parameter R0, and the various cutoff
+ * measures include an Rcutoff, which effectively defines an angular cutoff
+ * similar in effect to a cone-jet radius.
+ */
 class Nsubjettiness : public FunctionOfPseudoJet<double> {
 
 public:
-
-   
-   // Main constructor, which takes N, the AxesDefiniation, and the MeasureDefinition.
-   // The Definitions are given in NjettinessDefinition.hh
-   //
-   // The recommended AxesDefinitions are (more are available as listed in the README
-   // and defined in NjettinessDefinition.hh):
-   //   KT_Axes             : exclusive kt axes
-   //   WTA_KT_Axes         : exclusive kt with winner-take-all recombination
-   //   OnePass_KT_Axes     : one-pass minimization from kt starting point
-   //   OnePass_WTA_KT_Axes : one-pass min. from wta_kt starting point
-   //
-   // The recommended measure definitions are (with the corresponding parameters)
-   //   NormalizedMeasure(beta,R0)
-   //      :  This was the original N-subjettiness measure (dimensionless)
-   //   UnnormalizedMeasure(beta)
-   //      :  This is the new recommended default, same as above but without
-   //      :  the normalization factor, and hence has units of GeV
-   //   NormalizedCutoffMeasure(beta,R0,Rcutoff)
-   //      :  Same as normalized_measure, but cuts off at Rcutoff
-   //   UnnormalizedCutoffMeasure(beta,Rcutoff)
-   //      :  Same as unnormalized_measure, but cuts off at Rcutoff
+   
+   /// Main constructor, which takes N, the AxesDefinition, and the MeasureDefinition.
+   /// The Definitions are given in AxesDefinition.hh and MeasureDefinition.hh
    Nsubjettiness(int N,
                  const AxesDefinition& axes_def,
@@ -75,25 +95,84 @@
    : _njettinessFinder(axes_def,measure_def), _N(N) {}
    
-   
-   // Alternative constructors that define the measure via enums and parameters
-   // These constructors are likely be removed
-   // Zero parameter arguments
-   // (Currently, no measure uses this)
+   /// Returns tau_N, measured on the constituents of this jet
+   double result(const PseudoJet& jet) const;
+
+   /// Returns components of tau_N, so that user can find individual tau values.
+   TauComponents component_result(const PseudoJet& jet) const;
+   
+   /// To set axes in manual mode
+   void setAxes(const std::vector<fastjet::PseudoJet> & myAxes) {
+      // Note that cross check that manual mode has been set is in Njettiness
+    	_njettinessFinder.setAxes(myAxes);
+   }
+   
+   /// returns seed axes used for onepass minimization (otherwise same as currentAxes)
+   std::vector<fastjet::PseudoJet> seedAxes() const {
+      return _njettinessFinder.seedAxes();
+   }
+   
+   /// returns current axes found by result() calculation
+   std::vector<fastjet::PseudoJet> currentAxes() const {
+      return _njettinessFinder.currentAxes();
+   }
+
+   /// returns subjet regions found by result() calculation (these have valid constituents)
+   /// Note that the axes and the subjets are not the same
+   std::vector<fastjet::PseudoJet> currentSubjets() const {
+      return _njettinessFinder.currentJets();
+   }
+
+   /// returns components of tau_N without recalculating anything
+   TauComponents currentTauComponents() const {
+      return _njettinessFinder.currentTauComponents();
+   }
+
+   /// returns components of tau_N without recalculating anything
+   TauPartition currentPartition() const {
+      return _njettinessFinder.currentPartition();
+   }
+   
+private:
+   
+   /// Core Njettiness code that is called
+   Njettiness _njettinessFinder; // TODO:  should muck with this so result can be const without this mutable
+   /// Number of subjets to find
+   int _N;
+   
+   /// Warning if the user tries to use v1.0.3 constructor.
+   static LimitedWarning _old_constructor_warning;
+
+public:
+   
+   // The following interfaces are included for backwards compatibility, but no longer recommended.
+   // They may be deleted in a future release
+   
+   /// \deprecated
+   /// Alternative constructors that define the measure via enums and parameters
+   /// These constructors will be removed in v3.0
+   /// Zero parameter arguments
+   /// (Currently, no measure uses this)
    Nsubjettiness(int N,
                  Njettiness::AxesMode axes_mode,
                  Njettiness::MeasureMode measure_mode)
-   : _njettinessFinder(axes_mode, measure_mode, 0), _N(N) {}
-
-   // One parameter argument
-   // (for unnormalized_measure, para1=beta)
+   : _njettinessFinder(axes_mode, measure_mode, 0), _N(N) {
+      _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.");
+   }
+   
+   /// \deprecated
+   /// Construcotr for one parameter argument
+   /// (for unnormalized_measure, para1=beta)
    Nsubjettiness(int N,
                  Njettiness::AxesMode axes_mode,
                  Njettiness::MeasureMode measure_mode,
                  double para1)
-   : _njettinessFinder(axes_mode, measure_mode, 1, para1), _N(N) {}
-
-   // Two parameter arguments
-   // (for normalized_measure, para1=beta, para2=R0)
-   // (for unnormalized_cutoff_measure, para1=beta, para2=Rcutoff)
+   : _njettinessFinder(axes_mode, measure_mode, 1, para1), _N(N) {
+      _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.");
+   }
+   
+   /// \deprecated
+   /// Constructor for two parameter arguments
+   /// (for normalized_measure, para1=beta, para2=R0)
+   /// (for unnormalized_cutoff_measure, para1=beta, para2=Rcutoff)
    Nsubjettiness(int N,
                  Njettiness::AxesMode axes_mode,
@@ -101,8 +180,11 @@
                  double para1,
                  double para2)
-   : _njettinessFinder(axes_mode, measure_mode, 2, para1, para2), _N(N) {}
-
-   // Three parameter arguments
-   // (for unnormalized_cutoff_measure, para1=beta, para2=R0, para3=Rcutoff)
+   : _njettinessFinder(axes_mode, measure_mode, 2, para1, para2), _N(N) {
+      _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.");
+   }
+   
+   /// \deprecated
+   /// Constructor for three parameter arguments
+   /// (for unnormalized_cutoff_measure, para1=beta, para2=R0, para3=Rcutoff)
    Nsubjettiness(int N,
                  Njettiness::AxesMode axes_mode,
@@ -111,8 +193,11 @@
                  double para2,
                  double para3)
-   : _njettinessFinder(axes_mode, measure_mode, 3, para1, para2, para3), _N(N) {}
-
-   // Old constructor for backwards compatibility with v1.0,
-   // where normalized_cutoff_measure was the only option
+   : _njettinessFinder(axes_mode, measure_mode, 3, para1, para2, para3), _N(N) {
+      _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.");
+   }
+   
+   /// \deprecated
+   /// Old constructor for backwards compatibility with v1.0,
+   /// where normalized_cutoff_measure was the only option
    Nsubjettiness(int N,
                  Njettiness::AxesMode axes_mode,
@@ -120,57 +205,23 @@
                  double R0,
                  double Rcutoff=std::numeric_limits<double>::max())
-   : _njettinessFinder(axes_mode, NormalizedCutoffMeasure(beta,R0,Rcutoff)), _N(N) {}
-   
-   /// returns tau_N, measured on the constituents of this jet 
-   double result(const PseudoJet& jet) const;
-
-   /// returns components of tau_N, so that user can find individual tau values.
-   TauComponents component_result(const PseudoJet& jet) const;
-   
-   /// returns current axes found by result() calculation
-   std::vector<fastjet::PseudoJet> currentAxes() const {
-      return _njettinessFinder.currentAxes();
-   }
-
-   /// returns seed axes used for onepass minimization (otherwise same as currentAxes)
-   std::vector<fastjet::PseudoJet> seedAxes() const {
-      return _njettinessFinder.seedAxes();
-   }
-   
-   /// returns subjet regions found by result() calculation (these have valid constituents)
-   /// Note that the axes and the subjets are not the same
-   std::vector<fastjet::PseudoJet> currentSubjets() const {
-      return _njettinessFinder.currentJets();
-   }
-
-   /// returns components of tau_N without recalculating anything
-   TauComponents currentTauComponents() const {
-      return _njettinessFinder.currentTauComponents();
-   }
-   
-   // To set axes for manual use
-   void setAxes(const std::vector<fastjet::PseudoJet> & myAxes) {
-      // Cross check that manual axes are being used is in Njettiness
-    	_njettinessFinder.setAxes(myAxes);
-   }
-   
-   
-private:
-   
-   Njettiness _njettinessFinder; // TODO:  should muck with this so result can be const without this mutable
-   int _N;
-
+   : _njettinessFinder(axes_mode, NormalizedCutoffMeasure(beta,R0,Rcutoff)), _N(N) {
+      _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.");
+   }
+   
 };
 
 
-//------------------------------------------------------------------------
+///------------------------------------------------------------------------
 /// \class NsubjettinessRatio
-// NsubjettinessRatio uses the results from Nsubjettiness to calculate the ratio
-// tau_N/tau_M, where N and M are specified by the user. The ratio of different tau values
-// is often used in analyses, so this class is helpful to streamline code.
+/// \brief Implements ratios of N-subjettiness jet shapes
+///
+/// NsubjettinessRatio uses the results from Nsubjettiness to calculate the ratio
+/// tau_N/tau_M, where N and M are specified by the user. The ratio of different tau values
+/// is often used in analyses, so this class is helpful to streamline code.  Note that
+/// manual axis mode is not supported
 class NsubjettinessRatio : public FunctionOfPseudoJet<double> {
 public:
 
-   // Main constructor.  Apart from specifying both N and M, the same options as Nsubjettiness
+   /// Main constructor.  Apart from specifying both N and M, the same options as Nsubjettiness
    NsubjettinessRatio(int N,
                       int M,
@@ -178,8 +229,27 @@
                       const MeasureDefinition & measure_def)
    : _nsub_numerator(N,axes_def,measure_def),
-   _nsub_denominator(M,axes_def,measure_def) {}
-   
-   // Alternative constructor with enums and parameters
-   // Again, likely to be removed
+   _nsub_denominator(M,axes_def,measure_def) {
+      if (axes_def.needsManualAxes()) {
+         throw Error("NsubjettinessRatio does not support ManualAxes mode.");
+      }
+   }
+
+   /// Returns tau_N/tau_M based off the input jet using result function from Nsubjettiness
+   double result(const PseudoJet& jet) const;
+
+private: 
+
+   Nsubjettiness _nsub_numerator;   ///< Function for numerator
+   Nsubjettiness _nsub_denominator; ///< Function for denominator
+
+public:
+   
+   // The following interfaces are included for backwards compatibility, but no longer recommended.
+   // They may be deprecated at some point.
+   
+   /// \deprecated
+   /// Old-style constructor for zero arguments
+   /// Alternative constructor with enums and parameters
+   /// Again, likely to be removed
    NsubjettinessRatio(int N,
                       int M,
@@ -188,6 +258,7 @@
    : _nsub_numerator(N, axes_mode, measure_mode),
    _nsub_denominator(M, axes_mode, measure_mode) {}
-
-   
+   
+   /// \deprecated
+   /// Old-style constructor for one argument
    NsubjettinessRatio(int N,
                       int M,
@@ -197,5 +268,7 @@
    : _nsub_numerator(N, axes_mode, measure_mode, para1),
    _nsub_denominator(M, axes_mode, measure_mode, para1) {}
-
+   
+   /// \deprecated
+   /// Old-style constructor for 2 arguments
    NsubjettinessRatio(int N,
                       int M,
@@ -207,4 +280,6 @@
    _nsub_denominator(M, axes_mode, measure_mode, para1, para2) {}
    
+   /// \deprecated
+   /// Old-style constructor for 3 arguments
    NsubjettinessRatio(int N,
                       int M,
@@ -217,12 +292,5 @@
    _nsub_denominator(M, axes_mode, measure_mode, para1, para2, para3) {}
 
-   //returns tau_N/tau_M based off the input jet using result function from Nsubjettiness
-   double result(const PseudoJet& jet) const;
-
-private: 
-
-   Nsubjettiness _nsub_numerator;
-   Nsubjettiness _nsub_denominator;
-
+   
 };
 
