ktjet is hosted by Hepforge, IPPP Durham

KtJet User Guide v1-05

More information can be found in the KtJet Paper and examples of using KtJet are given in Examples.

Introduction

Performing KT-clustering using the KtJet package is extremely simple, it basically involves instantiating a KtEvent object with a std::vector of input "particles" and a number of flags to set the KtEvent parameters. The input "particles" can be in the form of either HepLorentzVectors or KtLorentzVectors. The KtEvent objects can then be interrogated about the event using its simple public interface.

KtEvent

KtEvent can be instantiated in inclusive, exclusive or sub-jet mode. The inclusive mode has the following constructors:

  • KtEvent(const std::vector<KtLorentzVector> &, int type, int angle, int recom, KtFloat rparameter);
  • KtEvent(const std::vector<HepLorentzVector> &, int type, int angle, int recom, KtFloat rparameter);
  • KtEvent(const std::vector<KtLorentzVector> &, int type, KtDistance *, KtRecom *, KtFloat rparameter);
  • KtEvent(const std::vector<KtLorentzVector> &, int type, KtDistance *, int recom, KtFloat rparameter);
  • KtEvent(const std::vector<KtLorentzVector> &, int type, int angle, KtRecom *, KtFloat rparameter);

The first two of the constructors are the simplest to understand. The user passes KtEvent a std::vector of input LorentzVectors, three integer flags and the rparameter. The rparameter is of type KtFloat which is simply a typedef which defaults to float (but can be changed to double as a compiler option).

The three integer flags are: type, which sets the collision type; angle, which sets the distance scheme; recom, which sets the recombination scheme. A brief overview of the available options for each of these is given in table 1.0. A full description is given in the KtJet Paper.

type angle recom
1ee1angular1E
2eP2delta R2Pt
3Pe3QCD 3Pt2
4PP 4Et
5Et2
Table 1.0: KtJet Constructor flags

The other three constructors are much the same as the first two except they allow the passing of pointers to user defined recombination and distance schemes rather than integer flags. Defining your own schemes is discussed in further detail here.

Although KtEvent can take either HepLorentzVectors or KtLorentzVectors in its constructor, it is recommended that KtLorentzVectors are used as this gives greater functionality when interrogating the instantiated KtEvent object. Further information on using KtLorentzVectors can be found here.

Once that the KtEvent has been constructed in inclusive mode the final state jets are fully defined. They may be recovered from the KtEvent using the following methods:

std::vector<KtLorentzVector> getJets(); Return final state jets without sorting
std::vector<KtLorentzVector> getJetsE(); Return jets in order of decreasing E
std::vector<KtLorentzVector> getJetsEt(); Return final state jets in order of decreasing Et
std::vector<KtLorentzVector> getJetsPt(); Return final state jets in order of decreasing Pt
std::vector<KtLorentzVector> getJetsRapidity(); Return final state jets in order of decreasing rapidity
std::vector<KtLorentzVector> getJetsEta(); Return final state jets in order of decreasing pseudorapidity

If KtLorentzVectors were used as input into the KtEvent constructor there is a further method which will return the final state jet which contains the input KtLorentzVector.

  • KtLorentzVector getJet(const KtLorentzVector &) const;

In addition to these Jet returning methods, KtEvent has the following informational methods that are useful with the inclusive mode:

int getNJets() const; Return the number of final state jets
int getNConstituents() const; Return the number of objects input to KtEvent
std::vector<const KtLorentzVector *> getConstituents() const; Return pointers to the input particles
std::vector<KtLorentzVector> copyConstituents() const; Return copies of the input particles
KtFloat getETot() const; Return total energy in the event
int getType() const; Return collision type
int getAngle() const; Return distance ("angle") scheme
int getRecom() const; Return recombination scheme
bool isInclusive() const; Return inclusive flag: true if inclusive method constructor was used

The exclusive mode has the following constructors:

  • KtEvent(const std::vector<KtLorentzVector> &, int type, int angle, int recom);
  • KtEvent(const std::vector<HepLorentzVector> &, int type, int angle, int recom);
  • KtEvent(const std::vector<KtLorentzVector> &, int type, KtDistance *, KtRecom *);
  • KtEvent(const std::vector<KtLorentzVector> &, int type, KtDistance *, int recom);
  • KtEvent(const std::vector<KtLorentzVector> &, int type, int angle, KtRecom *);

