Jet Reconstruction Public Documentation

addjets(jet1::T, jet2::T; cluster_hist_index::Int) where {T <: FourMomentum}

Add jets' four momenta together, returning a new jet of type T with the specified cluster history index.

Details

This method is also known as the E_scheme in Fastjet.

addjets_pt2scheme(jet1::T, jet2::T, cluster_hist_index::Int) where {T <: FourMomentum}

Use the massless $p_T^2$ scheme for combining two jets, setting the appropriate cluster history index for the new jet.

addjets_ptscheme(jet1::T, jet2::T, cluster_hist_index::Int) where {T <: FourMomentum}

Use the massless $p_T$ scheme for combining two jets, setting the appropriate cluster history index for the new jet.

constituent_indexes(jet::T, cs::ClusterSequence{T}) where T <: FourMomentum

Return the indexes of the original particles which are the constituents of the given jet.

Arguments

• jet::T: The jet for which to retrieve the constituents.
• cs::ClusterSequence{T}: The cluster sequence object.

Returns

An vector of indices representing the original constituents of the given jet.

constituents(jet::T, cs::ClusterSequence{T}) where T <: FourMomentum

Get a copy of the constituents of a given jet in a cluster sequence.

Arguments

• cs::ClusterSequence{T}: The cluster sequence object.
• jet::T: The jet for which to retrieve the constituents.

Returns

An array of jet objects (which are of the same type as the input jet) copied from the constituents of the given jet, with reset cluster history indexes.

ee_genkt_algorithm(particles::AbstractVector{T}; algorithm::JetAlgorithm.Algorithm,
                   p::Union{Real, Nothing} = nothing, R = 4.0, recombine = addjets,
                   preprocess = nothing) where {T}

Run an e+e- reconstruction algorithm on a set of initial particles.

Arguments

• particles::AbstractVector{T}: A vector of particles to be clustered.
• algorithm::JetAlgorithm.Algorithm: The jet algorithm to use.
• p::Union{Real, Nothing} = nothing: The power parameter for the algorithm. Must be specified for EEKt algorithm. Other algorithms will ignore this value.
• R = 4.0: The jet radius parameter. Not required / ignored for the Durham algorithm.
• recombine: The recombination scheme to use.
• preprocess: Preprocessing function for input particles.

Returns

• The result of the jet clustering as a ClusterSequence object.

Notes

This is the public interface to the e+e- jet clustering algorithm. The function will check for consistency between the algorithm and the power parameter as needed. It will then prepare the internal EDM particles for the clustering itself, and call the actual reconstruction method _ee_genkt_algorithm.

If the algorithm is Durham, R is nominally set to 4. If the algorithm is EEkt, power p must be specified.

exclusive_jets(clusterseq::ClusterSequence{U}; dcut = nothing, njets = nothing, T = LorentzVectorCyl) where {U}

Return all exclusive jets of a ClusterSequence, with either a specific number of jets or a cut on the maximum distance parameter.

Arguments

• clusterseq::ClusterSequence: The ClusterSequence object containing the clustering history and jets.
• dcut::Union{Nothing, Real}: The distance parameter used to define the exclusive jets. If dcut is provided, the number of exclusive jets will be calculated based on this parameter.
• njets::Union{Nothing, Integer}: The number of exclusive jets to be calculated. If njets is provided, the distance parameter dcut will be calculated based on this number.
• T = LorentzVectorCyl: The return type used for the selected jets.

Note: Either dcut or njets must be provided (but not both).

Returns

• An array of T objects representing the exclusive jets.

Valid return types are LorentzVectorCyl and the jet type of the input clusterseq (U - either PseudoJet or EEJet depending which algorithm was used) (N.B. this will evolve in the future to be any subtype of FourMomentumBase; currently unrecognised types will return LorentzVectorCyl).

Exceptions

• ArgumentError: If neither dcut nor njets is provided.
• ArgumentError: If the algorithm used in the ClusterSequence object is not suitable for exclusive jets.
• ErrorException: If the cluster sequence is incomplete and exclusive jets are unavailable.

