SISCone Documentation

Version 3.0.5


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:

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:

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:

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:

(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


Home
Contacts:  Gregory Soyez  Gavin Salam