Repository navigation
External type generalisation - #247
Draft
graeme-a-stewart wants to merge 38 commits into
Draft
graeme-a-stewart wants to merge 38 commits into
graeme-a-stewart wants to merge 38 commits into
Conversation
Working parameterised reconstruction for pp with tiled algorithm.
These are now properly parameterised
With parameterised jet and cluster sequence types
We don't use underscores in any of the other test files
Improve type concretiser for jet selectors, when a user can pass an un-parametrised type, and this will be concretised. Fix parametrisation for jet preprocessors and adders. Further parametrised constructors for PseudoJet, from (pt, rap, phi). Fix softkiller function signatures for default types. Fix HepMC3 reader to parameterise return types. Read test files with set parametrised types, ensure tests use parameters are needed.
Invalid PseudoJets are constructed now as zero(PseudoJet), which sets the cluster_hist_index to typemin(Int). Tests for validity specifically probe this field value.
FourMomentum, EEJet, PseudoJet are updated to take a numerical parametrisation type, T <: Real. Constructors are added to ensure that concrete jets can be constructed without an explicit T (taking T from the input values) or with an explicit T. eltype() is defined to return the numerical type. A useful helper function, construct_reco_jets() is added that converts input particles into the starting "jets" for reconstruction, that avoids significant code duplication in all of the reco algorithm entry points.
Significant changes to correctly propagate parametrised numerical type though the reconstuction algorithms. Documentation is updated.
Fix a few small documentation errors. Add some sanity checks in the generic reconstruction interface, checking that we do have particles (disallow passing a zero length vector) and that the R value is sane.
Allow for reconstruction to be run with Float16, Float32 or Float64.
Ensure that type T (the numerical type of the EEJet) is used at all points in the reconstruction, including functional calls. Parameterise functions to T to ensure that mismatched types do not get used by accident. Reduces regression by about 40%. - pre this commit, reco time 35us - post this commit, reco time 29us - pre-parametrisation, reco time 21us
Ensure that all parameters are made consistent with the numerical type of the underlying PseudoJet. Add strict type specifiers to all internal functions, preventing accidentally calling them with mismatched numerical types.
Also, reran formatting
Adapt unit tests to new paramaterisation. Remove some unnecessarily harsh parameter typing and instead apply conversions as needed. Remove bogus "optimisation" for type of "p" in insert_new_jet!().
Also prettify output
Had not been parameterised correctly (fixes visualisation)
Ensure that jets of a parameterised numerical type can be constructed correctly from an EDM4hep ReconstructedParticle. Support explicit type declaration and taking the type from the ReconstructedParticle (usually Float32).
Support correctly non-parameterised instantiation
graeme-a-stewart
force-pushed
the
external-type-generalisation
branch
from
June 11, 2026 19:27
4a63d7c to
1e058fa
Compare
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #247 +/- ##
==========================================
+ Coverage 82.94% 83.36% +0.41%
==========================================
Files 23 23
Lines 1431 1485 +54
==========================================
+ Hits 1187 1238 +51
- Misses 244 247 +3 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Important to preserve the "develop" path for JetReconstruction as a relative one.
This was referenced Jun 12, 2026
graeme-a-stewart
force-pushed
the
external-type-generalisation
branch
from
June 12, 2026 13:11
5ce739d to
8a26d0b
Compare
graeme-a-stewart
marked this pull request as draft
August 18, 2026 08:44
| end | ||
|
|
||
| if isnothing(preprocess) | ||
| if P == J |
Collaborator
There was a problem hiding this comment.
I think this should compare the element type instead:
eltype(particles) == TargetJetTypeWith the current signature, P is the vector type, while J is the jet type.
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR adds support so that the underlying numerical type of jets becomes parameterised, instead of being fixed to
Float64. The parameterisation isT <: Real, which includes all float types and dual numbers (for potential autodiff applications).One exception to parametrisation is the
TiledJetstructure used in theN2Tiledalgorithm. This remains fixed toFloat64, due to the use of a concrete singleton (noTiledJet) as the sentinel for linked lists (and to indicate tiles with no jets). As discussed in #91, this is tricky to optimise (I have a branch with a proof of concept thatTiledJetcan be parameterised, but it is not performance optimised as it allocates too manyRef{TiledJet}s).Main Change Summary
Performance Report
The main optimisation steps of ensuring type consistency in mathematical operations have been done:
TTwhen appropriate, to ensure that mixed parameters are not passed by accidentThere has been some observation of a slight performance regression on pp reconstruction, but latest measurements show this as minimal O(1%) and not very consistent. Degradations also seem to be platform and phase of the moon (time) dependent, indicating no serious issue with the implementation.
Parametrisation
EEJet,PseudoJetandEERecoJetare now parameterised onT <: Real(also the common abstractFourMomentumtype). The number of constructors is considerably expanded to cover cases when initialisation is explicit as well as implicit, and including mixed types, where promotion is applied. Conversion fromLorentzVector,LorentzVectorCyland anything supportingLorentzVectorBaseare also covered. If the EDM4hep extension is loaded, construction fromEDM4hep.ReconstructedParticleis supported.ClusterSequence,HistoryElementandSoftKillerare likewise parameterised and will be initialised to the sameTas the input particles.For consistency
Tis used as the numerical type of the jet's parameters, andJis used for the jet type.Invalid Values
When an invalid jet is returned from substructure functions, this is no longer a singleton (which cannot be parameterised), but is a
PseudoJet{T}whereisvalid(jet) == false. Technically this is implemented by setting the_cluster_hist_indextotypemin(Int), but this is an internal detail - useisvalid()!Reconstruction Interfaces
The common
jet_reconstructioninterface is left unchanged, but in the algorithm specific entry functions (ee_genkt_algorithm,plain_jet_reconstruct,tiled_jet_reconstruct) the numerical type of the input particle vector is interrogated to pick the appropriate jet type conversion. This code is also factorised, avoiding duplication (construct_reco_jets).Jet Utility Interfaces
For substructure, soft killer and Lund plane, all interfaces are updated to parameterised jet types.
Robustness
Absurd
Rvalues (<=0or>2pi) throws an error. Attempting reconstruction with no inputs returns an emptyClusterSequence.Tests
Tests are updated to use parameterised values, when required.
test-reco-numtypes.jltests that reconstruction works forFloat32andFloat16.Examples
The
instrumented-jetreco.jlandbenchmark.shscripts can now handle a numerical type parameter, allowing non-Float64 reconstruction to be tested (--numtypeargument, second positional parameter respectively). Other examples are updated to adapt to parameterised types.JetReconstruction Package Version
This change is quite intrusive and potentially breaks client code when types become important to specify (e.g., see the fixes in the various example code scripts). This PR should therefore be considered a major change, targeting v2.0.0.
Files Modified
Source Files (31 changed)
src/JetReconstruction.jl: Module file updated for new type parameterssrc/CommonJet.jl: BaseFourMomentum{T}type and utilitiessrc/PseudoJet.jl: Complete parametrisation of pp jet typesrc/EEJet.jl: Complete parametrisation of e⁺e⁻ jet typesrc/JetUtils.jl: Updated utility functions for parameterised typessrc/AlgorithmStrategyEnums.jl: Minor updates for type consistencysrc/ClusterSequence.jl: Parameterised history and cluster sequence typessrc/PlainAlgo.jl: N2Plain strategy with type parameterssrc/TiledAlgoLL.jl: N2Tiled strategy with type parameterssrc/TiledAlgoUtils.jl: Tiled algorithm utilities updatedsrc/TiledAlgoLLStructs.jl: Struct definitions updatedsrc/GenericAlgo.jl: Main reconstruction entry point updatedsrc/EEAlgorithm.jl: e⁺e⁻ algorithms updatedsrc/Substructure.jl: All substructure functions updatedsrc/LundPlane.jl: Lund plane generation updatedsrc/SoftKiller.jl: Pileup mitigation updatedsrc/HepMC3.jl: HepMC3 reader updatedsrc/Utils.jl: Utility functions updatedsrc/JSONresults.jl: JSON output types updatedDocumentation Files
README.md: Updated example to show explicit type parameterdocs/src/substructure.md: Minor updates for type signaturesTest Files
test/test-reco-numtypes.jl: New file with numerical type teststest/_common.jl: Updated for new typestest/runtests.jl: Updated test runnerExample Files
examples/benchmark.sh: Added optional numtype as positional parameterexamples/instrumented-jetreco.jl: Added--numtypeoptionexamples/constituents/jetreco-constituents.jl: Pass explicit numerical typeexamples/constituents/jetreco-constituents.jl: Use own copy of JetReconstructionexamples/softkiller/softkiller_plots.jl: Use explicit numerical typeexamples/softkiller/softkiller_runtime.jl: Use explicit numerical typeexamples/visualisation/visualise-jets-nb.jl: Use own copy of JetReconstruction