This is a basic jet reconstruction example that shows how to call the package to perform a jet reconstruction, with different algorithms and (optionally) strategy, producing exclusive and inclusive jet selections.
This is a more sophisticated example that allows performance measurements to be made of the reconstruction, as well as profiling (flamegraphs and memory profiling). Use the --help option to see usage. e.g., to extract timing performance for the AntiKt algorithm using the tiled strategy:
sh
julia --project instrumented-jetreco.jl -S N2Tiled -A AntiKt --nsamples 100 ../test/data/events.hepmc3
This script will produce a PNG/PDF showing the results of a jet reconstruction. This is a 3D plot where all the initial energy deposits are visualised, with colours that indicate in which final cluster the deposit ended up in.
Similar to visualise-jets.jl this notebook will produce a visualisation of jet reconstruction in the browser. This is a 3D plot where all the initial energy deposits are visualised, with colours that indicate in which final cluster the deposit ended up in.
Generally one can use the jet_reconstruct interface, shown above, as the Best strategy safely as the overhead is extremely low. That interface supports a strategy option to switch to a different option.
Another option, if one wishes to use a specific strategy, is to call that strategy's interface directly, e.g.,
julia
# For N2Plain strategy called directly
+plain_jet_reconstruct(particles::Vector{T}; p = -1, R = 1.0, recombine = +)
Note that there is no strategy option in these interfaces.
To visualise the clustered jets as a 3d bar plot (see illustration above) we now use Makie.jl. See the jetsplot function in ext/JetVisualisation.jl and its documentation for more. There are two worked examples in the examples directory.
The plotting code is a package extension and will load if the one of the Makie modules is loaded in the environment.
The animatereco function will animate the reconstruction sequence, given a ClusterSequence object. See the function documentation for the many options that can be customised.
The package also provides methods such as loadjets, loadjets!, and savejets that one can use to save and load objects on/from disk easily in a very flexible format. See documentation for more.
Although it has been developed further since the CHEP2023 conference, the CHEP conference proceedings, 10.1051/epjconf/202429505017, should be cited if you use this package:
bibtex
@article{refId0,
+ author = {{Stewart, Graeme Andrew} and {Gras, Philippe} and {Hegner, Benedikt} and {Krasnopolski, Atell}},
+ doi = {10.1051/epjconf/202429505017},
+ journal = {EPJ Web of Conf.},
+ pages = {05017},
+ title = {Polyglot Jet Finding},
+ url = {https://doi.org/10.1051/epjconf/202429505017},
+ volume = 295,
+ year = 2024,
+ eprint={2309.17309},
+ archivePrefix={arXiv},
+ primaryClass={hep-ex}
+}
@misc{stewart2023polyglot,
+ title={Polyglot Jet Finding},
+ author={Graeme Andrew Stewart and Philippe Gras and Benedikt Hegner and Atell Krasnopolski},
+ year={2023},
+ eprint={2309.17309},
+ archivePrefix={arXiv},
+ primaryClass={hep-ex}
+}
Ensure that the rapidity and azimuthal angle of the PseudoJet p are valid. If the azimuthal angle is invalid (used as a proxy for both variables), they are set to a valid value using _set_rap_phi!.
Arguments
p::PseudoJet: The PseudoJet object to ensure valid rapidity and azimuthal angle for.
_plain_jet_reconstruct(; particles::Vector{PseudoJet}, p = -1, R = 1.0, recombine = +)
This is the internal implementation of jet reconstruction using the plain algorithm. It takes a vector of particles representing the input particles and reconstructs jets based on the specified parameters. Here the particles must be of type PseudoJet.
Users of the package should use the plain_jet_reconstruct function as their entry point to this jet reconstruction.
The power value maps to specific pp jet reconstruction algorithms: -1 = AntiKt, 0 = Cambridge/Aachen, 1 = Inclusive Kt.
Arguments
particles: A vector of PseudoJet objects representing the input particles.
p=-1: The power to which the transverse momentum (pt) of each particle is raised.
R=1.0: The jet radius parameter.
recombine: The recombination function used to merge two jets. Default is + (additive recombination).
Returns
clusterseq: The resulting ClusterSequence object representing the reconstructed jets.
Set the rapidity and azimuthal angle of the PseudoJet p.
Arguments
p::PseudoJet: The PseudoJet object for which to set the rapidity and azimuthal angle.
Description
This function calculates and sets the rapidity and azimuthal angle of the PseudoJet p based on its momentum components. The rapidity is calculated in a way that is insensitive to roundoff errors when the momentum components are large. If the PseudoJet represents a point with infinite rapidity, a large number is assigned to the rapidity in order to lift the degeneracy between different zero-pt momenta.
Note - the ϕ angle is calculated in the range [0, 2π).
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.
Adds to the vector tile_union the tiles that are in the neighbourhood of the specified center_index, including itself and whose tagged status are false - start adding from position n_near_tiles-1, and increase n_near_tiles. 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.
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).
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.ßß
Perform the bookkeeping associated with the step of recombining jet_i and jet_j (assuming a distance dij).
Arguments
clusterseq::ClusterSequence: The cluster sequence object.
jet_i: The index of the first jet to be recombined.
jet_j: The index of the second jet to be recombined.
dij: The distance between the two jets.
recombine=+: The recombination function to be used. Default is addition.
Returns
newjet_k: The index of the newly created jet.
Description
This function performs the i-j recombination step in the cluster sequence. It creates a new jet by recombining the first two jets using the specified recombination function. The new jet is then added to the cluster sequence. The function also updates the indices and history information of the new jet and sorts out the history.
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.
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.
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.
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.
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.
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 peudojets
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.
Compute the indices of the right neighbors of a given center index in a tiling. This is used in the inital 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.
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.
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.
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 vaild 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.
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.
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.
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).
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
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
`,152),n=[o];function r(l,d,c,p,h,u){return i(),t("div",null,n)}const k=e(a,[["render",r]]);export{b as __pageData,k as default};
diff --git a/previews/PR66/assets/lib_internal.md.dfz8Wswb.lean.js b/previews/PR66/assets/lib_internal.md.dfz8Wswb.lean.js
new file mode 100644
index 0000000..6bdcf16
--- /dev/null
+++ b/previews/PR66/assets/lib_internal.md.dfz8Wswb.lean.js
@@ -0,0 +1 @@
+import{_ as e,c as t,o as i,a7 as s}from"./chunks/framework.CT7mYJ7N.js";const b=JSON.parse('{"title":"Jet Reconstruction Internal Documentation","description":"","frontmatter":{},"headers":[],"relativePath":"lib/internal.md","filePath":"lib/internal.md","lastUpdated":null}'),a={name:"lib/internal.md"},o=s("",152),n=[o];function r(l,d,c,p,h,u){return i(),t("div",null,n)}const k=e(a,[["render",r]]);export{b as __pageData,k as default};
diff --git a/previews/PR66/assets/lib_public.md.SJ6FK4z6.js b/previews/PR66/assets/lib_public.md.SJ6FK4z6.js
new file mode 100644
index 0000000..b19597e
--- /dev/null
+++ b/previews/PR66/assets/lib_public.md.SJ6FK4z6.js
@@ -0,0 +1,7 @@
+import{_ as e,c as t,o as s,a7 as i}from"./chunks/framework.CT7mYJ7N.js";const g=JSON.parse('{"title":"Jet Reconstruction Public Documentation","description":"","frontmatter":{},"headers":[],"relativePath":"lib/public.md","filePath":"lib/public.md","lastUpdated":null}'),a={name:"lib/public.md"},n=i(`
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.
Note: Either dcut or njets must be provided (but not both).
Returns
An array of LorentzVectorCyl objects representing the exclusive jets.
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.
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.
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.
Returns
An array of LorentzVectorCyl 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.
jet_reconstruct(particles; p = -1, R = 1.0, recombine = +, strategy = RecoStrategy.Best)
Reconstructs jets from a collection of particles using a specified algorithm and strategy
Arguments
particles: A collection of particles used for jet reconstruction.
p=-1: The power value used for the distance measure for generalised k_T, which maps to a particular reconstruction algorithm (-1 = AntiKt, 0 = Cambridge/Aachen, 1 = Kt).
R=1.0: The jet radius parameter.
recombine=+: The recombination scheme used for combining particles.
strategy=RecoStrategy.Best: The jet reconstruction strategy to use. RecoStrategy.Best makes a dynamic decision based on the number of starting particles.
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, and PseudoJet, for which these methods are already predefined in the JetReconstruction namespace.
recombine argument
The recombine argument is the function used to merge pairs of particles. The default is simply +(jet1,jet2), i.e. 4-momenta addition or the E-scheme.
Loads the jets from a file. Ignores lines that start with '#'. Each line gets processed in the following way: the line is split using split(line, splitby) or simply split(line) by default. Every value in this line is then converted to the dtype (which is Float64 by default). These values are then used as arguments for the constructor function which should produce individual jets. By default, the constructor constructs Lorentz vectors.
Everything that was already in jets is not affected as we only use push! on it.
Example
julia
# Load jets from two files into one array
+jets = []
+loadjets!("myjets1.dat", jets)
+loadjets!("myjets2.dat", jets)
plain_jet_reconstruct(particles::Vector{T}; p = -1, R = 1.0, recombine = +) where T
Perform jet reconstruction using the plain algorithm.
Arguments
particles::Vector{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.
p::Int=-1: The integer value used for jet reconstruction.
R::Float64=1.0: The radius parameter used for jet reconstruction.
recombine::Function=+: The recombination function used for jet reconstruction.
Note for the particles argument, the 4-vector methods need to exist in the JetReconstruction package namespace.
Returns
Vector{PseudoJet}: A vector of reconstructed jets.
Example
julia
jets = plain_jet_reconstruct(particles; p = -1, R = 1.0)
filename: The name of the file to save the jet data to.
jets: An array of jet objects to save.
format="px py pz E": (optional) A string specifying the format of the jet data to save. The default format is "px py pz E".
Details
This function saves jet data to a file in a specific format. Each line in the file represents a jet and contains the information about the jet in the specified format. The format string can include the following placeholders:
"E" or "energy": Jet energy
"px": Momentum along the x-axis
"py": Momentum along the y-axis
"pz": Momentum along the z-axis
"pt2": Square of the transverse momentum
"phi": Azimuth angle
"rapidity": Rapidity
Lines starting with '#' are treated as comments and are ignored.
It is strongly NOT recommended to put something other than values and (possibly custom) separators in the format string.
tiled_jet_reconstruct(particles::Vector{T}; p = -1, R = 1.0, recombine = +) where {T}
Main jet reconstruction algorithm entry point for reconstructing jets using the tiled stragegy for generic jet type T.
Note - if a non-standard recombination is used, it must be defined for JetReconstruction.PseudoJet, as this struct is used internally.
Arguments
particles::Vector{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)
p::Int = -1: The power parameter for the jet reconstruction algorithm, thus swiching between different algorithms.
R::Float64 = 1.0: The jet radius parameter for the jet reconstruction algorithm.
recombine::Function = +: The recombination function used for combining pseudojets.
Returns
Vector{PseudoJet}: A vector of reconstructed jets.
Example
julia
tiled_jet_reconstruct(particles::Vector{LorentzVectorHEP}; p = -1, R = 0.4, recombine = +)
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.
jets::Vector{PseudoJet}: The physical PseudoJets in the cluster sequence. Each PseudoJet corresponds to a position in the history.
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.
The PseudoJet struct represents a pseudojet, a four-momentum object used in jet reconstruction algorithms. Additonal 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.
`,51),o=[n];function l(r,p,c,d,h,u){return s(),t("div",null,o)}const y=e(a,[["render",l]]);export{g as __pageData,y as default};
diff --git a/previews/PR66/assets/lib_public.md.SJ6FK4z6.lean.js b/previews/PR66/assets/lib_public.md.SJ6FK4z6.lean.js
new file mode 100644
index 0000000..3df6264
--- /dev/null
+++ b/previews/PR66/assets/lib_public.md.SJ6FK4z6.lean.js
@@ -0,0 +1 @@
+import{_ as e,c as t,o as s,a7 as i}from"./chunks/framework.CT7mYJ7N.js";const g=JSON.parse('{"title":"Jet Reconstruction Public Documentation","description":"","frontmatter":{},"headers":[],"relativePath":"lib/public.md","filePath":"lib/public.md","lastUpdated":null}'),a={name:"lib/public.md"},n=i("",51),o=[n];function l(r,p,c,d,h,u){return s(),t("div",null,o)}const y=e(a,[["render",l]]);export{g as __pageData,y as default};
diff --git a/previews/PR66/assets/lib_visualisation.md.BnzlcLmb.js b/previews/PR66/assets/lib_visualisation.md.BnzlcLmb.js
new file mode 100644
index 0000000..0a1722e
--- /dev/null
+++ b/previews/PR66/assets/lib_visualisation.md.BnzlcLmb.js
@@ -0,0 +1,29 @@
+import{_ as e,c as s,o as a,a7 as i}from"./chunks/framework.CT7mYJ7N.js";const g=JSON.parse('{"title":"Jet Visualisation Documentation","description":"","frontmatter":{},"headers":[],"relativePath":"lib/visualisation.md","filePath":"lib/visualisation.md","lastUpdated":null}'),t={name:"lib/visualisation.md"},n=i(`
Animate the jet reconstruction process and save it as a video file.
Arguments
cs::ClusterSequence: The cluster sequence object containing the jets.
filename: The name of the output video file.
Optional Arguments
barsize_phi=0.1: The size of the bars in the phi direction.
barsize_y=0.1: The size of the bars in the y direction.
colormap=:glasbey_category10_n256: The colormap to use for coloring the jets.
perspective=0.5: The perspective of the plot.
azimuth=2.7: The azimuth angle of the plot.
elevation=0.5: The elevation angle of the plot.
framerate=5: The framerate of the output video.
end_frames=0: The number of static frames to show at the end of the animation. This can be useful to show the final state of the jets for a longer time.
title=nothing: The title to add to the plot.
ancestors=false: Whether to include ancestors of the jets in the animation. When true the ancestors of the jets will be plotted as well, as height zero bars, with the same colour as the jet they are ancestors of.
Module: The plotting module to use. Default is Makie.
For perspective, azimuth, and elevation, a single value can be passed for a fixed viewpoint, or a tuple of two values for a changing viewpoint. The viewpoint will then change linearly between the two values over the course of the animation.
Returns
fig: The figure object representing the final frame.
Plots a 3d bar chart that represents jets. Takes an objects array of objects to display and idx_arrays, an array of arrays with indeces, where idx_arrays[i] gives indeces of objects that form the jet number i. This function's signature might not be the most practical for the current version of the JetReconstruction.jl package, as it has been written during the early stage of development. There is now an overload of it that takes a ClusterSequence object as its argument.
Optional arguments: barsize_phi::Real — width of a bar along the ϕ axis; barsize_eta::Real — width of a bar along the η axis; colormap::Symbol — Makie colour map; Module — the module where you have your Makie (see below);
# example
+using CairoMakie # use any other Makie that you have here
+
+jetsplot([object1, object2, object3], [[1], [2, 3]])
The example above plots object1 as a separate jet in one colour and object2 and object3 together in another colour.
This function needs Makie.jl to work. You should install and import/use a specific backend yourself. jetsplot works with CairoMakie, WGLMakie, GLMakie, etc. Additionally, you can specify the module where you have your Makie explicitly:
Plots a 3d bar chart that represents jets. Takes objects, an array of objects to display (should be the same array you have passed to jet_reconstruct to get the cs::ClusterSequence), and the cs::ClusterSequence itself as arguments.
Optional arguments: barsize_phi::Real — width of a bar along the ϕ axis; barsize_eta::Real — width of a bar along the η axis; colormap::Symbol — Makie colour map; Module — the module where you have your Makie (see below);
# example
+using CairoMakie # use any other Makie that you have here
+jetsplot([object1, object2, object3], cluster_sequence_I_got_from_jet_reconstruct; Module=CairoMakie)
This function needs Makie.jl to work. You should install and import/use a specific backend yourself. jetsplot works with CairoMakie, WGLMakie, GLMakie, etc. Additionally, you can specify the module where you have your Makie explicitly:
This is a basic jet reconstruction example that shows how to call the package to perform a jet reconstruction, with different algorithms and (optionally) strategy, producing exclusive and inclusive jet selections.
This is a more sophisticated example that allows performance measurements to be made of the reconstruction, as well as profiling (flamegraphs and memory profiling). Use the --help option to see usage. e.g., to extract timing performance for the AntiKt algorithm using the tiled strategy:
sh
julia --project instrumented-jetreco.jl -S N2Tiled -A AntiKt --nsamples 100 ../test/data/events.hepmc3
This script will produce a PNG/PDF showing the results of a jet reconstruction. This is a 3D plot where all the initial energy deposits are visualised, with colours that indicate in which final cluster the deposit ended up in.
Similar to visualise-jets.jl this notebook will produce a visualisation of jet reconstruction in the browser. This is a 3D plot where all the initial energy deposits are visualised, with colours that indicate in which final cluster the deposit ended up in.
This package implements sequential Jet Reconstruction (clustering) algorithms, which are used in high-energy physics as part of event reconstruction for and colliders.
Three strategies are available for the different algorithms:
Strategy Name
Notes
Interface
RecoStrategy.Best
Dynamically switch strategy based on input particle density
jet_reconstruct
RecoStrategy.N2Plain
Global matching of particles at each interation (works well for low )
plain_jet_reconstruct
RecoStrategy.N2Tiled
Use tiles of radius to limit search space (works well for higher )
tiled_jet_reconstruct
Generally one can use the jet_reconstruct interface, shown above, as the Best strategy safely as the overhead is extremely low. That interface supports a strategy option to switch to a different option.
Another option, if one wishes to use a specific strategy, is to call that strategy's interface directly, e.g.,
julia
# For N2Plain strategy called directly
+plain_jet_reconstruct(particles::Vector{T}; p = -1, R = 1.0, recombine = +)
Note that there is no strategy option in these interfaces.
Sorting vectors is trivial in Julia, no special sorting methods are provided. As an example, to sort exclusive jets of (usually GeV, depending on your EDM) from highest energy to lowest:
To visualise the clustered jets as a 3d bar plot (see illustration above) we now use Makie.jl. See the jetsplot function in ext/JetVisualisation.jl and its documentation for more. There are two worked examples in the examples directory.
The plotting code is a package extension and will load if the one of the Makie modules is loaded in the environment.
The animatereco function will animate the reconstruction sequence, given a ClusterSequence object. See the function documentation for the many options that can be customised.
The package also provides methods such as loadjets, loadjets!, and savejets that one can use to save and load objects on/from disk easily in a very flexible format. See documentation for more.
Although it has been developed further since the CHEP2023 conference, the CHEP conference proceedings, 10.1051/epjconf/202429505017, should be cited if you use this package:
bibtex
@article{refId0,
+ author = {{Stewart, Graeme Andrew} and {Gras, Philippe} and {Hegner, Benedikt} and {Krasnopolski, Atell}},
+ doi = {10.1051/epjconf/202429505017},
+ journal = {EPJ Web of Conf.},
+ pages = {05017},
+ title = {Polyglot Jet Finding},
+ url = {https://doi.org/10.1051/epjconf/202429505017},
+ volume = 295,
+ year = 2024,
+ eprint={2309.17309},
+ archivePrefix={arXiv},
+ primaryClass={hep-ex}
+}
@misc{stewart2023polyglot,
+ title={Polyglot Jet Finding},
+ author={Graeme Andrew Stewart and Philippe Gras and Benedikt Hegner and Atell Krasnopolski},
+ year={2023},
+ eprint={2309.17309},
+ archivePrefix={arXiv},
+ primaryClass={hep-ex}
+}
Ensure that the rapidity and azimuthal angle of the PseudoJet p are valid. If the azimuthal angle is invalid (used as a proxy for both variables), they are set to a valid value using _set_rap_phi!.
Arguments
p::PseudoJet: The PseudoJet object to ensure valid rapidity and azimuthal angle for.
_plain_jet_reconstruct(; particles::Vector{PseudoJet}, p = -1, R = 1.0, recombine = +)
This is the internal implementation of jet reconstruction using the plain algorithm. It takes a vector of particles representing the input particles and reconstructs jets based on the specified parameters. Here the particles must be of type PseudoJet.
Users of the package should use the plain_jet_reconstruct function as their entry point to this jet reconstruction.
The power value maps to specific pp jet reconstruction algorithms: -1 = AntiKt, 0 = Cambridge/Aachen, 1 = Inclusive Kt.
Arguments
particles: A vector of PseudoJet objects representing the input particles.
p=-1: The power to which the transverse momentum (pt) of each particle is raised.
R=1.0: The jet radius parameter.
recombine: The recombination function used to merge two jets. Default is + (additive recombination).
Returns
clusterseq: The resulting ClusterSequence object representing the reconstructed jets.
Set the rapidity and azimuthal angle of the PseudoJet p.
Arguments
p::PseudoJet: The PseudoJet object for which to set the rapidity and azimuthal angle.
Description
This function calculates and sets the rapidity and azimuthal angle of the PseudoJet p based on its momentum components. The rapidity is calculated in a way that is insensitive to roundoff errors when the momentum components are large. If the PseudoJet represents a point with infinite rapidity, a large number is assigned to the rapidity in order to lift the degeneracy between different zero-pt momenta.
Note - the ϕ angle is calculated in the range [0, 2π).
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.
Adds to the vector tile_union the tiles that are in the neighbourhood of the specified center_index, including itself and whose tagged status are false - start adding from position n_near_tiles-1, and increase n_near_tiles. 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.
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).
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.ßß
Perform the bookkeeping associated with the step of recombining jet_i and jet_j (assuming a distance dij).
Arguments
clusterseq::ClusterSequence: The cluster sequence object.
jet_i: The index of the first jet to be recombined.
jet_j: The index of the second jet to be recombined.
dij: The distance between the two jets.
recombine=+: The recombination function to be used. Default is addition.
Returns
newjet_k: The index of the newly created jet.
Description
This function performs the i-j recombination step in the cluster sequence. It creates a new jet by recombining the first two jets using the specified recombination function. The new jet is then added to the cluster sequence. The function also updates the indices and history information of the new jet and sorts out the history.
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.
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.
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.
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.
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.
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 peudojets
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.
Compute the indices of the right neighbors of a given center index in a tiling. This is used in the inital 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.
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.
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.
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 vaild 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.
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.
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.
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).
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
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
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.
Note: Either dcut or njets must be provided (but not both).
Returns
An array of LorentzVectorCyl objects representing the exclusive jets.
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.
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.
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.
Returns
An array of LorentzVectorCyl 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.
jet_reconstruct(particles; p = -1, R = 1.0, recombine = +, strategy = RecoStrategy.Best)
Reconstructs jets from a collection of particles using a specified algorithm and strategy
Arguments
particles: A collection of particles used for jet reconstruction.
p=-1: The power value used for the distance measure for generalised k_T, which maps to a particular reconstruction algorithm (-1 = AntiKt, 0 = Cambridge/Aachen, 1 = Kt).
R=1.0: The jet radius parameter.
recombine=+: The recombination scheme used for combining particles.
strategy=RecoStrategy.Best: The jet reconstruction strategy to use. RecoStrategy.Best makes a dynamic decision based on the number of starting particles.
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, and PseudoJet, for which these methods are already predefined in the JetReconstruction namespace.
recombine argument
The recombine argument is the function used to merge pairs of particles. The default is simply +(jet1,jet2), i.e. 4-momenta addition or the E-scheme.
Loads the jets from a file. Ignores lines that start with '#'. Each line gets processed in the following way: the line is split using split(line, splitby) or simply split(line) by default. Every value in this line is then converted to the dtype (which is Float64 by default). These values are then used as arguments for the constructor function which should produce individual jets. By default, the constructor constructs Lorentz vectors.
Everything that was already in jets is not affected as we only use push! on it.
Example
julia
# Load jets from two files into one array
+jets = []
+loadjets!("myjets1.dat", jets)
+loadjets!("myjets2.dat", jets)
plain_jet_reconstruct(particles::Vector{T}; p = -1, R = 1.0, recombine = +) where T
Perform jet reconstruction using the plain algorithm.
Arguments
particles::Vector{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.
p::Int=-1: The integer value used for jet reconstruction.
R::Float64=1.0: The radius parameter used for jet reconstruction.
recombine::Function=+: The recombination function used for jet reconstruction.
Note for the particles argument, the 4-vector methods need to exist in the JetReconstruction package namespace.
Returns
Vector{PseudoJet}: A vector of reconstructed jets.
Example
julia
jets = plain_jet_reconstruct(particles; p = -1, R = 1.0)
filename: The name of the file to save the jet data to.
jets: An array of jet objects to save.
format="px py pz E": (optional) A string specifying the format of the jet data to save. The default format is "px py pz E".
Details
This function saves jet data to a file in a specific format. Each line in the file represents a jet and contains the information about the jet in the specified format. The format string can include the following placeholders:
"E" or "energy": Jet energy
"px": Momentum along the x-axis
"py": Momentum along the y-axis
"pz": Momentum along the z-axis
"pt2": Square of the transverse momentum
"phi": Azimuth angle
"rapidity": Rapidity
Lines starting with '#' are treated as comments and are ignored.
It is strongly NOT recommended to put something other than values and (possibly custom) separators in the format string.
tiled_jet_reconstruct(particles::Vector{T}; p = -1, R = 1.0, recombine = +) where {T}
Main jet reconstruction algorithm entry point for reconstructing jets using the tiled stragegy for generic jet type T.
Note - if a non-standard recombination is used, it must be defined for JetReconstruction.PseudoJet, as this struct is used internally.
Arguments
particles::Vector{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)
p::Int = -1: The power parameter for the jet reconstruction algorithm, thus swiching between different algorithms.
R::Float64 = 1.0: The jet radius parameter for the jet reconstruction algorithm.
recombine::Function = +: The recombination function used for combining pseudojets.
Returns
Vector{PseudoJet}: A vector of reconstructed jets.
Example
julia
tiled_jet_reconstruct(particles::Vector{LorentzVectorHEP}; p = -1, R = 0.4, recombine = +)
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.
jets::Vector{PseudoJet}: The physical PseudoJets in the cluster sequence. Each PseudoJet corresponds to a position in the history.
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.
The PseudoJet struct represents a pseudojet, a four-momentum object used in jet reconstruction algorithms. Additonal 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.
Animate the jet reconstruction process and save it as a video file.
Arguments
cs::ClusterSequence: The cluster sequence object containing the jets.
filename: The name of the output video file.
Optional Arguments
barsize_phi=0.1: The size of the bars in the phi direction.
barsize_y=0.1: The size of the bars in the y direction.
colormap=:glasbey_category10_n256: The colormap to use for coloring the jets.
perspective=0.5: The perspective of the plot.
azimuth=2.7: The azimuth angle of the plot.
elevation=0.5: The elevation angle of the plot.
framerate=5: The framerate of the output video.
end_frames=0: The number of static frames to show at the end of the animation. This can be useful to show the final state of the jets for a longer time.
title=nothing: The title to add to the plot.
ancestors=false: Whether to include ancestors of the jets in the animation. When true the ancestors of the jets will be plotted as well, as height zero bars, with the same colour as the jet they are ancestors of.
Module: The plotting module to use. Default is Makie.
For perspective, azimuth, and elevation, a single value can be passed for a fixed viewpoint, or a tuple of two values for a changing viewpoint. The viewpoint will then change linearly between the two values over the course of the animation.
Returns
fig: The figure object representing the final frame.
Plots a 3d bar chart that represents jets. Takes an objects array of objects to display and idx_arrays, an array of arrays with indeces, where idx_arrays[i] gives indeces of objects that form the jet number i. This function's signature might not be the most practical for the current version of the JetReconstruction.jl package, as it has been written during the early stage of development. There is now an overload of it that takes a ClusterSequence object as its argument.
Optional arguments: barsize_phi::Real — width of a bar along the ϕ axis; barsize_eta::Real — width of a bar along the η axis; colormap::Symbol — Makie colour map; Module — the module where you have your Makie (see below);
# example
+using CairoMakie # use any other Makie that you have here
+
+jetsplot([object1, object2, object3], [[1], [2, 3]])
The example above plots object1 as a separate jet in one colour and object2 and object3 together in another colour.
This function needs Makie.jl to work. You should install and import/use a specific backend yourself. jetsplot works with CairoMakie, WGLMakie, GLMakie, etc. Additionally, you can specify the module where you have your Makie explicitly:
Plots a 3d bar chart that represents jets. Takes objects, an array of objects to display (should be the same array you have passed to jet_reconstruct to get the cs::ClusterSequence), and the cs::ClusterSequence itself as arguments.
Optional arguments: barsize_phi::Real — width of a bar along the ϕ axis; barsize_eta::Real — width of a bar along the η axis; colormap::Symbol — Makie colour map; Module — the module where you have your Makie (see below);
# example
+using CairoMakie # use any other Makie that you have here
+jetsplot([object1, object2, object3], cluster_sequence_I_got_from_jet_reconstruct; Module=CairoMakie)
This function needs Makie.jl to work. You should install and import/use a specific backend yourself. jetsplot works with CairoMakie, WGLMakie, GLMakie, etc. Additionally, you can specify the module where you have your Makie explicitly:
