Jet Reconstruction Internal Documentation

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

Adds two four-momentum vectors together, returning a new jet.

Details

This addition operation will return a jet with the cluster history index set to

1. *This means that this jet cannot be used, or be part of, any clustering

history.*

copy(j::TiledJet)

Create a copy of a TiledJet object.

Arguments

• j::TiledJet: The TiledJet object to be copied.

Returns

A new TiledJet object with the same attributes as the input object.

isapprox(fj1::FinalJet, fj2::FinalJet; kwargs...)

Compare two FinalJet objects for approximate equality based on their rapidity, azimuthal angle, and transverse momentum. kwargs are passed to the isapprox function, e.g., tol.

isvalid(t::TiledJet)

Check if a TiledJet is valid, by seeing if it is not the noTiledJet object.

Arguments

• t::TiledJet: The TiledJet object to check.

Returns

• Bool: true if the TiledJet object is valid, false otherwise.

isvalid(j::PseudoJet)

Function to check whether a given PseudoJet object is non-zero or not. Primarily to use for checking the validity of outputs of substructure tagging.

Returns

• Bool: true if the PseudoJet object is non-zero (valid), false otherwise.

Base.iterate(t::rightmost_tiles, state=1)

Iterate over the rightmost_tiles object, returning all the rightmost tiles for a given Cartesian tile index.

Base.iterate(t::neighbour_tiles, state=1)

Iterate over the neighbour_tiles object, returning all the neighbour tiles for a given Cartesian tile index.

Base.iterate(tj::TiledJet)

Iterate over a TiledJet object's linked list, walking over all jets until the end (then the next jet is invalid).

Arguments

• tj::TiledJet: The TiledJet object to start to iterate over.

show(io::IO, jet::FourMomentum)

Print core information about the four-momentum vector of jet to the given IO stream.

show(io::IO, sk::SoftKiller)

Pretty-print the SoftKiller grid configuration.

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

Compute the cosine of the angle between the momentum vector of jet and the z-axis.

Returns

• The cosine of the angle between the jet and the z-axis.

Alias for energy function

_addjets_with_scale(scale1::Real, scale2::Real, jet1::T, jet2::T, cluster_hist_index::Int) where {T <: FourMomentum}

Combine two jets as massless objects using the given scale factors for each jet, and return the new jet with the cluster history index set.

_ee_genkt_algorithm!(particles::AbstractVector{EEJet};
                    algorithm::JetAlgorithm.Algorithm, p::Real, R = 4.0,
                    recombine = addjets_escheme)

This function is the internal implementation of the e+e- jet clustering algorithm. It takes a vector of EEJet particles representing the input particles and reconstructs jets based on the specified parameters.

Users of the package should use the ee_genkt_algorithm function as their entry point to this jet reconstruction.

Arguments

• particles::AbstractVector{EEJet}: A vector of EEJet particles used as input for jet reconstruction. This vector must supply the correct cluster_hist_index values and will be mutated as part of the returned ClusterSequence.
• algorithm::JetAlgorithm.Algorithm: The jet reconstruction algorithm to use.
• p::Real: The power to which the transverse momentum (pt) of each particle is raised.
• R = 4.0: The jet radius parameter.
• recombine = addjets_escheme: The recombination function used to merge two jets.

Returns

• clusterseq: The resulting ClusterSequence object representing the reconstructed jets.

_plain_jet_reconstruct!(particles::AbstractVector{PseudoJet};
                       algorithm::JetAlgorithm.Algorithm, p::Real, R = 1.0,
                       recombine = addjets_escheme)

This is the internal implementation of jet reconstruction using the plain algorithm. It takes a vector of PseudoJet particles representing the input particles and reconstructs jets based on the specified parameters.

Users of the package should use the plain_jet_reconstruct function as their entry point to this jet reconstruction.

Arguments

• particles::AbstractVector{PseudoJet}: A vector of PseudoJet particles used as input for jet reconstruction. This vector must supply the correct cluster_hist_index values and will be mutated as part of the returned ClusterSequence.
• algorithm::JetAlgorithm.Algorithm: The jet reconstruction algorithm to use.
• p::Real: The power to which the transverse momentum (pt) of each particle is raised.
• R = 1.0: The jet radius parameter.
• recombine = addjets_escheme: The recombination scheme to use.