These are the same as the inclusive mode, except without the rparameter. Once exclusive KtEvent object has been instantiated the final state jets can be defined by:

  • setting either the stopping parameter d_cut
    void findJetsD(KtFloat dCut);
  • or by forcing the final state to decompose into N jets
    void findJetsN(int nJets);

In the case of an e+e- analysis, the variable y_cut may be used. The final state jets are defined by the method
void findJetsY(KtFloat yCut);

The E_cut value can also be set (the default value is the total energy of the event):
void setECut(KtFloat eCut);

The exclusive KtEvent Object can also be interrogated about the d_cut and y_cut values when n+1 jets merged into n jets:
KtFloat getDMerge(int nJets) const;
KtFloat getYMerge(int nJets) const;

In addition to these methods, any of those used in the inclusive mode may also be used.

KtJet may also be used to perform sub-jet analysis on any of the output final state jets. This is a simple matter of constructing a KtEvent object with one of the output final state jets. This can be used in the same way as when performing exclusive jet finding in the e+e- mode. KtEvent has the following constructors for sub-jet analysis, they should by now have a familiar structure to the user, except they take a single KtLorentzVector "Jet" instead of a std::vector of "particles".

  • KtEvent(const KtLorentzVector jet, int angle, int recom);
  • KtEvent(const KtLorentzVector & jet, KtDistance *, KtRecom *);
  • KtEvent(const KtLorentzVector & jet, KtDistance *, int recom);
  • KtEvent(const KtLorentzVector & jet, int angle, KtRecom *);

KtLorentzVector

All input "particle" and output "jet" objects in KtJet are KtLorentzVectors. KtEvents can be instantiated with HepLorentzVectors, but the first thing KtEvent does is construct KtLorentVectors from these. KtLorentzVector inherit from CLHEPs HepLorentzVector and adds extra functionality so they can be tracked easily inside KtEvent. It has the following constructors:

  • KtLorentzVector();
  • KtLorentzVector(const HepLorentzVector &);
  • KtLorentzVector(KtFloat px, KtFloat py, KtFloat pz, KtFloat e);

When KtLorentzVectors are added together the resulting KtLorentzVector contains a std::vector of its constituents. Information about a KtLorentzVector's constituents can be gained using the following methods.

const std::vector<const KtLorentzVector*> & getConstituents() const; return a reference to the vector of constituents
std::vector<KtLorentzVector> copyConstituents() const; copy constituents
inline int getNConstituents() const; returns the number of constituents KtLorentzVector is made up of
bool contains(const KtLorentzVector &) const; check if a given KtLorentzVector is a constituent of this one

A KtLorentzVector can also be queried as to whether it is a Jet (has constituents) or not.
bool isJet() const;

KtLorentzVector has two extra methods for adding two KtLorentzVectors together. One which does simple 4 vector adding (E-scheme) and one which takes a recombination scheme as an argument and uses this to combine the KtLorentzVectors.

  • void add(const KtLorentzVector &, KtRecom *recom);
  • void add(const KtLorentzVector &);

There is also a operator+= which simply adds the the KtLorentzVectors using the E-scheme.

  • KtLorentzVector & operator+= (const KtLorentzVector &);

Finally there are four comparison operators.

  • bool operator== (const KtLorentzVector &) const;
  • bool operator!= (const KtLorentzVector &) const;
  • bool operator> (const KtLorentzVector &) const;
  • bool operator< (const KtLorentzVector &) const;

It is important to note that these functions ONLY compare the KtLorentzVectors IDs. So the opertator== function will return true for two KtLorentzVectors with the same ID number even if their four-momentums are different. The decision to do this was taken because it improves the performance of KtJet and makes the use of STL containers much simpler for the users. The HepLorentzVector comparison, which just compares the four momentum, can still be used on KtLorentzVectors, but involves much more convoluted calls. For example, the four momentum of two KtLorentzVectors, vec0 and vec1, can be compared as follows:

  • vec0.HepLorentzVector::operator==(vec1)

Example Code

For examples on how to run with KtJet see Examples

Defining distance and recombination schemes

For information on how to define your own distance and recombination schemes go here