SISCone Documentation

Version 2.0.6


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.


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


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 Csisscone::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 Csisscone::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


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


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.

Back to top


Home
Contacts:  Gregory Soyez  Gavin Salam