Returns

• clusterseq: The resulting ClusterSequence object representing the reconstructed jets.

_tiled_jet_reconstruct!(particles::AbstractVector{PseudoJet};
                       algorithm::JetAlgorithm.Algorithm,
                       p::Real, R = 1.0, recombine = addjets_escheme)

Main jet internal reconstruction algorithm entry point for reconstructing jets once preprocessing of data types are done. The algorithm parameter must be consistent with the power parameter.

Arguments

• particles::AbstractVector{PseudoJet}: A vector of PseudoJet particles used as input for jet reconstruction. This vector must supply the correct cluster_hist_index values and will be mutated as part of the returned ClusterSequence.
• algorithm::JetAlgorithm.Algorithm: The jet reconstruction algorithm to use.
• p::Real: The power parameter for the jet reconstruction algorithm, thus switching between different algorithms.
• R = 1.0: The jet radius parameter for the jet reconstruction algorithm.
• recombine::Function = addjets_escheme: The recombination function used for combining pseudojets.

Returns

• clusterseq: The resulting ClusterSequence object representing the reconstructed jets.

Example

_tiled_jet_reconstruct!(particles::Vector{PseudoJet}; algorithm = JetAlgorithm.Kt, p = 1, R = 0.4)

_tj_diJ(jet)

Compute the dij metric value for a given jet.

Arguments

• jet: The input jet.

Returns

• The dij value for the jet.

Example

_tj_dist(jetA, jetB)

Compute the geometric distance in the (y, ϕ)-plane between two jets in the TiledAlgoLL module.

Arguments

• jetA: The first jet.
• jetB: The second jet.

Returns

The squared distance between jetA and jetB.

Examples

add_step_to_history!(clusterseq::ClusterSequence, parent1, parent2, jetp_index, dij)

Add a new jet's history into the recombination sequence.

Arguments:

• clusterseq::ClusterSequence: The cluster sequence object.
• parent1: The index of the first parent.
• parent2: The index of the second parent.
• jetp_index: The index of the jet.
• dij: The dij value.

This function adds a new HistoryElement to the history vector of the clusterseq object. The HistoryElement contains information about the parents, child, jet index, dij value, and the maximum dij value so far. It also updates the child index of the parent elements.

If the parent1 or parent2 have already been recombined, an InternalError is thrown. The jetp_index is used to update the _cluster_hist_index of the corresponding PseudoJet object.

add_untagged_neighbours_to_tile_union(center_index, tile_union, n_near_tiles, tiling)

Adds to the vector tileunion the tiles that are in the neighbourhood of the specified centerindex, including itself and whose tagged status are false - start adding from position nneartiles-1, and increase nneartiles. When a neighbour is added its tagged status is set to true.

Arguments

• center_index: The index of the center tile.
• tile_union: An array to store the indices of neighbouring tiles.
• n_near_tiles: The number of neighbouring tiles.
• tiling: The tiling object containing the tile tags.

Returns

The updated number of near tiles.

angular_distance(eereco, i, j) -> Float64

Calculate the angular distance between two jets i and j using the formula $1 - cos(θ_{ij})$.

Arguments

• eereco: The array of EERecoJet objects.
• i: The first jet.
• j: The second jet.

Returns

• Float64: The angular distance between i and j, which is $1 - cos heta$.

cluster_hist_index(j::FourMomentum)

Return the cluster history index of the jet j.

copy_to_slot!(eereco, i, j)

Copy the contents of slot i in the eereco array to slot j.

decluster(jet::T, clusterseq::ClusterSequence{T}) where {T <: FourMomentum}

Given a jet and its clustering sequence, this function attempts to decluster it into its two parent subjets. If both parents exist, it returns them ordered by descending pt².

Returns:

• (j1, j2) where j1 is the harder subjet.

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

Function to calculate the distance in the y-ϕ plane between two jets jet1 and jet2 (that is using rapidity and azimuthal angle).

Returns

• The Euclidean distance in the y-ϕ plane for the two jets.

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