Examples

exclusive_jets(clusterseq, dcut = 20.0)
exclusive_jets(clusterseq, njets = 3, T = PseudoJet)

final_jets(jets::Vector{PseudoJet}, ptmin::AbstractFloat=0.0)

This function takes a vector of PseudoJet objects and a minimum transverse momentum ptmin as input. It returns a vector of FinalJet objects that satisfy the transverse momentum condition.

Arguments

• jets::Vector{PseudoJet}: A vector of PseudoJet objects representing the input jets.
• ptmin::AbstractFloat=0.0: The minimum transverse momentum required for a jet to be included in the final jets vector.

Returns

A vector of FinalJet objects that satisfy the transverse momentum condition.

Specialisation for final jets from LorentzVectorCyl (TODO: merge into more general function)

Specialisation for final jets from LorentzVectors (TODO: merge into more general function)

inclusive_jets(clusterseq::ClusterSequence{U}; ptmin = 0.0, T = LorentzVectorCyl) where {U}

Return all inclusive jets of a ClusterSequence with pt > ptmin.

Arguments

• clusterseq::ClusterSequence: The ClusterSequence object containing the clustering history and jets.
• ptmin::Float64 = 0.0: The minimum transverse momentum (pt) threshold for the inclusive jets.
• T = LorentzVectorCyl: The return type used for the selected jets.

Returns

An array of T objects representing the inclusive jets.

Description

This function computes the inclusive jets from a given ClusterSequence object. It iterates over the clustering history and checks the transverse momentum of each parent jet. If the transverse momentum is greater than or equal to ptmin, the jet is added to the array of inclusive jets.

Valid return types are LorentzVectorCyl and the jet type of the input clusterseq (U - either PseudoJet or EEJet depending which algorithm was used) (N.B. this will evolve in the future to be any subtype of FourMomentumBase; currently unrecognised types will return LorentzVectorCyl).

Example

inclusive_jets(clusterseq; ptmin = 10.0)

jet_filtering(jet::PseudoJet, clusterseq::ClusterSequence{PseudoJet}; radius::Real,
                   hardest_jets::Integer) -> PseudoJet

Filters a jet to retain only the hardest subjets based on a specified radius and number.

Arguments:

• jet::PseudoJet: PseudoJet instance representing the jet to filter.
• clusterseq::ClusterSequence{PseudoJet}: ClusterSequence containing jet history.
• radius::Real: Radius parameter to recluster subjets.
• hardest_jets::Integer: Number of hardest jets to retain in the filtered result.

Returns:

• PseudoJet: Filtered jet composed of the hardest subjets.

jet_reconstruct(particles::AbstractVector; algorithm::JetAlgorithm.Algorithm,
                     p::Union{Real, Nothing} = nothing, R = 1.0,
                     recombine = addjets, preprocess = nothing,
                     strategy::RecoStrategy.Strategy = RecoStrategy.Best)

Reconstructs jets from a collection of particles using a specified algorithm and strategy.

Arguments

• particles::AbstractVector: A collection of particles used for jet reconstruction.
• algorithm::JetAlgorithm.Algorithm: The algorithm to use for jet reconstruction.
• p::Union{Real, Nothing} = nothing: The power value used for the distance measure for generalised k_T algorithms (GenKt, EEKt). Other algorithms will ignore this value.
• R = 1.0: The jet radius parameter.
• recombine = addjets: The recombination scheme used for combining particles.
• preprocess = nothing: The function to preprocess the particles before reconstruction (e.g., for massless schemes). nothing means the particles are not preprocessed.
• strategy::RecoStrategy.Strategy = RecoStrategy.Best: The jet reconstruction strategy to use. RecoStrategy.Best makes a dynamic decision based on the number of starting particles.

Note that p must be specified for GenKt and EEKt algorithms, other algorithms will ignore its value. When an algorithm has no R dependence the R parameter is ignored.

Returns

