SISConeSphericalPlugin is a plugin for fastjet (v2.1 upwards) that provides an interface to the seedless infrared safe cone jet finder by Gregory Soyez and Gavin Salam. More...

#include <SISConeSphericalPlugin.hh>

Inheritance diagram for SISConeSphericalPlugin:

[legend]

Collaboration diagram for SISConeSphericalPlugin:

[legend]

List of all members.

Public Types
enum	SplitMergeScale { SM_E, SM_Etilde }
	enum for the different split-merge scale choices; Note that order _must_ be the same as in siscone More...
Public Member Functions
	SISConeSphericalPlugin (double cone_radius, double overlap_threshold, int n_pass_max=0, double protojet_Emin=0.0, bool caching=false, SplitMergeScale split_merge_scale=SM_Etilde, double split_merge_stopping_scale=0.0)
	Main constructor for the SISConeSpherical Plugin class.
double	protojet_Emin () const
	minimum energy for a protojet to be considered in the split-merge step of the algorithm
double	protojet_or_ghost_Emin () const
	return the scale to be passed to SISCone as the protojet_Emin -- if we have a ghost separation scale that is above the protojet_ptmin, then the ghost_separation_scale becomes the relevant one to use here
SplitMergeScale	split_merge_scale () const
	indicates scale used in split-merge
void	set_split_merge_scale (SplitMergeScale sms)
	sets scale used in split-merge
bool	split_merge_use_E_weighted_splitting () const
	indicate if the splittings are done using the anti-kt distance
void	set_split_merge_use_E_weighted_splitting (bool val)
virtual bool	supports_ghosted_passive_areas () const
	overload the default as we don't provide support for passive areas.
virtual std::string	description () const
	plugin description
virtual void	run_clustering (ClusterSequence &) const
	really do the clustering work
Protected Member Functions
virtual void	reset_stored_plugin () const
	call the re-clustering itself
Private Attributes
double	_protojet_Emin
SplitMergeScale	_split_merge_scale
bool	_use_E_weighted_splitting
Static Private Attributes
static std::auto_ptr < SISConeSphericalPlugin >	stored_plugin
static std::auto_ptr < std::vector< PseudoJet > >	stored_particles
static std::auto_ptr < siscone_spherical::CSphsiscone >	stored_siscone

Detailed Description

SISConeSphericalPlugin is a plugin for fastjet (v2.1 upwards) that provides an interface to the seedless infrared safe cone jet finder by Gregory Soyez and Gavin Salam.

This is the version of SISCone using spherical coordinates. Compared to the original cylindrical version:

Particles are within a cone if their opening angle relative to the centre of the cone is less than R

The split-merge step uses the total energy in the protojet as the ordering and overlap-measure variable

The IR safety of the split-merge step is _not_ guaranteed for events consisting of two back-to-back identical heavy particles that decay. This is because of potential degeneracies in the ordering for the split-merge step.

For moderate values of R the problem should not be too severe (or may even be absent for some values of the overlap parameter), however the user should be aware of the issue.

The default split-merge scale may change at a later date to resolve this issue.

SISCone uses geometrical techniques to exhaustively consider all possible distinct cones. It then finds out which ones are stable and sends the result to the Tevatron Run-II type split-merge procedure for overlapping cones.

Four parameters govern the "physics" of the algorithm:

the cone_radius (this should be self-explanatory!)

the overlap_threshold is the parameter which dictates how much two jets must overlap (E_overlap/min(E1,E2)) if they are to be merged

Not all particles are in stable cones in the first round of searching for stable cones; one can therefore optionally have the the jet finder carry out additional passes of searching for stable cones among particles that were in no stable cone in previous passes --- the maximum number of passes carried out is n_pass_max. If this is zero then additional passes are carried out until no new stable cones are found.

Protojet Emin: protojets that are below this Emin (default = 0) are discarded before each iteration of the split-merge loop.

One parameter governs some internal algorithmic shortcuts:

if "caching" is turned on then the last event clustered by siscone is stored -- if the current event is identical and the cone_radius and n_pass_max are identical, then the only part of the clustering that needs to be rerun is the split-merge part, leading to significant speed gains; there is a small (O(N) storage and speed) penalty for caching, so it should be kept off (default) if only a single overlap_threshold is used.

The final jets can be accessed by requestion the inclusive_jets(...) from the ClusterSequence object. Note that these PseudoJets have their user_index() set to the index of the pass in which they were found (first pass = 0). NB: This does not currently work for jets that consist of a single particle.

For further information on the details of the algorithm see the SISCone paper, arXiv:0704.0292 [JHEP 0705:086,2007].

For documentation about the implementation, see the siscone/doc/html/index.html file.

Definition at line 89 of file SISConeSphericalPlugin.hh.

Member Enumeration Documentation

enum SISConeSphericalPlugin::SplitMergeScale