Computes the difference in azimuthal angle φ between two jets, wrapped into the range [-π, π].

Returns

• δφ as a Float64 in radians.

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

Function to calculate the distance in the η-ϕ plane between two jets jet1 and jet2 (that is, using the pseudorapidity and azimuthal angle).

Returns

• The Euclidean distance in the η-ϕ plane for the two jets.

detach!(jet::TiledJet)

Detach a TiledJet from its linked list by updating the previous and next pointers.

Arguments

• jet::TiledJet: The TiledJet object to detach.

determine_rapidity_extent(eta::Vector{T}) where T <: AbstractFloat

Calculate the minimum and maximum rapidities based on the input vector eta. The function determines the rapidity extent by binning the multiplicities as a function of rapidity and finding the minimum and maximum rapidities such that the edge bins contain a certain fraction (~1/4) of the busiest bin and a minimum number of particles.

This is the heuristic which is used by FastJet (inline comments are from FastJet).

Arguments

• eta::Vector{T}: A vector of rapidity values.

Returns

• minrap::T: The minimum rapidity value.
• maxrap::T: The maximum rapidity value.

dij(i, kt2_array, nn, nndist)

Compute the dij value for a given index i to its nearest neighbor. The nearest neighbor is determined from nn[i], and the metric distance to the nearest neighbor is given by the distance nndist[i] applying the lower of the kt2_array values for the two particles.

Arguments

• i: The index of the element.
• kt2_array: An array of kt2 values.
• nn: An array of nearest neighbors.
• nndist: An array of nearest neighbor distances.

Returns

• The computed dij value.

dij_dist(eereco, i, j, dij_factor)

Calculate the dij distance between two $e^+e^-$jets.

Arguments

• eereco: The array of EERecoJet objects.
• i: The first jet.
• j: The second jet.
• dij_factor: The scaling factor to multiply the dij distance by.

Returns

• The dij distance between i and j.

dist(i, j, rapidity_array, phi_array)

Compute the distance between points in a 2D space defined by rapidity and phi coordinates.

Arguments

• i::Int: Index of the first point to consider (indexes into rapidity_array and phi_array).
• j::Int: Index of the second point to consider (indexes into rapidity_array and phi_array).
• rapidity_array::Vector{Float64}: Array of rapidity coordinates.
• phi_array::Vector{Float64}: Array of phi coordinates.

Returns

• distance::Float64: The distance between the two points.

do_iB_recombination_step!(clusterseq::ClusterSequence, jet_i, diB)

Bookkeeping for recombining a jet with the beam (i.e., finalising the jet) by adding a step to the history of the cluster sequence.

Arguments

• clusterseq::ClusterSequence: The cluster sequence object.
• jet_i: The index of the jet.
• diB: The diB value.

energy(j::FourMomentum)

Return the energy component of the four-momentum vector of j.

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

Compute the pseudorapidity (η) of a jet.

Returns

• The pseudorapidity (η) of the jet.

fast_findmin(dij, n)

Find the minimum value and its index in the first n elements of the dij array. The use of @turbo macro gives a significant performance boost.

Arguments

• dij: An array of values.
• n: The number of elements to consider in the dij array.

Returns

• dij_min: The minimum value in the first n elements of the dij array.
• best: The index of the minimum value in the dij array.

find_tile_neighbours!(tile_union, jetA, jetB, oldB, tiling)

Find the union of neighbouring tiles of jetA, jetB, and oldB and add them to the tile_union. This established the set of tiles over which searches for updated and new nearest-neighbours must be run

Arguments

• tile_union: The tile union to which the neighbouring tiles will be added.
• jetA: The first jet.
• jetB: The second jet.
• oldB: The old second jet.
• tiling: The tiling information.

Returns

The number of neighbouring tiles added to the tile_union.

geometric_distance(eta1::AbstractFloat, phi1::AbstractFloat, eta2::AbstractFloat, phi2::AbstractFloat)

Compute the geometric distance between two points in the rap-phi plane.

Arguments

• eta1::AbstractFloat: The eta coordinate of the first point.
• phi1::AbstractFloat: The phi coordinate of the first point.
• eta2::AbstractFloat: The eta coordinate of the second point.
• phi2::AbstractFloat: The phi coordinate of the second point.

