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.
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:
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
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 finderThe 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:
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::.
The result of calling compute_jets(...) or recompute_jets(...) is stored in the vector
vector<Cjet> Csiscone::jets; |
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 } |
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.
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:
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.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.siscone_spherical
namespace.libsiscone_spherical.{a,so}
rather than libsiscone.{a,so}
.SISConeSphericalPlugin
.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
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); |
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.