enum for the different split-merge scale choices; Note that order _must_ be the same as in siscone

Enumerator:

SM_E	Energy (IR unsafe with momentum conservation)
SM_Etilde	sum_{i jet} E_i [1+sin^2(theta_iJ)]

Definition at line 94 of file SISConeSphericalPlugin.hh.

                       {SM_E,        
                        SM_Etilde    
  };

Constructor & Destructor Documentation

SISConeSphericalPlugin::SISConeSphericalPlugin	(	double	cone_radius,
		double	overlap_threshold,
		int	n_pass_max = `0`,
		double	protojet_Emin = `0.0`,
		bool	caching = `false`,
		SplitMergeScale	split_merge_scale = `SM_Etilde`,
		double	split_merge_stopping_scale = `0.0`
	)		`[inline]`

Main constructor for the SISConeSpherical Plugin class.

Definition at line 102 of file SISConeSphericalPlugin.hh.

                                                                  {
    _cone_radius           =cone_radius;
    _overlap_threshold     =overlap_threshold;
    _n_pass_max            =n_pass_max;
    _protojet_Emin         =protojet_Emin;
    _caching               =caching;        
    _split_merge_scale     =split_merge_scale;
    _split_merge_stopping_scale = split_merge_stopping_scale;
    _ghost_sep_scale       = 0.0;
    _use_E_weighted_splitting = false;
  }

Member Function Documentation

string SISConeSphericalPlugin::description ( ) const [virtual]

plugin description

Implements SISConeBasePlugin.

Definition at line 35 of file SISConeSphericalPlugin.cc.

References SISConeBasePlugin::_split_merge_stopping_scale, SISConeBasePlugin::_use_jet_def_recombiner, SISConeBasePlugin::caching(), SISConeBasePlugin::cone_radius(), SISConeBasePlugin::n_pass_max(), SISConeBasePlugin::overlap_threshold(), and SISConePlugin::split_merge_scale().

                                                  {
  ostringstream desc;
  
  const string on = "on";
  const string off = "off";

  string sm_scale_string = "split-merge uses " + 
    split_merge_scale_name(Esplit_merge_scale(split_merge_scale()));

  desc << "Spherical SISCone jet algorithm with " ;
  desc << "cone_radius = "       << cone_radius        () << ", ";
  desc << "overlap_threshold = " << overlap_threshold  () << ", ";
  desc << "n_pass_max = "        << n_pass_max         () << ", ";
  desc << "protojet_Emin = "     << protojet_Emin()      << ", ";
  desc <<  sm_scale_string                                << ", ";
  desc << "caching turned "      << (caching() ? on : off);
  desc << ", SM stop scale = "     << _split_merge_stopping_scale;

  // add a note to the description if we use the pt-weighted splitting
  if (_use_E_weighted_splitting){
    desc << ", using E-weighted splitting";
  }

  if (_use_jet_def_recombiner){
    desc << ", using jet-definition's own recombiner";
  }

  // create a fake siscone object so that we can find out more about it
  CSphsiscone siscone;
  if (siscone.merge_identical_protocones) {
    desc << ", and (IR unsafe) merge_indentical_protocones=true" ;
  }

  desc << ", SISCone code v" << siscone_version();

  return desc.str();
}

double SISConeSphericalPlugin::protojet_Emin ( ) const [inline]

minimum energy for a protojet to be considered in the split-merge step of the algorithm

Definition at line 122 of file SISConeSphericalPlugin.hh.

References _protojet_Emin.

Referenced by SISConeSphericalPlugin().

{return _protojet_Emin  ;}

double SISConeSphericalPlugin::protojet_or_ghost_Emin ( ) const [inline]

return the scale to be passed to SISCone as the protojet_Emin -- if we have a ghost separation scale that is above the protojet_ptmin, then the ghost_separation_scale becomes the relevant one to use here

Definition at line 128 of file SISConeSphericalPlugin.hh.

References SISConeBasePlugin::_ghost_sep_scale, and _protojet_Emin.

                                          {return std::max(_protojet_Emin,
                                                           _ghost_sep_scale);}

void SISConeSphericalPlugin::reset_stored_plugin ( ) const [protected, virtual]

call the re-clustering itself

Implements SISConeBasePlugin.

Definition at line 209 of file SISConeSphericalPlugin.cc.

References SISConePlugin::stored_plugin.

Referenced by SISConePlugin::run_clustering().

                                                      {
  stored_plugin.reset( new SISConeSphericalPlugin(*this));
}

void SISConeSphericalPlugin::run_clustering ( ClusterSequence & ) const [virtual]

really do the clustering work

Implements SISConeBasePlugin.

Definition at line 75 of file SISConeSphericalPlugin.cc.