A cluster sequence object containing the reconstructed jets and the merging history.

Details

particles argument

Any type that supplies the methods pt2(), phi(), rapidity(), px(), py(), pz(), energy() (in the JetReconstruction namespace) can be used. This includes LorentzVector, LorentzVectorCyl, PseudoJet and EEJet, for which these methods are already predefined in the JetReconstruction namespace.

Note when using PseudoJet or EEJet, the history indices (_cluster_hist_index) must be set correctly. For initial jets, this means assigning to each jet its index in the vector if you construct them manually. When using other jet types correct indices are set automatically internally.

recombine argument

The recombine argument is the function used to merge pairs of particles. The default is addjets, which uses 4-momenta addition (a.k.a. the E-scheme).

preprocess argument

The preprocess argument is a function that will be called for all original input particles and which returns a new particle, usually matching a non-standard recombination scheme, e.g., massless particles for $p_T$ or $p_T^2$ recombination. nothing means no preprocessing is done.

Example

jet_reconstruct(particles; algorithm = JetAlgorithm.AntiKt, R = 0.4)
jet_reconstruct(particles; algorithm = JetAlgorithm.Kt, R = 1.0)
jet_reconstruct(particles; algorithm = JetAlgorithm.Durham)
jet_reconstruct(particles; algorithm = JetAlgorithm.GenKt, p = 0.5, R = 1.0)
jet_reconstruct(particles; algorithm = JetAlgorithm.AntiKt, R = 1.0, preprocess = preprocess_ptscheme, 
                recombine = addjets_ptscheme)

jet_trimming(jet::PseudoJet, clusterseq::ClusterSequence{PseudoJet}; radius::Real,
                  fraction::Real, recluster_method::JetAlgorithm.Algorithm) -> PseudoJet

Trims a jet by removing subjets with transverse momentum below a specified fraction.

Arguments:

• jet::PseudoJet: PseudoJet instance representing the jet to trim.
• clusterseq::ClusterSequence{PseudoJet}: ClusterSequence containing jet history.
• radius::Real: Radius used for reclustering in trimming.
• fraction::Real: Minimum momentum fraction for retained subjets.
• recluster_method::JetAlgorithm.Algorithm: Method identifier for reclustering.

Returns:

• PseudoJet: Trimmed jet composed of retained subjets.

kt_scale(jet1::T, jet2::T) where {T <: FourMomentum}

Computes the transverse momentum scale as the product of the minimum pt and the angular separation in the η-ϕ plane (using pseudorapidity).

Returns

• The transverse momentum scale of the two jets.

lorentzvector(jet::T) where {T <: FourMomentum} ->  -> LorentzVector

Return a cartesian LorentzVector from a jet.

lorentzvector_cyl(jet::T) where T <: FourMomentum -> LorentzVectorHEP.LorentzVectorCyl

Return a cylindrical LorentzVectorCyl from a jet.

mass_drop(jet::PseudoJet, clusterseq::ClusterSequence{PseudoJet}; mu::Real,
               y::Real) -> PseudoJet

Identifies subjets in a jet that pass the mass drop tagging condition. The method stops at the first jet satisfying the mass and distance thresholds.

Arguments:

• jet::PseudoJet: PseudoJet instance representing the jet to tag.
• clusterseq::ClusterSequence{PseudoJet}: ClusterSequence with jet clustering history.
• mu::Real: Maximum allowed mass ratio for a jet to pass tagging.
• y::Real: Minimum kT distance threshold for parent separation.

Returns:

• PseudoJet: The jet (or subjet) satisfying the mass drop conditions, if tagging is successful, otherwise invalid_pseudojet object

n_exclusive_jets(clusterseq::ClusterSequence; dcut::AbstractFloat)

Return the number of exclusive jets of a ClusterSequence that are above a certain dcut value.

Arguments

• clusterseq::ClusterSequence: The ClusterSequence object containing the clustering history.
• dcut::AbstractFloat: The maximum value for the distance parameter in the reconstruction.

Returns

The number of exclusive jets in the ClusterSequence object.

Example

n_exclusive_jets(clusterseq, dcut = 20.0)

parent_jets(jet::T, cs::ClusterSequence{T})::Tuple{Union{Nothing, T}, Union{Nothing, T}} where {T <: FourMomentum}

Find the parent jets of a given jet in a cluster sequence.

Arguments

• jet::T: The jet for which to find the parent jets.
• cs::ClusterSequence: The cluster sequence object.

Returns

A tuple of two elements, each of which is either the parent jet object or nothing (if the jet has no parent).

plain_jet_reconstruct(particles::AbstractVector{T};
                      algorithm::JetAlgorithm.Algorithm,
                      p::Union{Real, Nothing} = nothing, R = 1.0,
                      recombine = addjets, preprocess = nothing) where {T}

Perform pp jet reconstruction using the plain algorithm.

Arguments

• particles::AbstractVector{T}: A vector of particles used for jet reconstruction, any array of particles, which supports suitable 4-vector methods, viz. pt2(), phi(), rapidity(), px(), py(), pz(), energy(), can be used for each element.
• algorithm::JetAlgorithm.Algorithm: The jet algorithm to use.
• p::Union{Real, Nothing} = nothing: The power value used for jet reconstruction. Must be specified for GenKt algorithm. Other algorithms will ignore this value.
• R = 1.0: The radius parameter used for jet reconstruction.
• recombine::Function = addjets: The recombination function used to combine particles into a new jet.
• preprocess::Function = nothing: A function to preprocess the input particles.

Note for the particles argument, the 4-vector methods need to exist in the JetReconstruction package namespace.

This code will use the k_t algorithm types, operating in (rapidity, φ) space.

Returns

• Vector{PseudoJet}: A vector of reconstructed jets.

Example

jets = plain_jet_reconstruct(particles; p = -1, R = 0.4)
jets = plain_jet_reconstruct(particles; algorithm = JetAlgorithm.Kt, R = 1.0)

const preprocess_pt2scheme = preprocess_ptscheme

Preprocessing for p_T and p_T^2 schemes are identical.

preprocess_massless_pt(jet::T) where {T <: FourMomentum}

Jet preprocessor for the massless $p_T$ schemes, resetting the energy of the jet to be equal to the 3-momentum of the input jet.

preprocess_ptscheme(particle::Union{LorentzVector, LorentzVectorCyl};
                         cluster_hist_index::Int = 0,
                         jet_type = PseudoJet)

Jet preprocessor for the massless $p_T$ schemes, resetting the energy of the jet to be equal to the 3-momentum of the input jet (generic particle type).

Details

This function is used to convert a particle of type LorentzVector or LorentzVectorCyl into a jet_type object, which is a subtype of FourMomentum. (This is a work around until LorentzVectorBase can be used, which will make the accessors uniform.)

pt_fraction(jet1::T, jet2::T) where T <: FourMomentum

Computes the transverse momentum fraction of the softer of two jets.

Returns

• The transverse momentum fraction of the softer of the two jets.

read_final_state_particles(fname; maxevents = -1, skipevents = 0, T=PseudoJet)

Reads final state particles from a file and returns them as a vector of type T.

Arguments

• fname: The name of the HepMC3 ASCII file to read particles from. If the file is gzipped, the function will automatically decompress it.
• maxevents=-1: The maximum number of events to read. -1 means all events will be read.
• skipevents=0: The number of events to skip before an event is included.
• T=PseudoJet: The type of object to construct and return.

Returns

A vector of vectors of T objects, where each inner vector represents all the particles of a particular event. In particular T can be PseudoJet or a LorentzVector type. Note, if T is not PseudoJet, the order of the arguments in the constructor must be (t, x, y, z).

soft_drop(jet::PseudoJet, clusterseq::ClusterSequence{PseudoJet}; zcut::Real,
               beta::Real, radius::Real = 1.0) -> PseudoJet

