siscone is hosted by Hepforge, IPPP Durham

The SISCone Jet Algorithm

Version 3.0.6


home SISCone is written in C++ and is provided as a library. We describe below 3 ways of using it:

For the e+e- events, we provide an implementation of SISCone in spherical coordinates. See here for details on how to use it.

home

Using the sample application

For simple applications, SISCone comes with a command-line application 

Usage: ./siscone <args>

Here is an exhaustive list of the arguments:
Parameters control (with default values):
  -n <val>, --number=<val>  : set the maximum number of particles allowed (all)
  -R <val>, --radius=<val>  : set the radius (0.7)
  -f <val>, --fraction=<val>: set the overlap parameter (0.5)
  -p <val>, --ptmin=<val>   : set the minimal pT for protojets (0)
  -e <val>, --event=<val>   : set the event filename (events/single-event.dat)
  -n <val>, --npass=<val>   : set the number of passes (0 for infinity) (0)
  -s <val>, --sm=<val>      : set the variable for split-merge (pttilde)

Output flags:
  --version    : show version information
  -h, --help   : show this message
  -v, --verbose: be verbose (on by default)
  -q, --quiet  : be quiet

The program outputs two files:

  • particles.dat: the list of particles as a two-column file giving the rapidity y and azimuthal angle φ for each particle
  • jets.dat: the first line gives the number of jets. Then comes the list of jets within 4 columns giving, for each jet, the (y, φ) coordinates of its centre, its pT and the number of particles it contains. The remaining part of the file lists the jet content. This is again given in 4 columns: the (y, φ) coordinates of the particle, its index in the initial list and the index of the jet to which it belongs.

Back to top

home

Using the library

SISCone can be more conveniently used directly in C++ program linked against the SISCone library. There are basically two objects that are important for users:

Cmomentum: the 4-momentum class

(see momentum.h for details)

This class is used to store the property of one particle. It is defined through the 4-momentum coordinates of the particle e.g., to create a particle of momentum px py pz and energy E

  Cmomentum particle=Cmomentum(px, py, pz, E);

Csiscone: the SISCone jet finder

(see siscone.h for details)

The Csiscone class is the main class of interest of the algorithm. It is the one that you want to use to calculate the jets from a given set of particles. The algorithm is called through the following members: 

  int Csiscone::compute_jets(vector<Cmomentum> &particles,
                             double R, double f, int n_pass_max=0, double ptmin=0.0,
                             Esplit_merge_scale _split_merge_scale=SM_pttilde);
  int Csiscone::recompute_jets(double f, double ptmin=0.0,
                               Esplit_merge_scale _split_merge_scale=SM_pttilde);

The first of those methods takes the following information as argument:

  • particles: the list of particles to deal with under the form of a STL vector of particles.
  • R: the radius of the cone used to scan for stable cones (protocones)
  • f: the overlap parameter. When splitting and merging protocones, two overlapping cones are split (resp. merged) when their overlapping pT is smaller (resp. larger) than a fraction f of the smallest pT of the parents.
  • n_pass_max: maximum number of passes. When computing protocones, it happens that some particles do not enter into jet. We can therefore re-run the algorithm with those particles only. This parameter controls the number of such passes. It has been set to 1 by default. If you want to run the algorithm until all particles are associated with a jet or no new stable cone are found, set it to 0.
  • ptmin: minimal pT for the protojets included in the split-merge process. At each step of the split-merge process, we remove jet candidates which have a pT less than ptmin.
  • split_merge_scale: variable to use for split-merge (ordering and overlap fraction computation). This can be SM_pttilde, SM_Et, SM_mt or SM_pt, respectively corresponding to a p-scheme pT, the transverse energy ET, the transverse mass mT or the transverse momentum pT. We highly recommand to keep the default value SM_pttilde (see this note for details)
The second member (recompute_jets) allows you to rerun the split/merge algorithm with a different overlap parameter.

Remark: The algorithm has been placed inside the namespace siscone. Hence, you should either add the line using namespace siscone; on top of your applications, or prefix any call to the siscone library by siscone::.

Output

The result of calling compute_jets(...) or recompute_jets(...) is stored in the vector 

vector<Cjet> Csiscone::jets;
The elements of that vector contain all necessary information concerning the jets:
  • Cjet::v: 4-momentum of the jet.
  • Cjet::n: number of particles in the jet.
  • Cjet::contents: jet contents. It is stored as a vector<int> listing the indices of the particles contained in the jet.
  • Cjet::pass : pass at which the jet has been found (0 is the first, -1 means that the particle has not been included in the analysis i.e. it has infinite rapidity).

an illustrative example

Here follows an example which illustrates the usage of those objects (see also main.cpp in the scones tree) 

