Changeset 49234af in git for external/fastjet/JetDefinition.hh

Timestamp:

Dec 9, 2014, 1:27:13 PM (10 years ago)

Author:

Michele <michele.selvaggi@…>

Branches:

ImprovedOutputFile, Timing, dual_readout, llp, master

Children:

37deb3b, 9e991f8

Parents:

f6b6ee7 (diff), e7e90df (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.

Message:

Merge branch 'TestFastJet310b1'

File:

• external/fastjet/JetDefinition.hh (modified) (19 diffs)

external/fastjet/JetDefinition.hh

@@ -1 @@
-//STARTHEADER
-// $Id: JetDefinition.hh 2687 2011-11-14 11:17:51Z soyez $
-//
-// Copyright (c) 2005-2011, Matteo Cacciari, Gavin P. Salam and Gregory Soyez
+#ifndef __FASTJET_JETDEFINITION_HH__
+#define __FASTJET_JETDEFINITION_HH__
+
+//FJSTARTHEADER
+// $Id: JetDefinition.hh 3677 2014-09-09 22:45:25Z soyez $
+//
+// Copyright (c) 2005-2014, Matteo Cacciari, Gavin P. Salam and Gregory Soyez
 //
 //----------------------------------------------------------------------
@@ -13 +16 @@
 //
 //  The algorithms that underlie FastJet have required considerable
-//  development and are described in hep-ph/0512210. If you use
+//  development. They are described in the original FastJet paper,
+//  hep-ph/0512210 and in the manual, arXiv:1111.6097. If you use
 //  FastJet as part of work towards a scientific publication, please
-//  include a citation to the FastJet paper.
+//  quote the version you use and include a citation to the manual and
+//  optionally also to hep-ph/0512210.
 //
 //  FastJet is distributed in the hope that it will be useful,
@@ -25 +30 @@
 //  along with FastJet. If not, see <http://www.gnu.org/licenses/>.
 //----------------------------------------------------------------------
-//ENDHEADER
-
-#ifndef __FASTJET_JETDEFINITION_HH__
-#define __FASTJET_JETDEFINITION_HH__
+//FJENDHEADER
 
 #include<cassert>
@@ -47 +49 @@
 /// clustering events with kt and cambridge style algorithms.
 enum Strategy {
-  /// fastest form about 500..10^4
+  /// Like N2MHTLazy9 in a number of respects, but does not calculate
+  /// ghost-ghost distances and so does not carry out ghost-ghost
+  /// recombination. 
+  ///
+  /// If you want active ghosted areas, then this is only suitable for
+  /// use with the anti-kt algorithm (or genkt with negative p), and
+  /// does not produce any pure ghost jets. If used with active areas
+  /// with Kt or Cam algorithms it will actually produce a passive
+  /// area.
+  /// 
+  /// Particles are deemed to be ghosts if their pt is below a
+  /// threshold (currently 1e-50, hard coded as ghost_limit in
+  /// LazyTiling9SeparateGhosts).
+  ///
+  /// Currently for events with a couple of thousand normal particles
+  /// and O(10k) ghosts, this can be quicker than N2MHTLazy9, which
+  /// would otherwise be the best strategy. 
+  ///
+  /// New in FJ3.1
+  N2MHTLazy9AntiKtSeparateGhosts   = -10, 
+  /// only looks into a neighbouring tile for a particle's nearest
+  /// neighbour (NN) if that particle's in-tile NN is further than the
+  /// distance to the edge of the neighbouring tile. Uses tiles of
+  /// size R and a 3x3 tile grid around the particle.
+  /// New in FJ3.1
+  N2MHTLazy9   = -7, 
+  /// Similar to N2MHTLazy9, but uses tiles of size R/2 and a 5x5 tile
+  /// grid around the particle.
+  /// New in FJ3.1
+  N2MHTLazy25   = -6, 
+  /// Like to N2MHTLazy9 but uses slightly different optimizations,
+  /// e.g. for calculations of distance to nearest tile; as of
+  /// 2014-07-18 it is slightly slower and not recommended for
+  /// production use. To considered deprecated.
+  /// New in FJ3.1
+  N2MHTLazy9Alt   = -5, 
+  /// faster that N2Tiled above about 500 particles; differs from it
+  /// by retainig the di(closest j) distances in a MinHeap (sort of
+  /// priority queue) rather than a simple vector. 
   N2MinHeapTiled   = -4, 
   /// fastest from about 50..500
@@ -57 +97 @@
   /// worse even than the usual N^3 algorithms
   N3Dumb      =  0, 
-  /// automatic selection of the best (based on N)
+  /// automatic selection of the best (based on N), including 
+  /// the LazyTiled strategies that are new to FJ3.1
   Best        =  1, 
   /// best of the NlnN variants -- best overall for N>10^4.
@@ -79 +120 @@
   /// (Does not work for R>=2pi)
   NlnNCam      = 12, // 2piMultD
+  /// the automatic strategy choice that was being made in FJ 3.0
+  /// (restricted to strategies that were present in FJ 3.0)
+  BestFJ30     =  21, 
   /// the plugin has been used...
   plugin_strategy = 999
@@ -87 +131 @@
 /// \enum JetAlgorithm
 /// the various families of jet-clustering algorithm
+//
+// [Remember to update the "is_spherical()" routine if any further
+// spherical algorithms are added to the list below]
 enum JetAlgorithm {
   /// the longitudinally invariant kt algorithm
@@ -102 +149 @@
   /// where p = extra_param()
   genkt_algorithm=3, 
-  /// a version of cambridge with a special distance measure for particles
-  /// whose pt is < extra_param()
+  /// a version of cambridge with a special distance measure for
+  /// particles whose pt is < extra_param(); this is not usually
+  /// intended for end users, but is instead automatically selected
+  /// when requesting a passive Cambridge area.
   cambridge_for_passive_algorithm=11,
   /// a version of genkt with a special distance measure for particles
   /// whose pt is < extra_param() [relevant for passive areas when p<=0]
+  /// ***** NB: THERE IS CURRENTLY NO IMPLEMENTATION FOR THIS ALG *******
   genkt_for_passive_algorithm=13, 
   //.................................................................
@@ -131 +181 @@
 
 //======================================================================
-/// the various recombination schemes
+/// The various recombination schemes
+///
+/// Note that the schemes that recombine with non-linear weighting of
+/// the directions (e.g. pt2, winner-takes-all) are collinear safe
+/// only for algorithms with a suitable ordering of the
+/// recombinations: orderings in which, for particles of comparable
+/// energies, small-angle clusterings take place before large-angle
+/// clusterings. This property is satisfied by all gen-kt algorithms.
+/// 
 enum RecombinationScheme {
   /// summing the 4-momenta
@@ -153 +211 @@
   /// no preprocessing
   BIpt2_scheme=6,
+  /// pt-based Winner-Takes-All (WTA) recombination: the
+  /// result of the recombination has the rapidity, azimuth and mass
+  /// of the the PseudoJet with the larger pt, and a pt equal to the
+  /// sum of the two pt's
+  WTA_pt_scheme=7,
+  /// mod-p-based Winner-Takes-All (WTA) recombination: the result of
+  /// the recombination gets the 3-vector direction and mass of the
+  /// PseudoJet with the larger |3-momentum| (modp), and a
+  /// |3-momentum| equal to the scalar sum of the two |3-momenta|.
+  WTA_modp_scheme=8,
+  // Energy-ordering can lead to dangerous situations with particles at
+  // rest. We instead implement the WTA_modp_scheme
+  //
+  // // energy-based Winner-Takes-All (WTA) recombination: the result of
+  // // the recombination gets the 3-vector direction and mass of the
+  // // PseudoJet with the larger energy, and an energy equal to the
+  // // to the sum of the two energies
+  // WTA_E_scheme=8,
   /// for the user's external scheme
   external_scheme = 99
@@ -244 +320 @@
                 const Recombiner * recombiner_in,
                 Strategy strategy_in = Best) {
-    *this = JetDefinition(jet_algorithm_in, R_in, external_scheme, strategy_in);
+    *this = JetDefinition(jet_algorithm_in, R_in, xtra_param_in, external_scheme, strategy_in);
     _recombiner = recombiner_in;
-    set_extra_param(xtra_param_in);
   }
 
@@ -284 +359 @@
                 RecombinationScheme recomb_scheme_in = E_scheme,
                 int nparameters_in = 1);
+
+  /// cluster the supplied particles and returns a vector of resulting
+  /// jets, sorted by pt (or energy in the case of spherical,
+  /// i.e. e+e-, algorithms). This routine currently only makes
+  /// sense for "inclusive" type algorithms.
+  template <class L> 
+  std::vector<PseudoJet> operator()(const std::vector<L> & particles) const;
   
   /// R values larger than max_allowable_R are not allowed.
@@ -297 +379 @@
 
   /// set the recombiner class to the one provided
+  ///
+  /// Note that in order to associate to a jet definition a recombiner
+  /// from another jet definition, it is strongly recommended to use
+  /// the set_recombiner(const JetDefinition &) method below. The
+  /// latter correctly handles the situations where the jet definition
+  /// owns the recombiner (i.e. where delete_recombiner_when_unused
+  /// has been called). In such cases, using set_recombiner(const
+  /// Recombiner *) may lead to memory corruption.
   void set_recombiner(const Recombiner * recomb) {
-    if (_recombiner_shared()) _recombiner_shared.reset(recomb);
+    if (_shared_recombiner()) _shared_recombiner.reset(recomb);
     _recombiner = recomb;
     _default_recombiner = DefaultRecombiner(external_scheme);
   }
 
+  /// set the recombiner to be the same as the one of 'other_jet_def'
+  ///
+  /// Note that this is the recommended method to associate to a jet
+  /// definition the recombiner from another jet definition. Compared
+  /// to the set_recombiner(const Recombiner *) above, it correctly
+  /// handles the case where the jet definition owns the recombiner
+  /// (i.e. where delete_recombiner_when_unused has been called)
+  void set_recombiner(const JetDefinition &other_jet_def);
+
   /// calling this tells the JetDefinition to handle the deletion of
-  /// the recombiner when it is no longer used
+  /// the recombiner when it is no longer used. (Should not be called
+  /// if the recombiner was initialised from a JetDef whose recombiner
+  /// was already scheduled to delete itself - memory handling will
+  /// already be automatic across both JetDef's in that case).
   void delete_recombiner_when_unused();
 
@@ -310 +412 @@
   const Plugin * plugin() const {return _plugin;};
 
-  /// allows to let the JetDefinition handle the deletion of the
+  /// calling this causes the JetDefinition to handle the deletion of the
   /// plugin when it is no longer used
   void delete_plugin_when_unused();
@@ -333 +435 @@
   void set_extra_param(double xtra_param) {_extra_param = xtra_param;}
 
-  /// return a pointer to the currently defined recombiner. 
+  /// returns a pointer to the currently defined recombiner. 
   ///
   /// Warning: the pointer may be to an internal recombiner (for
@@ -347 +449 @@
 
   /// returns true if the current jet definitions shares the same
-  /// recombiner as teh one passed as an argument
+  /// recombiner as the one passed as an argument
   bool has_same_recombiner(const JetDefinition &other_jd) const;
+
+  /// returns true if the jet definition involves an algorithm
+  /// intended for use on a spherical geometry (e.g. e+e- algorithms,
+  /// as opposed to most pp algorithms, which use a cylindrical,
+  /// rapidity-phi geometry).
+  bool is_spherical() const;
 
   /// return a textual description of the current jet definition 
   std::string description() const;
 
+  /// returns a description not including the recombiner information
+  std::string description_no_recombiner() const;
+
+  /// a short textual description of the algorithm jet_alg
+  static std::string algorithm_description(const JetAlgorithm jet_alg);
+
+  /// the number of parameters associated to a given jet algorithm
+  static unsigned int n_parameters_for_algorithm(const JetAlgorithm jet_alg);
 
 public:
@@ -462 +578 @@
     virtual bool exclusive_sequence_meaningful() const {return false;}
 
+    /// returns true if the plugin implements an algorithm intended
+    /// for use on a spherical geometry (e.g. e+e- algorithms, as
+    /// opposed to most pp algorithms, which use a cylindrical,
+    /// rapidity-phi geometry).
+    virtual bool is_spherical() const {return false;}
+
     /// a destructor to be replaced if necessary in derived classes...
     virtual ~Plugin() {};
@@ -481 +603 @@
   DefaultRecombiner _default_recombiner;
   const Recombiner * _recombiner;
-  SharedPtr<const Recombiner> _recombiner_shared;
+  SharedPtr<const Recombiner> _shared_recombiner;
 
 };
@@ -516 +638 @@
 
 
-
-
-
 FASTJET_END_NAMESPACE
 
+// include ClusterSequence which includes the implementation of the 
+// templated JetDefinition::operator()(...) member
+#include "fastjet/ClusterSequence.hh"
+
+
 #endif // __FASTJET_JETDEFINITION_HH__