Applies soft-drop grooming to remove soft, wide-angle radiation from jets. This function reclusters the jet and iteratively checks the soft-drop condition on subjets.

Arguments:

• jet::PseudoJet: PseudoJet instance to groom.
• clusterseq::ClusterSequence{PseudoJet}: ClusterSequence containing jet history.
• zcut::Real: Minimum allowed energy fraction for subjets.
• beta::Real: Angular exponent controlling soft radiation suppression.
• radius::Real: The new radius that will be used to recluster the components of the jet, by default set to 1.0.

Returns:

• PseudoJet: Groomed jet or invalid_pseudojet object if grooming fails.

tiled_jet_reconstruct(particles::AbstractVector{T};
                      algorithm::JetAlgorithm.Algorithm,
                      p::Union{Real, Nothing} = nothing, R = 1.0,
                      recombine = addjets, preprocess = nothing) where {T}

Main jet reconstruction algorithm entry point for reconstructing jets using the tiled strategy for generic jet type T.

This code will use the k_t algorithm types, operating in (rapidity, φ) space.

It is not necessary to specify both the algorithm and the p (power) value. If both are given they must be consistent or an exception is thrown.

Arguments

• particles::AbstractVector{T}: A vector of particles used as input for jet reconstruction. T must support methods px, py, pz and energy (defined in the JetReconstruction namespace).
• algorithm::JetAlgorithm.Algorithm: The jet algorithm to use.
• p::Union{Real, Nothing} = nothing: The power value used for jet reconstruction. Must be specified for GenKt algorithm. Other algorithms will ignore this value.
• R = 1.0: The jet radius parameter for the jet reconstruction algorithm.
• recombine::Function = addjets: The recombination function used to combine particles into a new jet.
• preprocess::Function = nothing: A function to preprocess the input particles.

Returns

• Vector{PseudoJet}: A vector of reconstructed jets.

Example

tiled_jet_reconstruct(particles::Vector{LorentzVectorHEP}; p = -1, R = 0.4)

struct ClusterSequence

A struct holding the full history of a jet clustering sequence, including the final jets.

Fields

• algorithm::JetAlgorithm.Algorithm: The algorithm used for clustering.
• strategy::RecoStrategy.Strategy: The strategy used for clustering.
• power::Float64: The power value used for the clustering algorithm (not that this value is always stored as a Float64 to be type stable)
• R::Float64: The R parameter used for the clustering algorithm.
• jets::Vector{T}: The actual jets in the cluster sequence, which are of type T <: FourMomentum.
• n_initial_jets::Int: The initial number of particles used for exclusive jets.
• history::Vector{HistoryElement}: The branching history of the cluster sequence. Each stage in the history indicates where to look in the jets vector to get the physical PseudoJet.
• Qtot::Any: The total energy of the event.

ClusterSequence(algorithm::JetAlgorithm.Algorithm, p::Real, R::Float64, strategy::RecoStrategy.Strategy, jets::T, history, Qtot) where T <: FourMomentum

Construct a ClusterSequence object.

Arguments

• algorithm::JetAlgorithm.Algorithm: The algorithm used for clustering.
• p::Real: The power value used for the clustering algorithm.
• R::Float64: The R parameter used for the clustering algorithm.
• strategy::RecoStrategy.Strategy: The strategy used for clustering.
• jets::Vector{T}: The jets in the cluster sequence, which are of T <: FourMomentum
• history::Vector{HistoryElement}: The branching history of the cluster sequence.
• Qtot::Any: The total energy of the event.

struct EEJet <: FourMomentum

The EEJet struct is a 4-momentum object used for the e+e jet reconstruction routines.

Fields

• px::Float64: The x-component of the jet momentum.
• py::Float64: The y-component of the jet momentum.
• pz::Float64: The z-component of the jet momentum.
• E::Float64: The energy of the jet.
• _cluster_hist_index::Int: The index of the cluster histogram.
• _p2::Float64: The squared momentum of the jet.
• _inv_p::Float64: The inverse momentum of the jet.