Returns

• distance::Float64: The geometric distance between the two points.

get_algorithm_power(; algorithm::JetAlgorithm.Algorithm, p::Union{Real, Nothing}) -> Real

Get the algorithm power

This function returns appropriate power value for the specified jet algorithm if the algorithm is a fixed power algorithm (like AntiKt, CA, Kt, or Durham). If the algorithm is generalized (like GenKt or EEKt), it requires a power value to be specified and the function returns the same value.

Arguments

• p::Union{Real, Nothing}: The power value.
• algorithm::JetAlgorithm.Algorithm: The algorithm.

Returns

Resolved algorithm power value.

Throws

• ArgumentError: If no power is specified for a generalized algorithm

get_all_ancestors(idx, cs::ClusterSequence)

Recursively finds all ancestors of a given index in a ClusterSequence object.

Arguments

• idx: The index of the jet for which to find ancestors.
• cs: The ClusterSequence object containing the jet history.

Returns

An array of indices representing the ancestors of the given jet.

get_dij_dist(nn_dist, kt2_1, kt2_2, R2)

Compute the dij metric distance between two jets.

Arguments

• nn_dist: The nearest-neighbor distance between two jets.
• kt2_1: The squared momentum metric value of the first jet.
• kt2_2: The squared momentum metric value of the second jet.
• R2: The jet radius parameter squared.

Returns

The distance between the two jets.

If kt2_2 is equal to 0.0, then the first jet doesn't actually have a valid neighbour, so it's treated as a single jet adjacent to the beam.

get_tile(tiling_setup::TilingDef, eta::AbstractFloat, phi::AbstractFloat)

Given a tiling_setup object, eta and phi values, this function calculates the tile indices for the given eta and phi values.

Arguments

• tiling_setup: A TilingDef object that contains the tiling setup parameters.
• eta: The eta value for which to calculate the tile index.
• phi: The phi value for which to calculate the tile index.

Returns

• ieta: The tile index along the eta direction.
• iphi: The tile index along the phi direction.

get_tile_linear_index(tiling_setup::TilingDef, i_η::Int, i_ϕ::Int)

Compute the linear index of a tile in a tiled setup. This is much faster in this function than using the LinearIndices construct (like x100, which is bonkers, but there you go...)

Arguments

• tiling_setup::TilingDef: The tiling setup defining the number of tiles in each dimension.
• i_η::Int: The index of the tile in the η dimension.
• i_ϕ::Int: The index of the tile in the ϕ dimension.

Returns

• The linear index of the tile.

initial_history(particles)

Create an initial history for the given particles.

Arguments

• particles: The initial vector of stable particles.

Returns

• history: An array of HistoryElement objects.
• Qtot: The total energy in the event.

insert!(nextjet::TiledJet, jettomove::TiledJet)

Inserts a TiledJet object into the linked list of TiledJet objects, before the nextjet object. The jet to move can be an isolated jet, a jet from another list or a jet from the same list

Arguments

• nextjet::TiledJet: The TiledJet object after which jettomove should be inserted.
• jettomove::TiledJet: The TiledJet object to be inserted.

Example

is_ee(algorithm::JetAlgorithm.Algorithm)

Check if the algorithm is a e+e- reconstruction algorithm.

Returns

true if the algorithm is a e+e- reconstruction algorithm, false otherwise.

is_pp(algorithm::JetAlgorithm.Algorithm)

Check if the algorithm is a pp reconstruction algorithm.

Returns

true if the algorithm is a pp reconstruction algorithm, false otherwise.

jet_ranks(clusterseq::ClusterSequence; compare_fn = JetReconstruction.pt)

Compute the ranks of jets in a given ClusterSequence object based on a specified comparison function.

Arguments

• clusterseq::ClusterSequence: The ClusterSequence object containing the jets to rank.
• compare_fn = JetReconstruction.pt: The comparison function used to determine the order of the jets. Defaults to JetReconstruction.pt, which compares jets based on their transverse momentum.

Returns

A dictionary mapping each jet index to its rank.

Note

