JetDefinition.hh

//STARTHEADER
// $Id: JetDefinition.hh 1850 2011-01-25 19:33:24Z soyez $
//
// Copyright (c) 2005-2006, Matteo Cacciari and Gavin Salam
//
//----------------------------------------------------------------------
// This file is part of FastJet.
//
//  FastJet is free software; you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation; either version 2 of the License, or
//  (at your option) any later version.
//
//  The algorithms that underlie FastJet have required considerable
//  development and are described in hep-ph/0512210. If you use
//  FastJet as part of work towards a scientific publication, please
//  include a citation to the FastJet paper.
//
//  FastJet is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with FastJet; if not, write to the Free Software
//  Foundation, Inc.:
//      59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
//----------------------------------------------------------------------
//ENDHEADER

#ifndef __FASTJET_JETDEFINITION_HH__
#define __FASTJET_JETDEFINITION_HH__

#include<cassert>
#include "fastjet/internal/numconsts.hh"
#include "fastjet/PseudoJet.hh"
#include<string>
#include<memory>

FASTJET_BEGIN_NAMESPACE      // defined in fastjet/internal/base.hh

//  NB: (implemented in ClusterSequence.cc but defined here because
//  this is a visible location)
std::string fastjet_version_string();

//======================================================================
enum Strategy {
  N2MinHeapTiled   = -4, 
  N2Tiled     = -3, 
  N2PoorTiled = -2, 
  N2Plain     = -1, 
  N3Dumb      =  0, 
  Best        =  1, 
  NlnN        =  2, 
  NlnN3pi     =  3, 
  NlnN4pi     =  4,
  NlnNCam4pi   = 14,
  NlnNCam2pi2R = 13,
  NlnNCam      = 12, // 2piMultD
  plugin_strategy = 999
};


//======================================================================
enum JetAlgorithm {
  kt_algorithm=0,
  cambridge_algorithm=1,
  antikt_algorithm=2, 
  genkt_algorithm=3, 
  cambridge_for_passive_algorithm=11,
  genkt_for_passive_algorithm=13, 
  //.................................................................
  ee_kt_algorithm=50,
  ee_genkt_algorithm=53,
  //.................................................................
  plugin_algorithm = 99
};

typedef JetAlgorithm JetFinder;

const JetAlgorithm aachen_algorithm = cambridge_algorithm;
const JetAlgorithm cambridge_aachen_algorithm = cambridge_algorithm;

//======================================================================
enum RecombinationScheme {
  E_scheme=0,
  pt_scheme=1,
  pt2_scheme=2,
  Et_scheme=3,
  Et2_scheme=4,
  BIpt_scheme=5,
  BIpt2_scheme=6,
  external_scheme = 99
};




// forward declaration, needed in order to specify interface for the
// plugin.
class ClusterSequence;




//======================================================================
class JetDefinition {
  
public:

  class Plugin;

  // forward declaration of a class that will provide the
  // recombination scheme facilities and/or allow a user to
  // extend these facilities
  class Recombiner;

  

  JetDefinition(JetAlgorithm jet_algorithm, 
                double R, 
                RecombinationScheme recomb_scheme = E_scheme,
                Strategy strategy = Best) {
    *this = JetDefinition(jet_algorithm, R, strategy, recomb_scheme, 1);
  }

  JetDefinition(JetAlgorithm jet_algorithm, 
                RecombinationScheme recomb_scheme = E_scheme,
                Strategy strategy = Best) {
    double dummyR = 0.0;
    *this = JetDefinition(jet_algorithm, dummyR, strategy, recomb_scheme, 0);
  }

  JetDefinition(JetAlgorithm jet_algorithm, 
                double R, 
                double xtra_param,
                RecombinationScheme recomb_scheme = E_scheme,
                Strategy strategy = Best) {
    *this = JetDefinition(jet_algorithm, R, strategy, recomb_scheme, 2);
    set_extra_param(xtra_param);
  }


  JetDefinition(JetAlgorithm jet_algorithm, 
                double R, 
                const Recombiner * recombiner,
                Strategy strategy = Best) {
    *this = JetDefinition(jet_algorithm, R, external_scheme, strategy);
    _recombiner = recombiner;
  }


  JetDefinition(JetAlgorithm jet_algorithm, 
                const Recombiner * recombiner,
                Strategy strategy = Best) {
    *this = JetDefinition(jet_algorithm, external_scheme, strategy);
    _recombiner = recombiner;
  }

  JetDefinition(JetAlgorithm jet_algorithm, 
                double R, 
                double xtra_param,
                const Recombiner * recombiner,
                Strategy strategy = Best) {
    *this = JetDefinition(jet_algorithm, R, external_scheme, strategy);
    _recombiner = recombiner;
    set_extra_param(xtra_param);
  }

  JetDefinition() {
    *this = JetDefinition(kt_algorithm, 1.0);
  }

  JetDefinition(const Plugin * plugin) {
    _plugin = plugin;
    _strategy = plugin_strategy;
    _Rparam = _plugin->R();
    _jet_algorithm = plugin_algorithm;
    set_recombination_scheme(E_scheme);
  }


  JetDefinition(JetAlgorithm jet_algorithm, 
                double R, 
                Strategy strategy,
                RecombinationScheme recomb_scheme = E_scheme,
                int nparameters = 1);
// :
//    _jet_algorithm(jet_algorithm), _Rparam(R), _strategy(strategy) {
//    // the largest sensible value for R
//    if (jet_algorithm != ee_kt_algorithm &&
//      jet_algorithm != ee_genkt_algorithm) assert(_Rparam <= 0.5*pi);
//    assert(_jet_algorithm != plugin_algorithm &&
//           _strategy   != plugin_strategy);
//    _plugin = NULL;
//    set_recombination_scheme(recomb_scheme);
//    set_extra_param(0.0); // make sure it's defined
//  }


  void set_recombination_scheme(RecombinationScheme);

  void set_recombiner(const Recombiner * recomb) {
    _recombiner = recomb;
    _default_recombiner = DefaultRecombiner(external_scheme);
  }

  const Plugin * plugin() const {return _plugin;};

  JetAlgorithm jet_algorithm  () const {return _jet_algorithm  ;}
  JetAlgorithm jet_finder     () const {return _jet_algorithm  ;}
  double    R           () const {return _Rparam      ;}
  // a general purpose extra parameter, whose meaning depends on
  // the algorithm, and may often be unused.
  double    extra_param () const {return _extra_param ;}
  Strategy  strategy    () const {return _strategy    ;}
  RecombinationScheme recombination_scheme() const {
    return _default_recombiner.scheme();}

  void set_jet_algorithm(JetAlgorithm njf) {_jet_algorithm = njf;}
  void set_jet_finder(JetAlgorithm njf)    {_jet_algorithm = njf;}
  void set_extra_param(double xtra_param) {_extra_param = xtra_param;}

  const Recombiner * recombiner() const {
    return _recombiner == 0 ? & _default_recombiner : _recombiner;}

  std::string description() const;


public:
  //======================================================================
  class Recombiner {
  public:
    virtual std::string description() const = 0;
    
    virtual void recombine(const PseudoJet & pa, const PseudoJet & pb, 
                           PseudoJet & pab) const = 0;

    virtual void preprocess(PseudoJet & ) const {};
    
    virtual ~Recombiner() {};

    inline void plus_equal(PseudoJet & pa, const PseudoJet & pb) const {
      // put result in a temporary location in case the recombiner
      // does something funny (ours doesn't, but who knows about the
      // user's)
      PseudoJet pres; 
      recombine(pa,pb,pres);
      pa = pres;
    }

  };
  
  
  //======================================================================
  class DefaultRecombiner : public Recombiner {
  public:
    DefaultRecombiner(RecombinationScheme recomb_scheme = E_scheme) : 
      _recomb_scheme(recomb_scheme) {}
    
    virtual std::string description() const;
    
    virtual void recombine(const PseudoJet & pa, const PseudoJet & pb, 
                           PseudoJet & pab) const;

    virtual void preprocess(PseudoJet & p) const;

    RecombinationScheme scheme() const {return _recomb_scheme;}
    
  private:
    RecombinationScheme _recomb_scheme;
  };


  //======================================================================
  class Plugin{
  public:
    virtual std::string description() const = 0;
    
    virtual void run_clustering(ClusterSequence &) const = 0;
    
    virtual double R() const = 0;
    
    virtual bool supports_ghosted_passive_areas() const {return false;}

    virtual void set_ghost_separation_scale(double scale) const;
    virtual double ghost_separation_scale() const {return 0.0;}

    virtual bool exclusive_sequence_meaningful() const {return false;}

    virtual ~Plugin() {};
  };

private:


  JetAlgorithm _jet_algorithm;
  double    _Rparam;
  double    _extra_param ; 
  Strategy  _strategy  ;

  const Plugin * _plugin;

  // when we use our own recombiner it's useful to point to it here
  // so that we don't have to worry about deleting it etc...
  DefaultRecombiner _default_recombiner;
  const Recombiner * _recombiner;

};






FASTJET_END_NAMESPACE

#endif // __FASTJET_JETDEFINITION_HH__