SpartyJet documentation

Overview

Spartyjet is a set of software tools to run jet finding algorithms.
Besides physics motivations, it has been written with 3 goals in mind :

ease of use
flexibility
speed

To meet these goals, we tried to write it in a modular way : it consists in bricks of software put together allowing

to include any kind of input in the form of 4momentums
to perform any operation on this 4momentums set (including jet finding of course)
to save all results and any associated quantities into a ROOT ntuple

See a schematic view of the code organisation in this document.
A lots of different algorithm are shipped with Spartyjet : Atlas, CMS, CDF and D0 jet algorithms, the FastJet library, and Pythia's CellJet.
Finally, SpartyJet provides a set of ROOT scripts to visualize easily results of jets finding.

Installation

Requirements

Building environment : make, GCC/g++ (not tested with other compilers).
Recent version of ROOT (see notes)
Has been tested on various linux distributions. Should work with little effort on MacOsX.

compilation

Just type
```
make
```
in spartyjet/ directory. (see NOTES)

This will build a list of libraries in spartyjet/libs that you can load from a ROOT session or you can link to from an executable.

libraries

libs/libJetCore.so : all algorithms
libs/libCDFJet.so  : JetClustering and MidPoint 
libs/libATLASJet.so: ATLAS algorithms 
libs/libCellJet.so : CellJet algorithm
libs/libFastJet.so : FastJet and SISCone 
libs/libExtras.so  : extras

See spartyjet/scripts
or spartyjet/programs for examples. The scripts in spartyjet/scripts expect to be run from spartyjet/ directory.
the StdHEP libraries are optional to compile. If you plan on using StdHEP files as input, then open SpartyJet/MakefileCommonOpt and uncomment the line "DO_STDHEP = 1". On the other hand, if StdHEP compilation is producing errors, then make sure this line is commented out. The current default is to NOT compile StdHEP.

Running (example with JetBuilder)

The following walkthrough follows the script spartyjet/scripts/simple.C

Goal : Run the JetClustering Algorithm on the first 10 events listed in data/J1_Clusters.dat

First, you need to load the libraries that are needed for the algorithms that you are running.

gSystem->Load("libTree.so");         // is needed with recent ROOT version
gSystem->Load("libPhysics.so");      // is needed with recent ROOT version 
gSystem->Load("libs/libJetCore.so"); //  is needed for all algorithms 
gSystem->Load("libs/libCDFJet.so");  // is needed for JetClustering (and MidPoint)

Next, create an input object of type StdTextInput, and give it the filename containing the events.
```
StdTextInput textinput("data/J1_Clusters.dat");
```
Another type of input object is atlas::CBNTInput input, which is used with atlas ntuples.
Now create a builder object, which will take care of the dirty work of running the algorithm(s).
```
JetBuilder builder;
```
And you have to pass it the input object that you made.
```
builder.configure_input((InputMaker*)&textinput);
```
Now add the algorithms that you want to run, just jet clustering in this case.
```
builder.add_default_alg(
new
cdf::JetClustFinder("myJetClu"));
```
Set any other options that you want The option chosen here sets the min pt for the incoming four-vectors to 0GeV (no cut) and 1000GeV for outgoing jets
```
builder.set_default_cut(0,1);
```
NOTE - the units here are the same as the input Also in this example is the text output option. Just call add_text_output and pass it the filename you want to create. This option is discussed in OPTIONS
```
builder.add_text_output("data/output/text_simple.dat");
```
Configure the output by specifying the name of the tree and the root file you want the data to be stored in.
```
builder.configure_output("SpartyJet_Tree","data/output/simple.root");
```
Give the command to run the algorithms on the first 10 events
```
builder.process_events(10);
```
Then running the script will process the first 10 events on the file specified in the input object and produce the .root file specified in configure_output. This is meant as a basic introduction, and there are a lot more functions than listed here. Look at the other scripts to see more features.

Alternate method of Running (with getjets function)

Newly added (first in v1.1) is a new method to running SpartyJet. This method is motivated towards providing an easier way to use algorithms "on the fly".
This method allows users to more easily use SpartyJet's algorithms from other C++ programs, without going through JetBuilder.
The current list of supported functions is listed below

```
Jet::jet_list_t SpartyJet::getjets(JetTool* tool, Jet::jet_list_t\& inputJets);
```
uses the Jet class that comes with spartyjet. If you convert your input to the Jet class, you may use this version, the output is also given in the same Jet class.
```
std::vector<TLorentzVector> SpartyJet::getjets(JetTool* tool, std::vector<TLorentzVector> & input);
```
uses a vector of TLorentzVectors. Inside that function it converts the input to the Jet class, runs the algorithm, and then returns the jets as a vector of TLorentzVectors

std::vector<TLorentzVector> SpartyJet::getjets( JetTool* tool, 
            std::vector<TLorentzVector> & input, std::vector<std::vector <int >> & constituents);

is same as 2 except it also gives constituent information in the form of vector< vector <int > > . The integers correspond to the position index in the input vector.

```
std::vector<simplejet> SpartyJet::getjets(JetTool* tool, std::vector<simplejet>& input);
```
this function uses a simple struct defined in GetJets.hh called simplejet
```
struct simplejet {
  TLorentzVector jet;
  double area; 
  double area_error;
  std::vector<TLorentzVector> constituents;
};
```
the getjets function accepts a vector of simplejets, (with no constituent information), and in return you will get a list of jets with the constituent information built in. Area information has been added to the simplejet structure to allow for saving of area values;

The functions are contained in JetCore/GetJets.hh and examples are given in SpartyJet/programs/getjets_Jet.C and getjets_TLorentzVector.C .
Type 'make getjets' to make these examples, and then you may run the executables getjets_jets.exe , getjets_tlv.exe , and getjets_sj.exe to test the functions.
If you have more ideas of simple types of input that you would like to be accepted by the getjets function, email the authors (emails below)

Input to SpartyJet

The JetBuilder class needs a InputMaker object to read input to the jet finder; the following input classes are implemented

NtupleInputMaker

For inputs in ROOT ntuple, the generic NtupleInputMaker should work in numerous cases. It reads variables from a ROOT ntuple either in the form (px,py,pz,e) either (rapidity,phi,pt,e) when these quantities are stored as array of float/double or std::vector of float/double. The user only needs to set the variable names.
See scripts/testBuilder.C

as an example.
If you don't know how variables are internally stored in your ntuple, follow these steps :

open a ROOT session, and load your TTree in a variable (say 'tree')
do tree->MakeClass("test")
open the file test.h : you should see your variables with the corresponding types.

An example of this type of input can be seen in data/AtlasClustersJ5.root
Explanation:

Create Object. The constructors argument is a code describing the input type :
```
NtupleInputMaker input("InputJet",NtupleInputMaker::EtaPhiPtE_vector_float);
```
see the list of known code in JetCore/InputMaker_Ntuple.hh
set the names of the variables, note that for each of the variables and for n, prefix is added to the beginning and suffix to the end so here, the 'e' branch is "cl_e_caltopo"
```
input.set_prefix("cl_");
input.set_suffix("_caltopo");
input.set_variables("eta","phi","pt","e");
input.set_n_name("nc");
```
set masslessMode if needed. Available only for EtaPhiPtE_* input. When set on, only Eta, Phi and E variables will be read to construct input jets.
```
input.set_masslessMode(true);
```

call setFileTree(filename,treename)

input.setFileTree("data/AtlasClustersJ5.root", "CollectionTree");

AtlasInputMaker

OBSOLETE , use NtupleInputMaker - Basically a modified specific version of NtupleInputMaker suited to read in ATLAS ntuples.

StdTextInput

This form of input reads an ASCII file containing lists of 4vectors. To separate events, put one of the following lines between the events

.Event (only the .E or .e is important)

.event

The Input will recognize any of those as the start of a new event.
The form of the four vectors should be

E px py pz

If the form is the opposite (px py pz E), then call the function

inputobject->invert_input_order(true);

and it will be read in properly. An example of this input can be seen in data/J1_Clusters.dat .

StdHepInput

This form of input reads StdHEP format XDR files. It will look for particles with the status code of 1 (final state). A sample script StdHeptest.C is under the scripts directory, but there is no sample file as of yet.

CalchepPartonTextInput

This form of input reads output from CALCHEP. It reads in the number of initial and final state particles, and then for each event saves only the information for the final state particles. An example of this can be seen in data/gg_ggg_events.dat

and the script calchep_input_test.C .

HepMCInput

This form of input reads HepMC format ascii files. HepMC ascii files contain the following separators

E - Denotes new event
V - Information about a vertex
P - Information about a particle

This class reads in the four vectors of the particles denoted with a status code of 1 (not decayed, final state). An example of this can be seen in data/HepMC_sample.dat, and the script HepMCtest.C

Input Options

Rejecting bad input
As a common function for all input classes, you may call

InputMaker->reject_bad_input(bool)

to set whether or not the input will check incoming 4-vectors and select only the ones that pass the check. The current default is false, no checks will be done. (an alternative to this method of dealing with bad input is given in the JetBuilder OPTIONS section).

JetBuilder Options

Constituents

To turn OFF constituent finding (to yield results without that discussed in RESULTS) you must add false as a second argument when using builder.add_default_alg.
Constituents tracking is ON by default.
For example:

// without constituents :
builder.add_default_alg( new cdf::JetClustFinder("myJetClu"),false);
//with constituents  : 
builder.add_default_alg( new cdf::JetClustFinder("myJetClu"));