References SISConeBaseExtras::_jet_def_plugin, SISConeBaseExtras::_most_ambiguous_split, SISConeBaseExtras::_pass, SISConeBaseExtras::_protocones, SISConeBasePlugin::_split_merge_stopping_scale, SISConeBasePlugin::_use_jet_def_recombiner, SISConeBasePlugin::caching(), SISConeBasePlugin::cone_radius(), SISConeBasePlugin::ghost_separation_scale(), have_same_momentum(), ClusterSequence::jets(), SISConeBasePlugin::n_pass_max(), SISConeBasePlugin::overlap_threshold(), ClusterSequence::plugin_associate_extras(), ClusterSequence::plugin_record_iB_recombination(), ClusterSequence::plugin_record_ij_recombination(), SISConePlugin::reset_stored_plugin(), SISConePlugin::split_merge_scale(), SISConePlugin::stored_particles, SISConePlugin::stored_plugin, and SISConePlugin::stored_siscone.

                                                                             {

  CSphsiscone   local_siscone;
  CSphsiscone * siscone;

  unsigned n = clust_seq.jets().size();

  bool new_siscone = true; // by default we'll be running it

  if (caching()) {

    // Establish if we have a cached run with the same R, npass and
    // particles. If not then do any tidying up / reallocation that's
    // necessary for the next round of caching, otherwise just set
    // relevant pointers so that we can reuse and old run.
    if (stored_siscone.get() != 0) {
      new_siscone = !(stored_plugin->cone_radius()   == cone_radius()
                      && stored_plugin->n_pass_max() == n_pass_max()
                      && stored_particles->size()    == n);
      if (!new_siscone) {
        for(unsigned i = 0; i < n; i++) {
          // only check momentum because indices will be correctly dealt
          // with anyway when extracting the clustering order.
          new_siscone |= !have_same_momentum(clust_seq.jets()[i],
                                             (*stored_particles)[i]);
        }
      }
    }

    // allocate the new siscone, etc., if need be
    if (new_siscone) {
      stored_siscone  .reset( new CSphsiscone );
      stored_particles.reset( new std::vector<PseudoJet>(clust_seq.jets()));
      reset_stored_plugin();
    }

    siscone = stored_siscone.get();
  } else {
    siscone = &local_siscone;
  }

  // make sure stopping scale is set in siscone
  siscone->SM_var2_hardest_cut_off = _split_merge_stopping_scale*_split_merge_stopping_scale;

  // set the specific parameters
  // when running with ghosts for passive areas, do not put the
  // ghosts into the stable-cone search (not relevant)
  siscone->stable_cone_soft_E2_cutoff = ghost_separation_scale()
                                      * ghost_separation_scale();
  // set the type of splitting we want (default=std one, true->pt-weighted split)
  siscone->set_E_weighted_splitting(_use_E_weighted_splitting);


  if (new_siscone) {
    // transfer fastjet initial particles into the siscone type
    std::vector<CSphmomentum> siscone_momenta(n);
    for(unsigned i = 0; i < n; i++) {
      const PseudoJet & p = clust_seq.jets()[i]; // shorthand
      siscone_momenta[i] = CSphmomentum(p.px(), p.py(), p.pz(), p.E());
    }

    // run the jet finding
    //cout << "plg sms: " << split_merge_scale() << endl;
    siscone->compute_jets(siscone_momenta, cone_radius(), overlap_threshold(),
                          n_pass_max(), protojet_or_ghost_Emin(), 
                          Esplit_merge_scale(split_merge_scale()));
  } else {
    // rerun the jet finding
    // just run the overlap part of the jets.
    //cout << "plg rcmp sms: " << split_merge_scale() << endl;
    siscone->recompute_jets(overlap_threshold(), protojet_or_ghost_Emin(), 
                            Esplit_merge_scale(split_merge_scale()));
  }

  // extract the jets [in reverse order -- to get nice ordering in pt at end]
  int njet = siscone->jets.size();

  // allocate space for the extras object
  SISConeSphericalExtras * extras = new SISConeSphericalExtras(n);

  for (int ijet = njet-1; ijet >= 0; ijet--) {
    const CSphjet & jet = siscone->jets[ijet]; // shorthand

    // Successively merge the particles that make up the cone jet
    // until we have all particles in it.  Start off with the zeroth
    // particle.
    int jet_k = jet.contents[0];
    for (unsigned ipart = 1; ipart < jet.contents.size(); ipart++) {
      // take the last result of the merge
      int jet_i = jet_k;
      // and the next element of the jet
      int jet_j = jet.contents[ipart];
      // and merge them (with a fake dij)
      double dij = 0.0;

      if (_use_jet_def_recombiner) {
       clust_seq.plugin_record_ij_recombination(jet_i, jet_j, dij, jet_k);
      } else {
       // create the new jet by hand so that we can adjust its user index
       PseudoJet newjet = clust_seq.jets()[jet_i] + clust_seq.jets()[jet_j];
       // set the user index to be the pass in which the jet was discovered
       newjet.set_user_index(jet.pass);
       clust_seq.plugin_record_ij_recombination(jet_i, jet_j, dij, newjet, jet_k);
      }

    }

    // we have merged all the jet's particles into a single object, so now
    // "declare" it to be a beam (inclusive) jet.
    // [NB: put a sensible looking d_iB just to be nice...]
    double d_iB = clust_seq.jets()[jet_k].perp2();
    clust_seq.plugin_record_iB_recombination(jet_k, d_iB);

    // now record the pass of the jet in the extras object
    extras->_pass[clust_seq.jets()[jet_k].cluster_hist_index()] = jet.pass;
  }

  // now copy the list of protocones into an "extras" objects
  for (unsigned ipass = 0; ipass < siscone->protocones_list.size(); ipass++) {
    for (unsigned ipc = 0; ipc < siscone->protocones_list[ipass].size(); ipc++) {
      PseudoJet protocone(siscone->protocones_list[ipass][ipc]);
      protocone.set_user_index(ipass);
      extras->_protocones.push_back(protocone);
    }
  }
  extras->_most_ambiguous_split = siscone->most_ambiguous_split;

  // tell it what the jet definition was
  extras->_jet_def_plugin = this;

  // give the extras object to the cluster sequence.
  clust_seq.plugin_associate_extras(std::auto_ptr<ClusterSequence::Extras>(extras));
}

