SISCone Documentation

Version 2.0.5

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

Using the sample application
Using the library (from source code)
Using the FastJet plugin

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:

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 p_T 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.

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:

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 p_T is smaller (resp. larger) than a fraction f of the smallest p_T 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 p_T for the protojets included in the split-merge process. At each step of the split-merge process, we remove jet candidates which have a p_T 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 p_T, the transverse energy E_T, the transverse mass m_T or the transverse momentum p_T. 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 }

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.

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 p_t, 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 p_t 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
  
  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 ⁽¹⁾, 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.

⁽¹⁾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
Contacts: Gregory Soyez Gavin Salam