This is a utility function that can be used to rank initial clusters based on a specified jet property. It can be used to assign a consistent "rank" to each reconstructed jet in the cluster sequence, which is useful for stable plotting of jet outputs.

Alias for pt2 function

Alias for mass function

Alias for mass2 function

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

Return the magnitude of the momentum of a jet, |p|.

Returns

The magnitude of the jet.

mass(j::FourMomentum)

Return the invariant mass of a four momentum j. By convention if $m^2 < 0$, then $-sqrt{(-m^2)}$ is returned.

mass2(j::FourMomentum)

Return the invariant mass squared of the four-momentum vector j.

merge_steps(clusterseq::ClusterSequence)

Compute the number of jet-jet merge steps in a cluster sequence. This is useful to give the number of meaningful recombination steps in a jet reconstruction sequence (beam merge steps are not counted).

Arguments

• clusterseq::ClusterSequence: The cluster sequence object.

Returns

• merge_steps::Int: The number of merge steps.

nx(eej::EEJet)

Return the x-component of the unit vector aligned with the momentum of eej

ny(eej::EEJet)

Return the y-component of the unit vector aligned with the momentum of eej

nz(eej::EEJet)

Return the z-component of the unit vector aligned with the momentum of eej

open_with_stream(fname::AbstractString)

Open a file with a stream decompressor if it is compressed with gzip or zstd, otherwise as a normal file.

p(j::FourMomentum)

Return the momentum of the four-momentum vector of j.

p2(eej::EEJet)

Return the squared momentum of the EEJet object eej.

p2(j::FourMomentum)

Return the squared momentum of the four-momentum vector of j.

phi(j::FourMomentum)

Return the azimuthal angle, ϕ, of the four momentum j in the range [0, 2π).

phi(p::PseudoJet)

Return the azimuthal angle, ϕ, of a PseudoJet object p in the range [0, 2π).

pt(j::FourMomentum)

Return the momentum of the four-momentum vector of j.

pt(p::PseudoJet)

Compute the scalar transverse momentum (pt) of a PseudoJet.

Returns

• The transverse momentum (pt) of the PseudoJet.

pt2(j::FourMomentum)

Return the squared transverse momentum of the four-momentum vector of j.

pt2(p::PseudoJet)

Get the squared transverse momentum of a PseudoJet.

Returns

• The squared transverse momentum of the PseudoJet.

px(j::FourMomentum)

Return the x-component of the four-momentum vector of j.

py(j::FourMomentum)

Return the y-component of the four-momentum vector of j.

pz(j::FourMomentum)

Return the z-component of the four-momentum vector of j.

rapidity(j::FourMomentum)

Return the rapidity of the four momentum j.

rapidity(p::PseudoJet)

Compute the rapidity of a PseudoJet object.

Returns

The rapidity of the PseudoJet object.

recluster(jet::PseudoJet, clusterseq::ClusterSequence{PseudoJet}; R = 1.0,
               algorithm::JetAlgorithm.Algorithm = JetAlgorithm.CA) -> PseudoJet

Reclusters the constituents of a given jet jet with a different clustering algorithm algorithm and different jet radius R.

Arguments

• jet::PseudoJet: The jet whose constituents are to be reclustered.
• clusterseq::ClusterSequence{PseudoJet}: The cluster sequence from which the original jet is obtained.
• R = 1.0: The new jet radius.
• algorithm::JetAlgorithm.Algorithm = JetAlgorithm.CA: The new clustering method.

Returns

• ClusterSequence: The new cluster sequence.

reco_state(cs::ClusterSequence, pt_ranks; iteration=0)

This function returns the reconstruction state of a ClusterSequence object based on a given iteration number in the reconstruction.

Arguments

• cs::ClusterSequence: The ClusterSequence object to update.
• ranks: The ranks of the original clusters, that are inherited by pseudojets

during the reconstruction process.

• iteration=0: The iteration number to consider for updating the reconstruction state (0 represents the initial state).
• ignore_beam_merge=true: Ignore beam merging steps in the reconstruction (which produce no change in status).

Returns

A dictionary representing a snapshot of the reconstruction state.

Details

The function starts by initializing the reconstruction state with the initial particles. Then, it walks over the iteration sequence and updates the reconstruction state based on the history of recombination and finalization/beam merger steps.

rightneighbours(center::Int, tiling::Tiling)

Compute the indices of the right neighbors of a given center index in a tiling. This is used in the initial sweep to calculate the nearest neighbors, where the search between jets for the nearest neighbour is bi-directional, thus when a tile is considered only the right neighbours are needed to compare jet distances as the left-hand tiles have been done from that tile already.

Arguments

• center::Int: The center index.
• tiling::Tiling: The tiling object.

Returns

• Surrounding: An object containing the indices of the right neighbors.

set_nearest_neighbours!(clusterseq::ClusterSequence, tiling::Tiling, tiledjets::Vector{TiledJet})

This function sets the nearest neighbor information for all jets in the tiledjets vector.

Arguments

• clusterseq::ClusterSequence: The cluster sequence object.
• tiling::Tiling: The tiling object.
• tiledjets::Vector{TiledJet}: The vector of tiled jets.

Returns

• NNs::Vector{TiledJet}: The vector of nearest neighbor jets.
• diJ::Vector{Float64}: The vector of diJ values.

The function iterates over each tile in the tiling and sets the nearest neighbor information for each jet in the tile. It then looks for neighbor jets in the neighboring tiles and updates the nearest neighbor information accordingly. Finally, it creates the diJ table and returns the vectors of nearest neighbor jets and diJ values.

Note: The diJ values are calculated as the kt distance multiplied by R^2.

setup_tiling(eta::Vector{T}, Rparam::AbstractFloat) where T <: AbstractFloat

This function sets up the tiling parameters for a reconstruction given a vector of rapidities eta and a radius parameter Rparam.

Arguments

• eta::Vector{T}: A vector of rapidities.
• Rparam::AbstractFloat: The jet radius parameter.

Returns

• tiling_setup: A TilingDef object containing the tiling setup parameters.

Description

The function first decides the tile sizes based on the Rparam value. It then determines the number of tiles in the phi direction (n_tiles_phi) based on the tile size. Next, it determines the rapidity extent of the input eta vector and adjusts the values accordingly. Finally, it creates a TilingDef object with the calculated tiling parameters and returns it.

surrounding(center::Int, tiling::Tiling)

Compute the surrounding indices of a given center index in a tiling.

Arguments

• center::Int: The center index.
• tiling::Tiling: The tiling object.

Returns

• Surrounding: An object containing the surrounding indices.

tile_index(tiling_setup, eta::Float64, phi::Float64)

Compute the tile index for a given (eta, phi) coordinate.

Arguments

• tiling_setup: The tiling setup object containing the tile size and number of tiles.
• eta::Float64: The eta coordinate.
• phi::Float64: The phi coordinate.

Returns

The tile index corresponding to the (eta, phi) coordinate.

tile_index(sk::SoftKiller, p::PseudoJet)

Return the tile index for a given PseudoJet p in the SoftKiller grid sk. Returns -1 if the jet is outside the grid bounds.

tiledjet_remove_from_tiles!(tiling, jet)

Remove a jet from the given tiling structure.

Arguments

• tiling: The tiling structure from which the jet will be removed.
• jet: The jet to be removed from the tiling structure.

Description

This function removes a jet from the tiling structure. It adjusts the linked list to be consistent with the removal of the jet.

tiledjet_set_jetinfo!(jet::TiledJet, clusterseq::ClusterSequence, tiling::Tiling, jets_index, R2, p)

Initialise a tiled jet from a PseudoJet (using an index into our ClusterSequence)

Arguments:

• jet::TiledJet: The TiledJet object to set the information for.
• clusterseq::ClusterSequence: The ClusterSequence object containing the jets.
• tiling::Tiling: The Tiling object containing the tile information.
• jets_index: The index of the jet in the ClusterSequence.
• R2: The jet radius parameter squared.
• p: The power to raise the pt2 value to.

This function sets the eta, phi, kt2, jetsindex, NNdist, NN, tile_index, previous, and next fields of the TiledJet object.

Returns:

• nothing

upd_nn_crosscheck!(i, from, to, rapidity_array, phi_array, R2, nndist, nn)

Update the nearest neighbor information for a given particle index i against all particles in the range indexes from to to. The function updates the nndist and nn arrays with the nearest neighbor distance and index respectively, both for particle i and the checked particles [from:to] (hence crosscheck).

Arguments

• i::Int: The index of the particle to update and check against.
• from::Int: The starting index of the range of particles to check against.
• to::Int: The ending index of the range of particles to check against.
• rapidity_array: An array containing the rapidity values of all particles.
• phi_array: An array containing the phi values of the all particles.
• R2: The squared jet distance threshold for considering a particle as a neighbour.
• nndist: The array that stores the nearest neighbor distances.
• nn: The array that stores the nearest neighbor indices.

upd_nn_nocross!(i, from, to, rapidity_array, phi_array, R2, nndist, nn)

Update the nearest neighbor information for a given particle index i against all particles in the range indexes from to to. The function updates the nndist and nn arrays with the nearest neighbor distance and index respectively, only for particle i (hence nocross).

Arguments

• i::Int: The index of the particle to update and check against.
• from::Int: The starting index of the range of particles to check against.
• to::Int: The ending index of the range of particles to check against.
• rapidity_array: An array containing the rapidity values of all particles.
• phi_array: An array containing the phi values of the all particles.
• R2: The squared jet distance threshold for considering a particle as a neighbour.
• nndist: The array that stores the nearest neighbor distances.
• nn: The array that stores the nearest neighbor indices.

upd_nn_step!(i, j, k, N, Nn, kt2_array, rapidity_array, phi_array, R2, nndist, nn, nndij)

Update the nearest neighbor information after a jet merge step.

Arguments:

• i: Index of the first particle in the last merge step.
• j: Index of the second particle in the last merge step.
• k: Index of the current particle for which the nearest neighbour will be updated.
• N: Total number of particles (currently valid array indexes are [1:N]).
• Nn: Number of nearest neighbors to consider.
• kt2_array: Array of transverse momentum squared values.
• rapidity_array: Array of rapidity values.
• phi_array: Array of azimuthal angle values.
• R2: Distance threshold squared for nearest neighbors.
• nndist: Array of nearest neighbor geometric distances.
• nn: Array of nearest neighbor indices.
• nndij: Array of metric distances between particles.

This function updates the nearest neighbor information for the current particle k by considering the distances to particles i and j. It checks if the distance between k and i is smaller than the current nearest neighbor distance for k, and updates the nearest neighbor information accordingly. It also updates the nearest neighbor information for i if the distance between k and i is smaller than the current nearest neighbor distance for i. Finally, it checks if the nearest neighbor of k is the total number of particles Nn and updates it to j if necessary.

const η = eta

Alias for the pseudorapidity function, eta.

abstract type FourMomentum end

Interface for composite types that includes fields px, py, py, and E that represents the components of a four-momentum vector. All concrete jets that are used in the package are subtypes of this type.

struct HistoryElement

A struct holding a record of jet mergers and finalisations

Fields:

• parent1: Index in history where first parent of this jet was created (NonexistentParent if this jet is an original particle)
• parent2: Index in history where second parent of this jet was created (NonexistentParent if this jet is an original particle); BeamJet if this history entry just labels the fact that the jet has recombined with the beam)
• child: Index in history where the current jet is recombined with another jet to form its child. It is Invalid if this jet does not further recombine.
• jetp_index: Index in the jets vector where we will find the PseudoJet object corresponding to this jet (i.e. the jet created at this entry of the history). NB: if this element of the history corresponds to a beam recombination, then jetp_index=Invalid.
• dij: The distance corresponding to the recombination at this stage of the clustering.
• max_dij_so_far: The largest recombination distance seen so far in the clustering history.

HistoryElement(jetp_index)

Constructs a HistoryElement object with the given jetp_index, used for initialising the history with original particles.

Arguments

• jetp_index: The index of the jetp.

Returns

A HistoryElement object.

struct JetWithAncestors{T <: FourMomentum}

A struct representing a jet with its origin ancestors.

Fields

• self::T: The jet object itself.
• jetp_index::Int: The index of the jet in the corresponding cluster sequence.
• ancestors::Set{Int}: A set of indices representing the jetp_indexes of ancestors of the jet (in the cluster sequence).
• jet_rank::Int: The rank of the jet based on a comparison of all of the jet's ancestors

Note

This structure needs its associated cluster sequence origin to be useful.

struct Surrounding{N}

Structure used for iterating over neighbour tiles.

Fields

• indices::NTuple{N, Int}: A tuple of N integers representing the indices.

mutable struct TiledJet

TiledJet represents a jet in a tiled algorithm for jet reconstruction, with additional information to track the jet's position in the tiled structures.

Fields

• id::Int: The ID of the jet.
• eta::Float64: The rapidity of the jet.
• phi::Float64: The azimuthal angle of the jet.
• kt2::Float64: The transverse momentum squared of the jet.
• NN_dist::Float64: The distance to the nearest neighbor.
• jets_index::Int: The index of the jet in the jet array.
• tile_index::Int: The index of the tile in the tile array.
• dij_posn::Int: The position of this jet in the dij compact array.
• NN::TiledJet: The nearest neighbor.
• previous::TiledJet: The previous jet.
• next::TiledJet: The next jet.

TiledJet(id)

Constructs a TiledJet object with the given id and initializes its properties to zero.

Arguments

• id: The ID of the TiledJet object.

Returns

A TiledJet object with the specified id and values set to zero or noTiledJet.

struct Tiling

The Tiling struct represents a tiling configuration for jet reconstruction.

Fields

• setup::TilingDef: The tiling definition used for the configuration.
• tiles::Matrix{TiledJet}: A matrix of tiled jets, containing the first jet in each tile (then the linked list of the first jet is followed to get access to all jets in this tile).
• positions::Matrix{Int}: Used to track tiles that are on the edge of ϕ array, where neighbours need to be wrapped around.
• tags::Matrix{Bool}: The matrix of tags indicating whether a tile is valid or not (set to false initially, then true when the tile has been setup properly).

Tiling(setup::TilingDef)

Constructs a initial Tiling object based on the provided setup parameters.

Arguments

• setup::TilingDef: The setup parameters for the tiling.

Returns

A Tiling object.

struct TilingDef

A struct representing the definition of a specific tiling scheme.

Fields

• _tiles_eta_min::Float64: The minimum rapidity of the tiles.
• _tiles_eta_max::Float64: The maximum rapidity of the tiles.
• _tile_size_eta::Float64: The size of a tile in rapidity (usually R^2).
• _tile_size_phi::Float64: The size of a tile in phi (usually a bit more than R^2).
• _n_tiles_eta::Int: The number of tiles across rapidity.
• _n_tiles_phi::Int: The number of tiles across phi.
• _n_tiles::Int: The total number of tiles.
• _tiles_ieta_min::Int: The minimum rapidity tile index.
• _tiles_ieta_max::Int: The maximum rapidity tile index.

Constructor

TilingDef(_tiles_eta_min, _tiles_eta_max, _tile_size_eta, _tile_size_phi,
	_n_tiles_eta, _n_tiles_phi, _tiles_ieta_min, _tiles_ieta_max)

Constructs a TilingDef object with the given parameters.

struct neighbour_tiles

A struct representing the neighbouring tiles.

A struct for iterating over all neighbour tiles for a given Cartesian tile index. These are the tiles above and to the right of the given tile (X=included, O=not included):

XXX
X.X
XXX

Note, rapidity coordinate must be in range, ϕ coordinate wraps

Fields

• n_η::Int: Number of η tiles
• n_ϕ::Int: Number of ϕ tiles
• start_η::Int: Centre η tile coordinate
• start_ϕ::Int: Centre ϕ tile coordinate

struct rightmost_tiles

A struct for iterating over rightmost tiles for a given Cartesian tile index. These are the tiles above and to the right of the given tile (X=included, O=not included):

XXX
O.X
OOO

Note, rapidity coordinate must be in range, ϕ coordinate wraps

Fields

• n_η::Int: Number of η tiles
• n_ϕ::Int: Number of ϕ tiles
• start_η::Int: Centre η tile coordinate
• start_ϕ::Int: Centre ϕ tile coordinate