The CellJet algorithm is currently incapable of determining constituent information, so if constituents are turned on, the branches in the ROOT TTree output will be empty.

Text File Output

The text file output option tells JetBuilder to produce a text file that contains a list of all jets found from all algorithms for all events.
The file is easy to read, and recommended for quick viewing of results.
To turn on the text file output, you must call builder.add_text_output , and pass it the filename you want to create. For example

builder.add_text_output("data/output/text_output.dat");

Minimum Bias events

JetBuilder allows the user to add minimum bias events to data events to test the effect they have on the data and the results found, for example.
To enable minimun bias events, one must create another input object of any type (StdTextInput,NtupleInput...), then call builder.add_minbias_events(int n,input);
where n is the number of minimum bias events you want to add to each data event. JetBuilder will start at the beginning of the minbias data file and read the first n events for the first data event, then the second n events for the second data event, so on. When the end of the minbias file is found, it will simply continue from the beginning.

Example of code to add minbias events

// Create an input object for the min bias events
StdTextInput MBinput("data/MB_Clusters.dat");
// Tell builder to add 5 minbias events from MBinput for each data event
builder.add_minbias_events(5,(InputMaker*)& MBinput);

NOTE - The effect of adding minimum bias events is totally dependent upon the data that is chosen for minimum bias. If the data is not mininum bias, then the effect of this feature will be different.

Rejecting Bad Input

To deal with bad input fourvectors, JetBuilder makes use of a JetTool called NegEnergyTool. It can call this function before and after the jet finder tool to

Keep track of the constituents with negative energy and inverse their sign, and
from each jet, check if its constituents were found in 1) and if so, correct back the energy.

The default is to NOT use this tool, and one may switch it on with : builder.do_correct_neg_energy(bool);

Results

When using the JetBuilder class (as in above example) the result is a ROOT ntuple containing jet variables for each algorithm added, plus variables for input particles to the jet algorithms.

Constituents

For all algorithms, (except CellJet in v1), constituents information is saved as follows.
Assuming a jet finder named "MyJet" has been added, one gets 2 variables :

MyJet_numC
MyJet_ind

MyJet_numC is an array of size MyJet_N and MyJet_numC[i] is the number of constituents of ith jet.

MyJet_ind is an array of size InputJet_N . MyJet_ind[i] is the index of the jet to which the ith input constituent has been assigned. For example in ROOT :

myTree->Draw("InputJet_e","FastKt_ind==0")

will give the energy distribution of constituents in jets number 0 (i.e. highest pt jets) for the FastKt_ collection.
With recent versions of SpartyJet, one can save output in the form of std::vector rather than plain float arrays.
The JetBuilder has the option (for now only std::vector<double>) :

builder.use_std_vector()

Analysis

Found in the scripts directory is a file called analysis.c. Running this file in root on an output file produced from SpartyJet will allow you to interactively and easily make a number of plots from the data.
Run the script from root by .x analysis.c(".root file location");
This is always a work in progress and may be buggy.

Algorithms

Here is a list of the algorithms with a list of the options and parameters that can be set.

Tools and jet moment calculators

YSplitter

The class 'YSplitterTool' included in SpartyJet is an implementation of the common ysplitter scheme. It runs the FastJet algorithm on the constituents on a jet, and returns y_values as described in numerous papers.
Some parameters involved in this implementation are
n_jets -> ysplitter will calculate y_vals for the first n jets
n_y_values -> ysplitter will return the first n y_values
For an example of this, see the sample script: script/ysplitter_test.C

Notes

A recent version of ROOT is needed. Most testing was done with v5.15.00. Starting with SpartyJet_v1.12, SpartyJet compiles under v4.04.02, and certain features have been tested.
Make sure to include Load libTree.so and libPhysics.so in root scripts
If you have an error related to midpoint second pass, then call

MidPointFinderObject.set_SavePassnum(false);

This will turn off the saving of the pass number information, which has been seen to cause problems in some cases
There are two ways to deal with bad input to SpartyJet, one is described in "Section" and one is described in "JetBuilder OPTIONS"

Any questions/comments/suggestions, email:

Pierre-Antoine Delsart : delsart@dontspamLPS.UMontreal.CA
Kurtis Geerlings : geerlin6@dontspam.msu.edu
Joey Huston : huston@dontspam.pa.msu.edu

About this document ...

SpartyJet documentation

This document was generated using the LaTeX2HTML translator Version 2002-2-1 (1.71)

The command line arguments were:
latex2html -split 0 -dir html -no_navigation SpartyJet_Documentation.tex

The translation was initiated by Pierre-Antoine Delsart on 2007-11-05

Pierre-Antoine Delsart 2007-11-05