void SISConeSphericalPlugin::set_split_merge_scale ( SplitMergeScale sms ) [inline]

sets scale used in split-merge

Definition at line 134 of file SISConeSphericalPlugin.hh.

References _split_merge_scale.

{_split_merge_scale = sms;}

void SISConeSphericalPlugin::set_split_merge_use_E_weighted_splitting ( bool val ) [inline]

Definition at line 138 of file SISConeSphericalPlugin.hh.

References _use_E_weighted_splitting.

                                                          {
    _use_E_weighted_splitting = val;}

SplitMergeScale SISConeSphericalPlugin::split_merge_scale ( ) const [inline]

indicates scale used in split-merge

Definition at line 132 of file SISConeSphericalPlugin.hh.

References _split_merge_scale.

Referenced by SISConePlugin::description(), SISConePlugin::run_clustering(), and SISConeSphericalPlugin().

{return _split_merge_scale;}

bool SISConeSphericalPlugin::split_merge_use_E_weighted_splitting ( ) const [inline]

indicate if the splittings are done using the anti-kt distance

Definition at line 137 of file SISConeSphericalPlugin.hh.

References _use_E_weighted_splitting.

{return _use_E_weighted_splitting;}

virtual bool SISConeSphericalPlugin::supports_ghosted_passive_areas ( ) const [inline, virtual]

overload the default as we don't provide support for passive areas.

Reimplemented from SISConeBasePlugin.

Definition at line 143 of file SISConeSphericalPlugin.hh.

{return true;}

Member Data Documentation

double SISConeSphericalPlugin::_protojet_Emin [private]

Definition at line 153 of file SISConeSphericalPlugin.hh.

Referenced by protojet_Emin(), protojet_or_ghost_Emin(), and SISConeSphericalPlugin().

SplitMergeScale SISConeSphericalPlugin::_split_merge_scale [private]

Definition at line 154 of file SISConeSphericalPlugin.hh.

Referenced by set_split_merge_scale(), SISConeSphericalPlugin(), and split_merge_scale().

bool SISConeSphericalPlugin::_use_E_weighted_splitting [private]

Definition at line 155 of file SISConeSphericalPlugin.hh.

Referenced by set_split_merge_use_E_weighted_splitting(), SISConeSphericalPlugin(), and split_merge_use_E_weighted_splitting().

std::auto_ptr< std::vector< PseudoJet > > SISConeSphericalPlugin::stored_particles [static, private]

Definition at line 160 of file SISConeSphericalPlugin.hh.

Referenced by SISConePlugin::run_clustering().

std::auto_ptr< SISConeSphericalPlugin > SISConeSphericalPlugin::stored_plugin [static, private]

Definition at line 159 of file SISConeSphericalPlugin.hh.

Referenced by SISConePlugin::reset_stored_plugin(), and SISConePlugin::run_clustering().

std::auto_ptr< CSphsiscone > SISConeSphericalPlugin::stored_siscone [static, private]

Definition at line 161 of file SISConeSphericalPlugin.hh.

Referenced by SISConePlugin::run_clustering().

The documentation for this class was generated from the following files:

plugins/SISCone/fastjet/SISConeSphericalPlugin.hh
plugins/SISCone/SISConeSphericalPlugin.cc

SISConeSphericalPlugin Class Reference

Public Types

Public Member Functions

Protected Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation