Page MenuHomeHEPForge
Files F10664380

README
No OneTemporary
Actions

README
View Options

***********************************************************************
***********************************************************************
***** SpartyJet v1.11 *****
***** A generic framework for running multiple jet algorithms *****
***** last updated: October 15, 2007 *****
*****-------------------------------------------------------------*****
*****-------------------------------------------------------------*****
***** currently supports *****
***** ATLAS - fastkt *****
***** fastkt aachen *****
***** cone *****
***** CDF - JetClustering *****
***** MidPoint *****
***** second pass *****
***** D0 - improved legacy cone algorithm *****
***** (midpoint) *****
***** FastJet - fastjet kt *****
***** fastjet kt with aachen *****
***** SISCone plugin (seedless) *****
***** Pythia - CellJet *****
***********************************************************************
***********************************************************************
***********************************************************************
LICENSE:
***********************************************************************
This Software is under GNU General Public License v2.
***********************************************************************
AUTHORS:
***********************************************************************
Original software from
Kurtis L. Geerlings and Joey Huston, Michigan State University
This version :
Pierre-Antoine Delsart, Universite de Montreal
Kurtis L. Geerlings and Joey Huston, Michigan State University
------------------------------------
Third party jet algorithms :
------------------------------------
FastJet : Matteo Cacciari and Gavin Salam, LPTHE, Paris 6 & 7
http://www.lpthe.jussieu.fr/~salam/fastjet
ATLAS collaboration
CDF collaboration
CellJet : From Pythia 8, http://www.thep.lu.se/~torbjorn/Pythia.html
D0 collaboration
Improved Legacy Cone Algorithm is from Lars Sonnenschein
------------------------------------
***********************************************************************
INSTALLATION:
***********************************************************************
- 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.
***********************************************************************
USING GetJets Functions
***********************************************************************
- 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.
- since version 1.20, the getjets functions are wrapped in a 'SpartyJetTool'
class to allow for easier addition of additional JetTools,
like ysplitter
- The SpartyJet class, defined in JetCore/GetJets.hh operates as follows:
//Define object:
SpartyJetTool sparty;
//add any additional tools (if desired)
sparty.add_tool(ysplitter) // assuming ysplitter was previously declared
//get the jets
outputJets = sparty.getjets(JetTool* tool, Jet::jet_list_t& inputJets);
- There are three functions of the SpartyJet that may come in handy, and
they are fairly self-explanatory:
void add_tool(JetTool * tool);
void remove_tool(JetTool * tool);
void clear_additional_tools(bool do_delete = true );
- The four current possibilities for getjets functions are listed below:
JetCollection getjets(JetTool* tool,Jet::jet_list_t& inputJets);
std::vector<TLorentzVector> getjets(JetTool* tool,std::vector<TLorentzVector>&);
std::vector<TLorentzVector> getjets(JetTool* tool,std::vector<TLorentzVector>&,std::vector<std::vector<int> >&);
std::vector<SpartyJet::simplejet> getjets(JetTool* tool,std::vector<SpartyJet::simplejet>& input);
- The structure 'simplejet' used in one possibility above is defined as below,
and is defined within the SpartyJet namespace;
struct simplejet {
TLorentzVector jet;
double area;
double area_error;
std::vector<TLorentzVector> constituents;
};
- Examples of using getjets can be seen in the programs directory.
- If you have more ideas of simple types of input that you would like to be accepted
by the getjets functions, email the authors (emails at bottom)
- The previous functions to call SpartyJet::getjets without the
SpartyJetTool class, as outlined below, maintain functionality,
since the new code is backwards compatible.
-----------------------------------------------------------------------------
- The old list of supported functions is listed below
1) 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.
2) 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
3) std::vector<TLorentzVector> SpartyJet::getjets(
JetTool* tool,
std::vector<TLorentzVector>& input,
std::vector<std::vector<int> >& constituents);
is the 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.
4) std::vector<simplejet> SpartyJet::getjets(
JetTool* tool,
std::vector<simplejet>& input);
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;
***********************************************************************
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
constructors (char*, NtupleInputMaker),(NtupleInputMaker),(char*)
will all work
NtupleInputMaker input("InputJet",NtupleInputMaker::EtaPhiPt_vector_float);
- 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
input.set_masslessMode(true);
- call setFileTree(filename,treename)
input.setFileTree("data/AtlasClustersJ5.root", "CollectionTree");
AtlasInputMaker - OBSOLETE
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
N
n
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 1) keep track of the constituents with negative
energy and inverse their sign, and 2) 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);
***********************************************************************
other OPTIONS
***********************************************************************
Split/Merge flag
The SISCone, MidPoint, and JetClu algorithms have the ability to
track whether a jet was split or merged at any stage during the
algorithm. If this option is turned on, a branch in the output
ntuple will contain either 1 ( split/merged) or 0 (not split/merged).
To enable this option, call the following function. This
only works for SISCone, MidPoint and JetClu.
tool->set_saveSplitMerged(true);
An example of this use is found in scripts/option_examples.C
Save Pass Num
Since MidPointFinder has the option of running a second pass
algorithm, there is also the option to save a flag telling
which pass any jet is found in. This option adds a branch
to the output ntuple, with the value of either 1 or 2.
To enable this option, call the following function.
tool->set_savePassNum(true);
On some machines, this has seen to cause problems. If you
have problems related to the second pass of MidPointFinder,
call tool->set_savePassNum(false);
***********************************************************************
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.
***********************************************************************
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
***********************************************************************
- The following is a list of the algorithms with a list of the options
and parameters that can be set.
------------------------------------
- ATLAS - fastkt (aachen option)
------------------------------------
Constructors
atlas::FastKtTool(std::string name)
Functions
void simple_config(std::string findername, double param);
void set_other_propery(std::string name, float val);
void set_exclusiveN(int N); // if running exclusive mode with fixed Jet num
void set_exclusiveD(double ycut); // if running exclusive mode with fixed y cut:
------------------------------------
- ATLAS - cone
------------------------------------
Constructors
atlas::JetConeFinderTool( const std::string& name ="jconefindertool" );
Parameters Default
m_ptcut 0.0
m_eps 0.05
m_seedPt 2 GeV
m_etaMax 5
------------------------------------
- CDF - JetClustering
------------------------------------
Constructors
cdf::JetClustFinder(std::string name = "myJetClust")
Parameters Default
double seedThreshold 1GeV;
double coneRadius 0.7;
int adjacencyCut 2;
int maxIterations 100;
int iratch 1;
double overlapThreshold 0.75;
string m_name myJetClust;
Functions
void configure( double seedThreshold,
double coneRadius,
int adjacencyCut,
int maxIterations,
int iratch,
double overlapThreshold);
void set_seedThreshold(double)
void set_coneRadius(double)
void set_adjacencyCut(int)
void set_maxIterations(int)
void set_iratch(int)
void set_overlapThreshold(double)
void set_name(std::string)
------------------------------------
- CDF - MidPoint
------------------------------------
Constructors
cdf::MidPointFinder(std::string name = "myMidPoint",bool secondpass = false)
Parameters Default
string name myMidPoint
double seedThreshold 1;
double coneRadius 0.7;
double coneAreaFraction 0.25;
int maxPairSize 2;
int maxIterations 100;
double overlapThreshold 0.75;
int reduceConeSize 0;
bool savePassNum false; // controls saving of pass_num branch in TTree
bool do_second_pass false;
Functions
void configure( bool do_second_pass,
double seedThreshold,
double coneRadius,
double coneAreaFraction,
int maxPairSize,
int maxIterations,
double overlapThreshold,
int reduceConeSize);
void set_second_pass(bool)
void set_seedThreshold(double)
void set_coneRadius(double)
void set_coneAreaFraction(double)
void set_maxPairSize(int)
void set_maxIterations(int)
void set_overlapThreshold(double)
void set_reduceConeSize(int)
void set_name(std::string)
void set_savePassNum(bool)
------------------------------------
- D0 - improved legacy cone algorithm (midpoint)
------------------------------------
Constructors
D0::D0RunIIConeFinder(std::string name = "myD0cone",bool ssecondpass = false)
Parameters Default
string name myD0Cone
bool savePassNum false
bool do_second_pass false
float cone_radius 0.5
float min_jet_Et 0.0
float split_ratio 0.5
float far_ratio 0.5
float Et_min_ratio 0.5
bool kill_duplicate true
float duplicate_dR 0.005
float duplicate_dPT 0.01
float search_factor 1.0
float pT_min_leading_protojet 0.0
float pT_min_second_protojet 0.0
int merge_max 10000
float pT_min_nomerge 0.0
float Item_ET_Threshold 0.0
float Zvertex 0.0
Functions
void configure( bool do_second_pass,
float cone_radius,
float min_jet_Et,
float split_ratio,
float far_ratio,
float Et_min_ratio,
bool kill_duplicate,
float duplicate_dR,
float duplicate_dPT,
float search_factor,
float pT_min_leading_protojet,
float pT_min_second_protojet,
int merge_max,
float pT_min_nomerge,
float Item_ET_Threshold,
float Zvertex);
void set_second_pass(bool)
void set_name(std::string)
void set_savePassNum(bool)
void set_coneRadius(float)
void set_minJetEt(float)
void set_splitRatio(float)
void set_farRatio(float)
void set_EtMinRatio(float)
void set_killDuplicate(bool)
void set_duplicate_dR(float)
void set_duplicate_dPT(float)
void set_searchFactor(float)
void set_pTMinLeadingProtojet(float)
void set_pTMinSecondProtojet(float)
void set_mergeMax(int)
void set_pTMinNoMerge(float)
void set_itemEtThreshold(float)
void set_Zvertex(float)
------------------------------------
- FastJet - fastkt (aachen option)
------------------------------------
Constructors
fastjet::FastJetFinder( std::string name = "myFastJet",
bool aachen = false,
bool area = true)
Parameters Default
string name myFastJet
bool aachen false
bool area true // area calculation is fast enough to be default
bool inclusive true // includes inclusive jets in output
bool exclusive false // includes exclusive jets in output
int strategy fastjet::Best
double Rparam 1.0
double ptmin 5.0
double dcut 25.0
double ghost_etamax 6.0
int repeat 5
double ghost_area 0.01
double grid_scatter 1E-4
double kt_scatter 0.01
double mean_ghost_kt 1E-100
Functions
void set_strategy(int)
void set_name(std::string)
void configure( bool aachen,
bool area,
bool inclusive,
bool exclusive,
double Rparam,
double ptmin,
double dcut);
void set_aachen(bool)
void set_area(bool)
void set_inclusive(bool)
void set_exclusive(bool)
void set_Rparam(double)
void set_ptmin(double)
void set_dcut(double)
void configure_area(double ghost_etamax,
int repeat,
double ghost_area,
double grid_scatter,
double kt_scatter,
double mean_ghost_kt);
void set_ghost_etamax(double)
void set_repeat(int)
void set_ghost_area(double)
void set_grid_scatter(double)
void set_kt_scatter(double)
void set_mean_ghost_kt(double)
------------------------------------
- FastJet - SISCone
------------------------------------
Constructors
fastjet::SISConeFinder( std::string name = "mySISCone",
bool area = false)
fastjet::SISConeFinder( bool area)
fastjet::SISConeFinder( char* name,
bool area = false)
Parameters Default
string name mySISCone
bool area false // area is fairly slow in SISCone
bool inclusive true // includes inclusive jets in output
bool exclusive false // includes exclusive jets in output
double coneRadius 0.7
double overlapThreshold 0.75
int nPassMax 0
double protojetptmin 0.0
int caching 0
double ghost_etamax 6.0
int repeat 5
double ghost_area 0.1
double grid_scatter 1E-4
double kt_scatter 0.01
double mean_ghost_kt 1E-100
Functions
void set_strategy(int)
void set_name(std::string)
void configure( bool area,
bool inclusive,
bool exclusive,
double coneRadius,
double overlapThreshold,
int npassMax,
double protojetptmin,
int caching);
void set_area(bool)
void set_inclusive(bool)
void set_exclusive(bool)
void set_coneRadius(double)
void set_overlapThreshold(double)
void set_nPassMax(int)
void set_ptmin(double)
void set_caching(int)
void configure_area( double ghost_etamax,
int repeat,
double ghost_area,
double grid_scatter,
double kt_scatter,
double mean_ghost_kt);
void set_ghost_etamax(double)
void set_repeat(int)
void set_ghost_area(double)
void set_grid_scatter(double)
void set_kt_scatter(double)
void set_mean_ghost_kt(double)
------------------------------------
- Pythia - CellJet
------------------------------------
- NOTE: constituent finding does not currently work for celljet.
If you have it turned on, blank branches will be produced in the TTree
Constructors
celljet::CellJetFinder(std::string name = "myCellJet")
Parameters Default
string name myCellJet
double eTjetMinIn 0.0
double coneRadiusIn 0.7
double eTseedIn 1.5
Functions
void configure( double eTjetMinIn,
double coneRadiusIn,
double eTseedIn);
void set_minEt(double)
void set_coneRadius(double)
void set_seedEt(double)
void set_name(std::string)
***********************************************************************
Additional JetTools
***********************************************************************
- 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/option_examples.C
- NOTE: add_moments() has to be done AFTER the algorithms are added to the builder
***********************************************************************
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 "Input OPTIONS" and one is described in "JetBuilder OPTIONS"
***********************************************************************
Any questions/comments/suggestions, email:
Pierre-Antoine Delsart : delsart@LPS.UMontreal.CA
Kurtis Geerlings : geerlin6@msu.edu
Joey Huston : huston@pa.msu.edu

File Metadata

Mime Type
text/x-asm
Expires
Thu, Apr 24, 6:37 AM (1 d, 19 h)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
4838920
Default Alt Text
README (29 KB)

Event Timeline