Index: external/fastjet/contribs/Nsubjettiness/Njettiness.hh
===================================================================
--- external/fastjet/contribs/Nsubjettiness/Njettiness.hh	(revision 35cdc461e095e63247ab9dded070d76bc2c888e2)
+++ external/fastjet/contribs/Nsubjettiness/Njettiness.hh	(revision 8713dee253b44fe1d26e1aad36beeb66152508c4)
@@ -5,5 +5,5 @@
 //  Jesse Thaler, Ken Van Tilburg, Christopher K. Vermilion, and TJ Wilkason
 //
-//  $Id: Njettiness.hh 670 2014-06-06 01:24:42Z jthaler $
+//  $Id: Njettiness.hh 822 2015-06-15 23:52:57Z jthaler $
 //----------------------------------------------------------------------
 // This file is part of FastJet contrib.
@@ -27,7 +27,7 @@
 
 
-#include "MeasureFunction.hh"
-#include "AxesFinder.hh"
-#include "NjettinessDefinition.hh"
+#include "MeasureDefinition.hh"
+#include "AxesDefinition.hh"
+#include "TauComponents.hh"
 
 #include "fastjet/PseudoJet.hh"
@@ -42,5 +42,73 @@
 
 namespace contrib {
-   
+
+/** \mainpage Nsubjettiness Documentation
+ *
+ * These Doxygen pages provide automatically generated documentation for the
+ * Nsubjettiness FastJet contrib.  This documentation is being slowly improved.
+ *
+ * \section core_classes Core Classes
+ *
+ * - Nsubjettiness:  Calculating N-subjettiness jet shapes
+ * - NsubjettinessRatio:  Calculating N-subjettiness ratios
+ * - XConePlugin:  Running the XCone jet algorithm
+ * - NjettinessPlugin:  Running generic N-jettiness as a jet algorithm
+ *
+ * \subsection core_classes_helper Helper Classes for Core
+ * - Njettiness:  Core code for all N-(sub)jettiness calculations
+ * - NjettinessExtras:  Way to access additional N-jettiness information
+ * - TauComponents:  Output format for all N-(sub)jettiness information
+ * - TauPartition:  Access to N-(sub)jettiness partitioning information
+ * - PseudoXConePlugin:  Testing code to compare to XConePlugin (doesn't use one-pass minimization)
+ *
+ * \section axes_classes Axes Definitions
+ *
+ * \subsection axes_classes_base Base Classes
+ * - AxesDefinition:  Defines generic axes definition
+ * - ExclusiveJetAxes:  Axes finder from exclusive jet algorithm
+ * - ExclusiveCombinatorialJetAxes:  Axes finder from exclusive jet algorithm (with extra axes to test combinatoric options)
+ * - HardestJetAxes:  Axes finder from inclusive jet algorithm
+ *
+ * \subsection axes_classes_derived Derived Classes
+ *
+ * \b OnePass means iterative improvement to a (local) N-(sub)jettiness minimum.
+ *
+ * \b MultiPass means using multiple random seed inputs
+ *
+ * \b Comb means checking N + Nextra choose N combinatorial options
+ *
+ * - KT_Axes / OnePass_KT_Axes:  Axes from exclusive kT
+ * - CA_Axes / OnePass_CA_Axes:  Axes from exclusive Cambridge/Aachen
+ * - AntiKT_Axes / OnePass_AntiKT_Axes:  Axes from inclusive anti-kT
+ * - WTA_KT_Axes / OnePass_WTA_KT_Axes:  Axes from exclusive kT, using winner-take-all recombination
+ * - WTA_CA_Axes / OnePass_WTA_CA_Axes:  Axes from exclusive CA, using winner-take-all recombination
+ *
+ * - GenET_GenKT_Axes / OnePass_GenET_GenKT_Axes / Comb_GenET_GenKT_Axes:  Axes from exclusive generalized kt, with generalized Et recombination
+ * - WTA_GenKT_Axes / OnePass_WTA_GenKT_Axes / Comb_WTA_GenKT_Axes:  Axes from exclusive generalized kt, with winner-take-all recombination
+ *
+ * - Manual_Axes / OnePass_Manual_Axes / MultiPass_Manual_Axes:  Use manual axes
+ * - MultiPass_Axes:  Multiple passes with random input seeds
+ *
+ * \subsection axes_classes_helper Helper Classes for Axes
+ * - GeneralEtSchemeRecombiner:  Generalized Et-scheme recombiner
+ * - WinnerTakeAllRecombiner:  Winner-take-all recombiner (similar functionality now in FastJet 3.1)
+ * - JetDefinitionWrapper:  Wrapper for Jet Definitions to handle memory management
+ *
+ * \section measure_classes Measure Definitions
+ *
+ * \subsection measure_classes_bases Base Classes
+ * - MeasureDefinition:  Defines generic measures
+ * - DefaultMeasure:  Base class for the original N-subjettiness measures
+ *
+ * \subsection measure_classes_derived Derived Classes
+ * - NormalizedMeasure / UnnormalizedMeasure / NormalizedCutoffMeasure / UnnormalizedCutoffMeasure : Variants on the default N-subjettiness measure.
+ * - ConicalMeasure: Similar to default measure, but intended as N-jettiness event shape
+ * - ConicalGeometricMeasure / XConeMeasure:  Measure used in XCone jet algorithm
+ * - OriginalGeometricMeasure / ModifiedGeometricMeasure:  Dot product measures useful for theoretical calcualtions
+ *
+ * \subsection measure_classes_helper Helper Classes for Measures
+ * - LightLikeAxis : Defines light-like axis
+ */
+
 ///////
 //
@@ -49,15 +117,88 @@
 ///////
 
-//------------------------------------------------------------------------
+///------------------------------------------------------------------------
 /// \class Njettiness
-// Njettiness uses AxesFinder and MeasureFunction together in order to find tau_N for the event. The user specifies
-// which AxesFinder and which MeasureFunction to use in the calculation, and then Njettiness returns tau_N for the event.
-// It also can return information about the axes and jets it used in the calculation, as well as information about 
-// how the event was partitioned.
+/// \brief Core class for N-(sub)jettiness calculations
+///
+/**
+ * The N-jettiness event shape.
+ *
+ * This is the core class used to perform N-jettiness jet finding (via NjettinessPlugin or XConePluggin)
+ * as well as find the N-subjettiness jet shape (via Nsubjettiness).
+ *
+ * In general, the user should never need to call this object.  In addition, its API should not be considered
+ * fixed, since all code improvements effectively happen from reorganizing this class.
+ *
+ * Njettiness uses AxesDefinition and MeasureDefinition together in order to find tau_N for the event.
+ * It also can return information about the axes and jets it used in the calculation, as well as
+ * information about how the event was partitioned.
+ */
 class Njettiness {
 public:
    
-   // The various axes choices available to the user
-   // It is recommended to use AxesDefinition instead of these.
+   /// Main constructor that uses AxesMode and MeasureDefinition to specify measure
+   /// Unlike Nsubjettiness or NjettinessPlugin, the value N is not chosen
+   Njettiness(const AxesDefinition & axes_def, const MeasureDefinition & measure_def);
+
+   /// Destructor
+   ~Njettiness() {};
+   
+   /// setAxes for Manual mode
+   void setAxes(const std::vector<fastjet::PseudoJet> & myAxes);
+   
+   /// Calculates and returns all TauComponents that user would want.
+   /// This information is stored in _current_tau_components for later access as well.
+   TauComponents getTauComponents(unsigned n_jets, const std::vector<fastjet::PseudoJet> & inputJets) const;
+
+   /// Calculates the value of N-subjettiness,
+   /// but only returns the tau value from _current_tau_components
+   double getTau(unsigned n_jets, const std::vector<fastjet::PseudoJet> & inputJets) const {
+      return getTauComponents(n_jets, inputJets).tau();
+   }
+
+   /// Return all relevant information about tau components
+   TauComponents currentTauComponents() const {return _current_tau_components;}
+   /// Return axes found by getTauComponents.
+   std::vector<fastjet::PseudoJet> currentAxes() const { return _currentAxes;}
+   /// Return seedAxes used if onepass minimization (otherwise, same as currentAxes)
+   std::vector<fastjet::PseudoJet> seedAxes() const { return _seedAxes;}
+   /// Return jet partition found by getTauComponents.
+   std::vector<fastjet::PseudoJet> currentJets() const {return _currentPartition.jets();}
+   /// Return beam partition found by getTauComponents.
+   fastjet::PseudoJet currentBeam() const {return _currentPartition.beam();}
+   /// Return beam partition found by getTauComponents.
+   TauPartition currentPartition() const {return _currentPartition;}
+   
+
+private:
+   
+   /// AxesDefinition to use.  Implemented as SharedPtrs to avoid memory management headaches
+   SharedPtr<const AxesDefinition> _axes_def;
+   /// MeasureDefinition to use.  Implemented as SharedPtrs to avoid memory management headaches
+   SharedPtr<const MeasureDefinition> _measure_def;
+
+   
+   // Information about the current information
+   // Defined as mutables, so user should be aware that these change when getTau is called.
+   // TODO:  These are not thread safe and should be fixed somehow
+   mutable TauComponents _current_tau_components; //automatically set to have components of 0; these values will be set by the getTau function call
+   mutable std::vector<fastjet::PseudoJet> _currentAxes; //axes found after minimization
+   mutable std::vector<fastjet::PseudoJet> _seedAxes; // axes used prior to minimization (if applicable)
+   mutable TauPartition _currentPartition; //partitioning information
+
+   /// Warning if the user tries to use v1.0.3 measure style.
+   static LimitedWarning _old_measure_warning;
+   /// Warning if the user tries to use v1.0.3 axes style.
+   static LimitedWarning _old_axes_warning;
+
+   
+public:
+   
+   // These interfaces are included for backwards compability, and will be deprecated in a future release (scheduled for deletion in v3.0)
+   
+   /// \deprecated
+   /// Deprecated enum to determine axes mode
+   /// The various axes choices available to the user
+   /// It is recommended to use AxesDefinition instead of these.
    enum AxesMode {
       kt_axes,             // exclusive kt axes
@@ -69,20 +210,17 @@
       onepass_ca_axes,     // one-pass minimization from ca starting point
       onepass_antikt_0p2_axes,  // one-pass minimization from antikt-0.2 starting point
-      onepass_wta_kt_axes, //one-pass minimization of WTA axes with kt 
-      onepass_wta_ca_axes, //one-pass minimization of WTA axes with ca 
+      onepass_wta_kt_axes, //one-pass minimization of WTA axes with kt
+      onepass_wta_ca_axes, //one-pass minimization of WTA axes with ca
       min_axes,            // axes that minimize N-subjettiness (100 passes by default)
       manual_axes,         // set your own axes with setAxes()
       onepass_manual_axes  // one-pass minimization from manual starting point
-      //  These options are commented out because they have not been fully tested
-      //      wta2_kt_axes,        // Winner Take All (alpha = 2) with kt
-      //      wta2_ca_axes,         // Winner Take All (alpha = 2) with CA
-      //      onepass_wta2_kt_axes, //one-pass minimization of WTA (alpha = 2) axes with kt
-      //      onepass_wta2_ca_axes, //one-pass minimization of WTA (alpha = 2) axes with ca
    };
-
-   // The measures available to the user.
-   // "normalized_cutoff_measure" was the default in v1.0 of Nsubjettiness
-   // "unnormalized_measure" is now the recommended default usage
-   // But it is recommended to use MeasureDefinition instead of these.
+   
+   /// \deprecated
+   /// Deprecated enum to determine measure mode
+   /// The measures available to the user.
+   /// "normalized_cutoff_measure" was the default in v1.0 of Nsubjettiness
+   /// "unnormalized_measure" is now the recommended default usage
+   /// But it is recommended to use MeasureDefinition instead of these.
    enum MeasureMode {
       normalized_measure,           //default normalized measure
@@ -93,14 +231,12 @@
       geometric_cutoff_measure      //geometric measure with explicit Rcutoff
    };
-
-   // Main constructor that uses AxesMode and MeasureDefinition to specify measure
-   // Unlike Nsubjettiness or NjettinessPlugin, the value N is not chosen
-   Njettiness(const AxesDefinition & axes_def, const MeasureDefinition & measure_def);
-
-   // Intermediate constructor (needed to enable v1.0.3 backwards compatibility?)
+   
+   /// \deprecated
+   /// Intermediate constructor (needed to enable v1.0.3 backwards compatibility?)
    Njettiness(AxesMode axes_mode, const MeasureDefinition & measure_def);
-
-   // Alternative constructor which takes axes/measure information as enums with measure parameters
-   // This version is not recommended
+   
+   /// \deprecated
+   /// Old-style constructor which takes axes/measure information as enums with measure parameters
+   /// This version absolutely is not recommended
    Njettiness(AxesMode axes_mode,
               MeasureMode measure_mode,
@@ -110,66 +246,12 @@
               double para3 = std::numeric_limits<double>::quiet_NaN())
    : _axes_def(createAxesDef(axes_mode)), _measure_def(createMeasureDef(measure_mode, num_para, para1, para2, para3)) {
-      setMeasureFunctionAndAxesFinder();  // call helper function to do the hard work
    }
-
-   // destructor
-   ~Njettiness() {};
-   
-   // setAxes for Manual mode
-   void setAxes(const std::vector<fastjet::PseudoJet> & myAxes);
-   
-   // Calculates and returns all TauComponents that user would want.
-   // This information is stored in _current_tau_components for later access as well.
-   TauComponents getTauComponents(unsigned n_jets, const std::vector<fastjet::PseudoJet> & inputJets) const;
-
-   // Calculates the value of N-subjettiness,
-   // but only returns the tau value from _current_tau_components
-   double getTau(unsigned n_jets, const std::vector<fastjet::PseudoJet> & inputJets) const {
-      return getTauComponents(n_jets, inputJets).tau();
-   }
-
-   // Return all relevant information about tau components
-   TauComponents currentTauComponents() const {return _current_tau_components;}
-   // Return axes found by getTauComponents.
-   std::vector<fastjet::PseudoJet> currentAxes() const { return _currentAxes;}
-   // Return seedAxes used if onepass minimization (otherwise, same as currentAxes)
-   std::vector<fastjet::PseudoJet> seedAxes() const { return _seedAxes;}
-   // Return jet partition found by getTauComponents.
-   std::vector<fastjet::PseudoJet> currentJets() const {return _currentJets;}
-   // Return beam partition found by getTauComponents.
-   fastjet::PseudoJet currentBeam() const {return _currentBeam;}
-   
-   // partition inputs by Voronoi (each vector stores indices corresponding to inputJets)
-   std::vector<std::list<int> > getPartitionList(const std::vector<fastjet::PseudoJet> & inputJets) const;
-
-private:
-   
-   // Information about Axes and Measures to be Used
-   // Implemented as SharedPtrs to avoid memory management headaches
-   SharedPtr<const AxesDefinition> _axes_def;
-   SharedPtr<const MeasureDefinition> _measure_def;
-   
-   // The chosen axes/measure mode workers
-   // Implemented as SharedPtrs to avoid memory management headaches
-   // TODO: make into a SharedPtr<const AxesFinder>?
-   SharedPtr<MeasureFunction> _measureFunction;  // The chosen measure
-   SharedPtr<AxesFinder> _startingAxesFinder;    // The initial axes finder
-   SharedPtr<AxesFinder> _finishingAxesFinder;   // A possible minimization step
-   
-   // Information about the current information
-   // Defined as mutables, so user should be aware that these change when getTau is called.
-   mutable TauComponents _current_tau_components; //automatically set to have components of 0; these values will be set by the getTau function call
-   mutable std::vector<fastjet::PseudoJet> _currentAxes; //axes found after minimization
-   mutable std::vector<fastjet::PseudoJet> _seedAxes; // axes used prior to minimization (if applicable)
-   mutable std::vector<fastjet::PseudoJet> _currentJets; //partitioning information
-   mutable fastjet::PseudoJet _currentBeam; //return beam, if requested
-   
-   // created separate function to set MeasureFunction and AxesFinder in order to keep constructor cleaner.
-   void setMeasureFunctionAndAxesFinder();
-   
-   // Convert old style enums into new style MeasureDefinition
+  
+   /// \deprecated
+   /// Convert old style enums into new style MeasureDefinition
    AxesDefinition* createAxesDef(AxesMode axes_mode) const;
    
-   // Convert old style enums into new style MeasureDefinition
+   /// \deprecated
+   /// Convert old style enums into new style MeasureDefinition
    MeasureDefinition* createMeasureDef(MeasureMode measure_mode, int num_para, double para1, double para2, double para3) const;
 
