Removed Jet Substructure Structs (#138)

* Removed Jet Substructure Structs

Using separate structs for calling substructure functions seemed redundant.
Removed the structs and incorporated their functionalities into the functions itself.

* use local version of JetReconstruction in examples and docs (#142)

* Jet utilities (#141) (#144)

Add functions to calculate the momentum fraction and the kt scale for jets.

- pt_fraction() for transverse momentum fraction
- kt_scale()

These are implemented generically for both jet types, though
may be primary interesting for pp events (PseudoJet).

deltar is added as a helper that returns the jet separation in
pseudorapidity-phi. This is distinct from deltaR which operates
in rapidity-phi space. These are probably not the greatest names,
but are not in the public API. deltaR is moved to the new source
file, JetUtils.jl.

There is a small tidy up of the logic for calculating ϕ
where the check for ϕ>2π can never be true.

Added functions to convert jets to LorentzVector and
LorentzVectorCyl. This required some initial refactoring
of jet methods to be general, rather than PseudoJet specific,
which will be continued.

(cherry picked from commit c7cfa9e)

* Rename EEjet to EEJet (#137)

* Rename EEjet to EEJet

Follow Julia standard capitalisation more closely

* Rename source file

* Update struct name

Co-authored-by: Mateusz Jakub Fila <[email protected]>

* Add basic unit tests for jet types

This improves test coverage

* Fixup a few old struct name references

---------

Co-authored-by: Mateusz Jakub Fila <[email protected]>

* Modified function signatures

Modified the function signatures for `mass_drop`, `soft_drop`, `jet_filtering` and `jet_trimming` and updated documentations.
Added `invalid_pseudojet` and `isvalid` and modified `test-substructure.jl`.

* Better comparison against invalid_pseudojet

Co-authored-by: Mateusz Jakub Fila <[email protected]>

* Use invalid from Base; documentation improvements

* Add type specifiers to docstrings

---------

Co-authored-by: Mateusz Jakub Fila <[email protected]>
Co-authored-by: Graeme A Stewart <[email protected]>

Author: 3 people

docs/src/substructure.md

@@ -1,79 +1,64 @@
 # Jet Substructure
 
-Jet substructure techniques provide powerful tools for analyzing and refining the properties of jets. Below are some of the key jet substructure functions, that are available.
+Jet substructure techniques provide powerful tools for analysing and refining the properties of jets. Below are some of the key jet substructure functions that are available.
 
 ### Mass Drop Tagging
 
 ```julia
-mass_drop(jet::PseudoJet, clusterseq::ClusterSequence, tag::MassDropTagger) -> PseudoJet
+mass_drop(jet::PseudoJet, clusterseq::ClusterSequence{PseudoJet}; mu::Float64, y::Float64) -> PseudoJet
 ```
 
 The [mass_drop](@ref) function identifies subjets in a jet that pass the mass drop tagging condition. To use the `mass_drop` function:
 
-- Configure the [MassDropTagger](@ref) with parameters tailored to the expected mass drop and distance thresholds for analysis.
-
-```julia
-tagger = MassDropTagger(mu=0.67, y=0.09)
-```
-
 - Apply the `mass_drop` function to the jet and its clustering sequence.
 
 ```julia
-tagged_jet = mass_drop(jet, clusterseq, tagger)
+tagger = (mu=0.67, y=0.09)
+tagged_jet = mass_drop(jet, clusterseq; tagger...)
 ```
 
-- If the jet is tagged successfully, the function returns the identified subjet. Else it returns `PseudoJet(0.0, 0.0, 0.0, 0.0)`.
+- If the jet is tagged successfully, the function returns the identified subjet. Else it returns the `invalid_pseudojet` object.
 
 ---
 
 ### Soft Drop Tagging
 
 ```julia
-soft_drop(jet::PseudoJet, clusterseq::ClusterSequence, tag::SoftDropTagger) -> PseudoJet
+soft_drop(jet::PseudoJet, clusterseq::ClusterSequence{PseudoJet}: zcut::Real, beta::Real) -> PseudoJet
 ```
 
 The [soft_drop](@ref) function applies soft-drop grooming to remove soft, wide-angle radiation from jets. It reclusters the jet with a specified radius and clustering method, iteratively checking the soft-drop condition on subjets. To use the `soft_drop` function:
 
-- Construct the [SoftDropTagger](@ref) by defining the parameters for the grooming process, such as the energy fraction (`zcut`) and angular exponent (`b`)
-
-```julia
-tagger = SoftDropTagger(zcut=0.1, b=2.0)
-```
-
-By default, the reclustering radius is set to `1.0` which can be modified by defing the `tagger` object as
+- Apply the `soft_drop` function to the jet and its clustering sequence.
 
 ```julia
-tagger = SoftDropTagger(zcut=0.1, b=2.0, cluster_rad=0.4)
+tagger = (zcut = 0.1, beta = 2.0)
+tagged_jet = soft_drop(jet, clusterseq; tagger...)
 ```
 
-- Apply the `soft_drop` function to the jet and its clustering sequence.
-
+By default, the reclustering radius is set to `1.0` which can be modified by the user as:
 ```julia
-tagged_jet = soft_drop(jet, clusterseq, tagger)
+tagger = (zcut = 0.1, beta = 2.0, radius = 0.4)
+tagged_jet = soft_drop(jet, clusterseq; tagger...)
 ```
 
-- If the jet is tagged successfully, the function returns the identified subjet. Else it returns `nothing`.
+- If the jet is tagged successfully, the function returns the identified subjet. Else it returns the `invalid_pseudojet` object.
 
 ---
 
 ### Jet Filtering
 
 ```julia
-jet_filtering(jet::PseudoJet, clusterseq::ClusterSequence, filter::JetFilter) -> PseudoJet
+jet_filtering(jet::PseudoJet, clusterseq::ClusterSequence{PseudoJet}; radius::Real, hardest_jets::Integer) -> PseudoJet
 ```
 
 The [jet_filtering](@ref) function filters a jet to retain only the hardest subjets based on a specified radius and number. To use the function:
 
-- Set the radius for subjet clustering and the number of hardest subjets to retain in a [JetFilter](@ref) method.
-
-```julia
-filter = JetFilter(filter_radius=0.3, num_hardest_jets=3)
-```
-
 - Apply the `jet_filtering` function to refine the jet.
 
 ```julia
-filtered_jet = jet_filtering(jet, clusterseq, filter)
+filter = (radius=0.3, hardest_jets=3)
+filtered_jet = jet_filtering(jet, clusterseq; filter...)
 ```
 
 - The function returns the filtered jet that retains only the most significant subjets, reducing noise.
@@ -83,26 +68,21 @@ filtered_jet = jet_filtering(jet, clusterseq, filter)
 ### Jet Trimming
 
 ```julia
-jet_trimming(jet::PseudoJet, clusterseq::ClusterSequence, trim::JetTrim) -> PseudoJet
+jet_trimming(jet::PseudoJet, clusterseq::ClusterSequence{PseudoJet}; radius::Real, fraction::Real, recluster_method::JetAlgorithm.Algorithm) -> PseudoJet
 ```
 
 The [jet_trimming](@ref) function trims a jet by removing subjets with transverse momentum below a specified fraction of the main jet's momentum. This method cleans up jets by removing soft particles. To use this function:
 
-- Configure the trimming radius and momentum fraction threshold in [JetTrim](@ref)
-
-```julia
-trim = JetTrim(trim_radius=0.3, trim_fraction=0.3, recluster_method=JetAlgorithm.CA)
-```
-
-It is to be noted that the `jet_trimming` function reclusters the constituents of the jet using either `C/A` or `kT ` algorithm, which needs to be specified.
-
 - Apply the `jet_trimming` function to clean the jet.
 
 ```julia
-trimmed_jet = jet_trimming(jet, clusterseq, trim)
+trim = (radius=0.3, fraction=0.3, recluster_method=JetAlgorithm.CA)
+trimmed_jet = jet_trimming(jet, clusterseq; trim...)
 ```
 
-- The function returns the trimmed jet.
+- The function returns the trimmed jet if trimming is successful, or the `invalid_pseudojet` object.
+
+It is to be noted that the `jet_trimming` function reclusters the constituents of the jet using either `C/A` or `kT ` algorithm, which needs to be specified.
 
 ---
 

examples/substructure/jet-grooming.jl

@@ -11,28 +11,21 @@ event_no = 1
 cluster_seq = jet_reconstruct(events[event_no], p = 0, R = 1.0)
 jets = inclusive_jets(cluster_seq; ptmin = 5.0, T = PseudoJet)
 
-r = 0.3     # recluster radius
-n = 3       # number of hard jets to consider
+filter = (radius = 0.3, hardest_jets = 3)
 
-filter = JetFilter(r, n)
-
-@info "Jet Filtering: recluster radius = $r, hard subjets to consider = $n"
+@info "Jet Filtering: recluster radius = $(filter.radius), hard subjets to consider = $(filter.hardest_jets)"
 for jet in jets
-    filtered = jet_filtering(jet, cluster_seq, filter)
+    filtered = jet_filtering(jet, cluster_seq; filter...)
 
     println("Original jet: pt = $(JetReconstruction.pt(jet)), rap = $(JetReconstruction.rapidity(jet)), phi = $(JetReconstruction.phi(jet)), E = $(jet.E)")
     println("Filtered jet: pt = $(JetReconstruction.pt(filtered)), rap = $(JetReconstruction.rapidity(filtered)), phi = $(JetReconstruction.phi(filtered)), E = $(filtered.E)\n")
 end
 
-r = 0.3                     # recluster radius
-f = 0.3                     # trim fraction
-m = JetAlgorithm.CA         # recluster method
-
-trim = JetTrim(r, f, m)
+trim = (radius = 0.3, fraction = 0.3, recluster_method = JetAlgorithm.CA)
 
-@info "Jet Trimming: recluster radius = $r, trim fraction = $f, recluster method = $m"
+@info "Jet Trimming: recluster radius = $(trim.radius), trim fraction = $(trim.fraction), recluster method = $(trim.recluster_method)"
 for jet in jets
-    trimmed = jet_trimming(jet, cluster_seq, trim)
+    trimmed = jet_trimming(jet, cluster_seq; trim...)
 
     println("Original jet: pt = $(JetReconstruction.pt(jet)), rap = $(JetReconstruction.rapidity(jet)), phi = $(JetReconstruction.phi(jet)), E = $(jet.E)")
     println("Trimmed jet: pt = $(JetReconstruction.pt(trimmed)), rap = $(JetReconstruction.rapidity(trimmed)), phi = $(JetReconstruction.phi(trimmed)), E = $(trimmed.E)\n")

examples/substructure/jet-tagging.jl

@@ -11,26 +11,20 @@ event_no = 1
 cluster_seq = jet_reconstruct(events[event_no], p = 0, R = 1.0)
 jets = inclusive_jets(cluster_seq; ptmin = 5.0, T = PseudoJet)
 
-μ = 0.67        # jet mass ratio
-y = 0.09        # symmetry cut
+MDtagger = (mu = 0.67, y = 0.09)
 
-MDtagger = MassDropTagger(μ, y)
-
-@info "Mass Drop Tagging: μ = $μ, y = $y"
+@info "Mass Drop Tagging: μ = $(MDtagger.mu), y = $(MDtagger.y)"
 for jet in jets
-    tagged = mass_drop(jet, cluster_seq, MDtagger)
+    tagged = mass_drop(jet, cluster_seq; MDtagger...)
     println("Original jet: pt = $(JetReconstruction.pt(jet)), rap = $(JetReconstruction.rapidity(jet)), phi = $(JetReconstruction.phi(jet)), E = $(jet.E)")
     println("Tagged jet: pt = $(JetReconstruction.pt(tagged)), rap = $(JetReconstruction.rapidity(tagged)), phi = $(JetReconstruction.phi(tagged)), E = $(tagged.E)\n")
 end
 
-z = 0.1         # soft drop threshold
-b = 2.0         # angular exponent
-
-SDtagger = SoftDropTagger(z, b)
+SDtagger = (zcut = 0.1, beta = 2.0)
 
-@info "Soft Drop Tagging: recluster radius = $(SDtagger.cluster_rad), zcut = $z, b = $b"
+@info "Soft Drop Tagging: zcut = $(SDtagger.zcut), b = $(SDtagger.beta)"
 for jet in jets
-    tagged = soft_drop(jet, cluster_seq, SDtagger)
+    tagged = soft_drop(jet, cluster_seq; SDtagger...)
     println("Original jet: pt = $(JetReconstruction.pt(jet)), rap = $(JetReconstruction.rapidity(jet)), phi = $(JetReconstruction.phi(jet)), E = $(jet.E)")
     println("Tagged jet: pt = $(JetReconstruction.pt(tagged)), rap = $(JetReconstruction.rapidity(tagged)), phi = $(JetReconstruction.phi(tagged)), E = $(tagged.E)\n")
 end

src/JetReconstruction.jl

@@ -73,8 +73,7 @@ export jet_reconstruct
 
 ## Substructure modules
 include("Substructure.jl")
-export MassDropTagger, SoftDropTagger, JetFilter, JetTrim, mass_drop, soft_drop,
-       jet_filtering, jet_trimming
+export mass_drop, soft_drop, jet_filtering, jet_trimming
 
 # Simple HepMC3 reader
 include("HepMC3.jl")

src/Pseudojet.jl

@@ -91,6 +91,23 @@ A PseudoJet object.
 PseudoJet(px::Real, py::Real,
 pz::Real, E::Real) = PseudoJet(px, py, pz, E, 0, px^2 + py^2)
 
+"""Used to mark an invalid result in case the corresponding substructure tagging fails."""
+const invalid_pseudojet = PseudoJet(0.0, 0.0, 0.0, 0.0)
+
+import Base.isvalid
+"""
+    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.
+
+# Arguments
+- `j::PseudoJet`: The `PseudoJet` object to check.
+
+# Returns
+- `Bool`: `true` if the `PseudoJet` object is non-zero, `false` otherwise. 
+"""
+isvalid(j::PseudoJet) = !(j === invalid_pseudojet)
+
 import Base.show
 """
     show(io::IO, jet::PseudoJet)