EEJet(px::Real, py::Real, pz::Real, E::Real, cluster_hist_index::Int)

Constructs an EEJet object from the given momentum components, energy, and cluster history index.

Details

If the default value of cluster_hist_index=0 is used, the EEJet cannot be used in a reconstruction sequence.

EEJet(jet::Any; cluster_hist_index::Int = 0)

Construct a EEJet from a generic object jet with the given cluster index. This functions also for LorentzVectorCyl objects.

Details

This function is used to convert a generic object jet into an EEJet, for this to work the object must have the methods px, py, pz, and energy defined, which are used to extract the four-momentum components of the object.

The cluster_hist_index is optional, but needed if the jet is part of a reconstruction sequence. If not provided, it defaults to 0 as an "invalid" value.

EEJet(jet::LorentzVector; cluster_hist_index::Int = 0)

Construct a EEJet from a LorentzVector object with optional cluster index.

EEJet(jet::PseudoJet; cluster_hist_index::Int=0)

Constructs an EEJet from a PseudoJet.

Details

The cluster_hist_index is set to the value of the cluster_hist_index of the PseudoJet if 0 is passed. Otherwise it is set to the value, >0, passed in.

struct FinalJet

A struct representing the final properties of a jet, used for JSON serialisation.

Fields

• rap::Float64: The rapidity of the jet.
• phi::Float64: The azimuthal angle of the jet.
• pt::Float64: The transverse momentum of the jet.

struct FinalJets

A struct with the vector of all jets for a certain jet identifier, used for JSON serialisation.

Fields

• jetid::Int64: The ID of the jet.
• jets::Vector{FinalJet}: A vector of FinalJet objects representing the jets.

struct PseudoJet <: FourMomentum

The PseudoJet struct represents a pseudojet, a four-momentum object used in jet reconstruction algorithms. Additional information for the link back into the history of the clustering is stored in the _cluster_hist_index field. There is caching of the more expensive calculations for rapidity and azimuthal angle.

Fields

• px::Float64: The x-component of the momentum.
• py::Float64: The y-component of the momentum.
• pz::Float64: The z-component of the momentum.
• E::Float64: The energy component of the momentum.
• _cluster_hist_index::Int: The index of the cluster history.
• _pt2::Float64: The squared transverse momentum.
• _inv_pt2::Float64: The inverse squared transverse momentum.
• _rap::Float64: The rapidity.
• _phi::Float64: The azimuthal angle.

PseudoJet(px::Real, py::Real, pz::Real, E::Real; cluster_hist_index::Int = 0)

Construct a PseudoJet from a four momentum (px, py, pz, E)with cluster indexclusterhistindex`.

Details

If the (default) value of cluster_hist_index=0 is used, the PseudoJet cannot be used in a reconstruction sequence.

PseudoJet(jet::Any; cluster_hist_index::Int = 0)

Construct a PseudoJet from a generic object jet with the given cluster index.

Details

This function is used to convert a generic object jet into a PseudoJet, for this to work the object must have the methods px, py, pz, and energy defined, which are used to extract the four-momentum components of the object.

The cluster_hist_index is optional, but needed if the jet is part of a reconstruction sequence. If not provided, it defaults to 0 as an "invalid" value.

PseudoJet(jet::EEJet)

Constructs a PseudoJet object from an EEJet object, with the same four momentum and cluster history index.

PseudoJet(jet::LorentzVectorCyl; cluster_hist_index::Int = 0)

Construct a PseudoJet from a LorentzVectorCyl object with the given cluster index.

PseudoJet(jet::LorentzVector; cluster_hist_index::Int = 0)

Construct a PseudoJet from a LorentzVector object with the cluster index.

PseudoJet(;pt::Real, rap::Real, phi::Real, m::Real = 0, cluster_hist_index::Int = 0)

Construct a PseudoJet from (pt, y, ϕ, m) with the cluster index cluster_hist_index.

Details

If the (default) value of cluster_hist_index=0 is used, the PseudoJet cannot be used in a reconstruction sequence.