JetReconstruction

Jet reconstruction (reclustering) with Julia

https://github.com/juliahep/jetreconstruction.jl

Science Score: 77.0%

This score indicates how likely this project is to be science-related based on various indicators:

✓
CITATION.cff file
Found CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
✓
DOI references
Found 1 DOI reference(s) in README
✓
Academic publication links
Links to: arxiv.org, zenodo.org
✓
Committers with academic emails
2 of 11 committers (18.2%) from academic institutions
○
Institutional organization owner
○
JOSS paper metadata
○
Scientific vocabulary similarity
Low similarity (10.2%) to scientific vocabulary

Keywords

hep jet-finding jet-reclustering jet-reconstruction julia physics

Keywords from Contributors

interpretability pde particles battery high-energy-physics meshing matrix-exponential hack state-management numerics

Last synced: 6 months ago · JSON representation ·

Repository

Jet reconstruction (reclustering) with Julia

Basic Info

Host: GitHub
Owner: JuliaHEP
License: mit
Language: Julia
Default Branch: main
Homepage: https://juliahep.github.io/JetReconstruction.jl/
Size: 38.9 MB

Statistics

Stars: 24
Watchers: 8
Forks: 13
Open Issues: 17
Releases: 13

Topics

hep jet-finding jet-reclustering jet-reconstruction julia physics

Created over 3 years ago · Last pushed 6 months ago

Metadata Files

Readme Contributing License Code of conduct Citation

JetReconstruction.jl

This package implements sequential Jet Reconstruction (clustering)

Algorithms

Algorithms used are based on the C++ FastJet package (https://fastjet.fr, hep-ph/0512210, arXiv:1111.6097), reimplemented natively in Julia.

The algorithms include anti-${k}_\text{T}$, Cambridge/Aachen, inclusive $k_\text{T}$, generalised $k_\text{T}$ for $pp$ events; and the Durham algorithm and generalised $k_\text{T}$ for $e^+e^-$.

Interface

The simplest interface is to call:

julia cs = jet_reconstruct(particles::AbstractVector{T}; algorithm = JetAlgorithm.AntiKt, R = 1.0)

particles - a one dimensional array (vector) of input particles for the clustering
- Any type that supplies the methods pt2(), phi(), rapidity(), px(), py(), pz(), energy() can be used
- These methods have to be defined in the namespace of this package, i.e., JetReconstruction.pt2(::T)
- The PseudoJet or EEJet types from this package, a 4-vector from LorentzVectorHEP, or a ReconstructedParticle from EDM4hep are suitable (and have the appropriate definitions)
algorithm is the name of the jet algorithm to be used (from the JetAlgorithm enum)
- JetAlgorithm.AntiKt anti-${k}_\text{T}$ clustering
- JetAlgorithm.CA Cambridge/Aachen clustering
- JetAlgorithm.Kt inclusive $k_\text{T}$
- JetAlgorithm.GenKt generalised $k_\text{T}$ (which also requires specification of p)
- JetAlgorithm.Durham the $e^+e-$ $k_\text{T}$ algorithm, also known as the Durham algorithm
- JetAlgorithm.EEKt the $e^+e-$ generalised $k_\text{T}$ algorithm (which also requires specification of p)
R - the cone size parameter; no particles more geometrically distance than R will be merged (default 1.0; note this parameter is ignored for the Durham algorithm)

The object returned is a ClusterSequence, which internally tracks all merge steps.

For a more complete description of all possible parameters please refer to the documentation.

To obtain the final inclusive jets, use the inclusive_jets method:

julia final_jets = inclusive_jets(cs::ClusterSequence; ptmin=0.0)

Only jets passing the cut $pT > p{Tmin}$ will be returned. The result is returned as a Vector{LorentzVectorHEP}, but different return types can be specified (e.g., inclusive_jets(cs::ClusterSequence, EEJet; ptmin=0.0)).

Sorting

As sorting vectors is trivial in Julia, no special sorting methods are provided. As an example, to sort exclusive jets of $>5.0$ (usually GeV, depending on your EDM) from highest energy to lowest:

julia sorted_jets = sort!(inclusive_jets(cs::ClusterSequence; ptmin=5.0), by=JetReconstruction.energy, rev=true)

Strategy

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 interaction (works well for low $N$) | plain_jet_reconstruct | | RecoStrategy.N2Tiled | Use tiles of radius $R$ to limit search space (works well for higher $N$) | 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

plainjetreconstruct(particles::AbstractVector{T}; algorithm = JetAlgorithm.AntiKt, R = 1.0) ```

Note that there is no strategy option in these interfaces.

Examples

In the examples directory there are a number of example scripts (note there is a specific Project.toml for examples).

See the jetreco.jl script for an example of how to call jet reconstruction.

sh julia --project jetreco.jl --algorithm=AntiKt ../test/data/events.pp13TeV.hepmc3.zst ... julia --project jetreco.jl --algorithm=Durham ../test/data/events.eeH.hepmc3.zst ... julia --project jetreco.jl --maxevents=10 --strategy=N2Plain --algorithm=Kt --exclusive-njets=3 ../test/data/events.pp13TeV.hepmc3.zst ...

There are options to explicitly set the algorithm (use --help to see these).

The example also shows how to use JetReconstruction.HepMC3 to read HepMC3 ASCII files (via the read_final_state_particles() wrapper).

Further examples, which show visualisation, timing measurements, profiling, etc. are given - see the README.md file in the examples directory.

Note that due to additional dependencies the Project.toml file for the examples is different from the package itself.

Plotting

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.

Reference

Although it has been developed further since the CHEP2023 conference, the CHEP conference proceedings, arXiv:2309.17309, should be cited if you use this package:

bibtex @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} }

Copyright

The code is under the MIT License.

Contributors ✨

Thanks goes to these contributors to this code (emoji key):

_{Graeme A Stewart} 🚇 ⚠️ 📖 💻 💡 👀	_{Philippe Gras} ⚠️ 📖 💻 💡	_{Atell Krasnopolski} ⚠️ 📖 💻 💡	_{Sattwamo Ghosh} ⚠️ 📖 💻 💡	_{Jerry Ling} 📖 👀	_hegner 📖	_{Mateusz Jakub Fila} 📖 🚇 ⚠️ 👀
_ExpandingMan 🚇	_emadmtr ⚠️ 💻 📖 💡

This project follows the all-contributors specification. Contributions of any kind welcome!

Owner

Name: JuliaHEP
Login: JuliaHEP
Kind: organization

Repositories: 18
Profile: https://github.com/JuliaHEP

Citation (CITATION.cff)

# This CITATION.cff file was generated with cffinit.
# Visit https://bit.ly/cffinit to generate yours today!

cff-version: 1.2.0
title: JetReconstruction.jl
message: >-
  If you use this software, please cite it using the
  software DOI and the preferred citation.
type: software
authors:
  - given-names: Graeme Andrew
    family-names: Stewart
    email: graeme.andrew.stewart@cern.ch
    affiliation: CERN
    orcid: 'https://orcid.org/0000-0003-0182-7088'
  - given-names: Atell
    family-names: Krasnopolski
    email: delta_atell@protonmail.com
    orcid: 'https://orcid.org/0009-0009-9336-0219'
  - given-names: Philippe
    family-names: Gras
    email: philippe.gras@cern.ch
    orcid: 'https://orcid.org/0000-0002-3932-5967'
  - given-names: Sattwamo
    family-names: Ghosh
identifiers:
  - type: doi
    value: 10.5281/zenodo.12671414
    description: Zenodo
preferred-citation:
  type: article
  title: Polyglot Jet Finding
  authors:
    - given-names: Graeme Andrew
      family-names: Stewart
      email: graeme.andrew.stewart@cern.ch
      affiliation: CERN
      orcid: 'https://orcid.org/0000-0003-0182-7088'
    - given-names: Atell
      family-names: Krasnopolski
      email: delta_atell@protonmail.com
      orcid: 'https://orcid.org/0009-0009-9336-0219'
    - given-names: Philippe
      family-names: Gras
      email: philippe.gras@cern.ch
      orcid: 'https://orcid.org/0000-0002-3932-5967'
    - given-names: Benedikt
      family-names: Hegner
      email: benedikt.hegner@cern.ch
      affiliation: CERN
      orcid: 'https://orcid.org/0009-0009-2020-1620'
  identifiers:
    - type: doi
      value: 10.1051/epjconf/202429505017
repository-code: 'https://github.com/JuliaHEP/JetReconstruction.jl'
abstract: Jet reconstruction (reclustering) with Julia
license: MIT

Committers

Last synced: 8 months ago

All Time

Total Commits: 196
Total Committers: 11
Avg Commits per committer: 17.818
Development Distribution Score (DDS): 0.413

Past Year

Commits: 79
Committers: 8
Avg Commits per committer: 9.875
Development Distribution Score (DDS): 0.392

Top Committers

Name	Email	Commits
Graeme A Stewart	g**t@c**h	115
Atell	d**l@p**m	43
Mateusz Jakub Fila	3****a	12
allcontributors[bot]	4****]	9
Jerry Ling	p**n@j**v	7
hegner	b**r@c**h	2
github-actions[bot]	4****]	2
dependabot[bot]	4****]	2
Sattwamo Ghosh	1****o	2
ExpandingMan	E****n	1
CompatHelper Julia	c**y@j**g	1

Committer Domains (Top 20 + Academic)

cern.ch: 2 julialang.org: 1 jling.dev: 1

Issues and Pull Requests

Last synced: 6 months ago

All Time

Total issues: 41
Total pull requests: 125
Average time to close issues: 29 days
Average time to close pull requests: 9 days
Total issue authors: 8
Total pull request authors: 11
Average comments per issue: 2.2
Average comments per pull request: 2.6
Merged pull requests: 96
Bot issues: 0
Bot pull requests: 35

Past Year

Issues: 39
Pull requests: 119
Average time to close issues: 25 days
Average time to close pull requests: 10 days
Issue authors: 7
Pull request authors: 11
Average comments per issue: 1.95
Average comments per pull request: 2.71
Merged pull requests: 90
Bot issues: 0
Bot pull requests: 35

View more stats

Top Authors

Issue Authors

graeme-a-stewart (43)
mattleblanc (4)
Moelf (3)
m-fila (3)
HarryWang0619 (2)
mgratrix (2)
mmikhasenko (1)
JuliaTagBot (1)

Pull Request Authors

graeme-a-stewart (69)
m-fila (29)
allcontributors[bot] (24)
github-actions[bot] (8)
sattwamo (5)
dependabot[bot] (5)
Moelf (4)
ExpandingMan (2)
mattleblanc (2)
emadmtr (2)
HarryWang0619 (2)
gojakuch (2)
hegner (1)

Top Labels

Issue Labels

enhancement (10) documentation (7) bug (5) interface change (5) Internals (5) examples (4) Current release series (4) tests (4) question (3) interface (2) good first issue (1)

Pull Request Labels

enhancement (10) documentation (8) bug (8) tests (7) interface change (7) Current release series (6) dependencies (5) cherry pick to main (4) examples (4) github_actions (3) Internals (2)

Packages

Total packages: 1
Total downloads:
- julia 6 total

Total dependent packages: 0
Total dependent repositories: 0
Total versions: 13

juliahub.com: JetReconstruction

Jet reconstruction (reclustering) with Julia

Homepage: https://juliahep.github.io/JetReconstruction.jl/
Documentation: https://docs.juliahub.com/General/JetReconstruction/stable/
License: MIT
Latest release: 0.4.9
published 7 months ago

Versions: 13
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 6 Total

Rankings

Dependent repos count: 3.2%

Downloads: 3.8%

Average: 7.8%

Dependent packages count: 16.3%

Last synced: 6 months ago