01 #include <stdio.h>
02 #include <iostream>
03 #include "siscone/momentum.h"
04 #include "siscone/siscone.h"
05 
06 #define R     0.7
07 #define f     0.5
08 #define f_alt 0.75
09 
10 using namespace std;
11 using namespace siscone;
12 
13 int main(int argc, char *argv[]){
14   vector<Cmomentum> particles;    // list of particles
15   Csiscone siscone;               // main object for the cone algorithm
16   int i;                          // loop index
17   int N;                          // number of particles
18   double px,py,pz,E;              // particles 4-momentum
19   char fline[512];                // line to read from a file
20 
21   // read particles
22   FILE *flux;
23   flux = fopen("events/single-event.dat", "r");
24   if (flux==NULL){
25     cerr << "cannot read event" << endl;
26     return 1;
27   }
28 
29   N=0;
30   while (fgets(fline, 512, flux)!=NULL){
31     if (fline[0]!='#'){ // skip lines beginning with '#'
32       if (sscanf(fline, "%le%le%le%le", &px, &py, &pz, &E)==4){
33         particles.push_back(Cmomentum(px, py, pz, E));
34         N++;
35       } else {
36         cout << "error in reading event file Giving up." << endl;
37         fclose(flux);
38         return 2;
39       }
40     }
41   }
42   fclose(flux);
43 
44   // compute jets
45   // first compute with multiple passes (default)
46   i=siscone.compute_jets(particles, R, f);
47   cout << "  " << i << " jets found in multi-pass run" << endl;
48 
49   // then, recompute it with a different f
50   i=siscone.recompute_jets(f_alt);
51   cout << "  " << i << " jets found with alterntive f" << endl;
52 
53   // compute jets with a single pass
54   i=siscone.compute_jets(particles, R, f, 1);
55   cout << "  " << i << " jets found in single-pass run" << endl;
56 
57   // show jets
58   vector<Cjet>::iterator it_j;
59   int i1;
60   fprintf(stdout, "#             pT        eta");
61   fprintf(stdout, "      phi       px         py         pz         E    \n");
62   for (it_j = siscone.jets.begin(), i1=0 ; 
63        it_j != siscone.jets.end() ; it_j++, i1++){
64     fprintf(stdout, "Jet %3d: %10.3f %8.3f %8.3f",
65             i1, it_j->v.perp(), it_j->v.eta, it_j->v.phi);
66     fprintf(stdout, " %10.3f %10.3f %10.3f %10.3f\n",
67             it_j->v.px, it_j->v.py,  it_j->v.pz,  it_j->v.E);
68   }
69 
70   return 0;
71 }

Back to top

home

Using the FastJet plugin

SISCone is available as a plugin of the FastJet project. The plugin is named SISConePlugin. Note that it requires at least version 2.1 of FastJet. See the FastJet website for details.

Back to top

home

The spherical version of SISCone

To allow clustering of e+e– events, an implementation of SISCone in spherical coordinates is available (as of version 2.0 of SISCone).

Its usage is very similar to that of the basic implementation of SISCone, so we just highlight the few differences here:

  • The spherical version, uses energy E and normal angles, rather than the longitudinally boost-invariant pt, rapidity and azimuth. Specifically:
    • The distance between a pair of particle is the angle between the pair particles (equivalently the the distance on the surface of a unit sphere). Similarily, the cone radius R is also defined as the cone half-opening angle.
    • During the split--merge step, we use the energy of the particles rather than their transverse momentum. However, as in the standard situation where ordering the protojets in pt led to infrared-unsafeties, ordering the protojets in energy in the spherical case also leads to infrared unsafeties. To solve that problem, we introduce the new variable
      Etilde
      and use it to order the protojets. Note that to compute the overlap fraction, we keep using the plain energy (which is perfectly safe in this case). In practice, when invoking the clustering, this corresponds to the default choice of SM_Etilde for the split--merge scale. If one rather wants to use E despite its infrared-unsafety problems, one can specify SM_E instead.
  • The structure remains the same as for the basic implementation but the class names have been prefixed by CSph instead of just C. For example, the list of 4-momenta should be of the CSphmomentum type (1), the clustering is done using CSphsiscone and the jets are stored in CSphjet objects.
  • The classes for the spherical implementation are placed under the siscone_spherical namespace.
  • The library is called libsiscone_spherical.{a,so} rather than libsiscone.{a,so}.
  • The spherical version of SISCone is available as a FastJet plugin named SISConeSphericalPlugin.
(1)The main reason for having two classes for the 4-momenta is that SISCone is internally optimised to avoid repeated computation of expensive quantities like the rapidity. Since the spherical version makes use of the polar angle θ instead of the rapidity y, having 2 separate classes allows to optimise both situations.

home

SISCone with progressive removal

Since version 3.0.0, SISCone with progressive removal provides an alternative to the standard split--merge algorithm used by default with SISCone. The SISCone-PR algorithm works as follows

  1. search for stable cones.
  2. declare the hardest stable cone a jet and remove its particles from the list of remaining particles.
  3. if there are some remaining particles, go back to 1.
In practice, jets are obtained by creating a Csiscone (or CSphsiscone object) as described above and calling 

  int Csisscone::compute_jets_progressive_removal(vector<Cmomentum> &particles,
                                                  double R, int n_pass_max=0, double ptmin=0.0,
                                                  Esplit_merge_scale _split_merge_scale=SM_pttilde);

This results in circular hard jets (analogously to anti-kt). The complexity of the algorithm is N2 log(N). The scale used to decide which stable cone is the hardest can be chosen in the same way as the ordering scale for the split--merge procedure. The default (SM_pttilde for the standard, pp, version of SISCone; SM_Etilde for the version in spherical coordinates) is recommended. Alternatively, a user-defined scale choice can be provided: the user has to derive their favourite scale choice from Csiscone::Cscale_choice and then use Csiscone::set_user_scale() with a pointer to an instance of that class to activate the user-defined choice.

Back to top