Skip to content

Commit 80c3fd2

Browse files
graeme-a-stewartgraeme-a-stewart
authored
Add Documenter.jl setup (#57)
* Basic Documenter setup Basic documentation build Images are moved into a docs/src/assets directory Export n_exclusive_jets() method * Refine documentation Add more details on the main interface Split examples into their own section * Add Documenter GH action * Minor change to main docs
1 parent 8b5f582 commit 80c3fd2

11 files changed

+253
-8
lines changed

‎.github/workflows/Documentation.yml

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
name: Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
tags: '*'
8+
pull_request:
9+
10+
jobs:
11+
build:
12+
permissions:
13+
contents: write
14+
pull-requests: read
15+
statuses: write
16+
runs-on: ubuntu-latest
17+
steps:
18+
- uses: actions/checkout@v4
19+
- uses: julia-actions/setup-julia@v2
20+
with:
21+
version: '1'
22+
- uses: julia-actions/cache@v1
23+
- name: Install dependencies
24+
run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
25+
- name: Build and deploy
26+
env:
27+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token
28+
run: julia --project=docs/ docs/make.jl

‎README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@ examples is different from the package itself.
9797

9898
### Plotting
9999

100-
![illustration](img/jetvis.png)
100+
![illustration](docs/src/assets/jetvis.png)
101101

102102
To visualise the clustered jets as a 3d bar plot (see illustration above) we now
103103
use `Makie.jl`. See the `jetsplot` function in `ext/JetVisualisation.jl` and its

‎docs/Project.toml

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
[deps]
2+
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
3+
JetReconstruction = "44e8cb2c-dfab-4825-9c70-d4808a591196"

‎docs/make.jl

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
using Documenter
2+
using JetReconstruction
3+
4+
makedocs(sitename = "JetReconstruction.jl")

‎img/illustration.jpeg renamed to ‎docs/src/assets/illustration.jpeg

File renamed without changes.

‎img/jetvis.png renamed to ‎docs/src/assets/jetvis.png

File renamed without changes.

‎docs/src/examples.md

+46
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Jet Reconstruction Examples
2+
3+
The Jet Reconstruction package has a number of example files that show how to
4+
usage.
5+
6+
*Note:* because of extra dependencies in these scripts, one must use the
7+
`Project.toml` file in the `examples` directory.
8+
9+
## `jetreco.jl`
10+
11+
This is a basic jet reconstruction example that shows how to call the package to
12+
perform a jet reconstruction, with different algorithms and (optionally)
13+
strategy, producing exclusive and inclusive jet selections.
14+
15+
```sh
16+
julia --project=. examples/jetreco.jl --maxevents=100 --strategy=N2Plain test/data/events.hepmc3
17+
...
18+
julia --project=. examples/jetreco.jl --maxevents=100 --strategy=N2Tiled test/data/events.hepmc3
19+
...
20+
```
21+
22+
There are options to explicitly set the algorithm (use `--help` to see these).
23+
24+
## `instrumented-jetreco.jl`
25+
26+
This is a more sophisticated example that allows performance measurements to be
27+
made of the reconstruction, as well as profiling (flamegraphs and memory
28+
profiling). Use the `--help` option to see usage. e.g., to extract timing
29+
performance for the AntiKt algorithm using the tiled strategy:
30+
31+
```sh
32+
julia --project instrumented-jetreco.jl -S N2Tiled -A AntiKt --nsamples 100 ../test/data/events.hepmc3
33+
```
34+
35+
## `visualise-jets.jl`
36+
37+
This script will produce a PNG/PDF showing the results of a jet reconstruction.
38+
This is a 3D plot where all the initial energy deposits are visualised, with
39+
colours that indicate in which final cluster the deposit ended up in.
40+
41+
## `visualise-jets.ipynb`
42+
43+
Similar to `visualise-jets.jl` this notebook will produce a visualisation of jet
44+
reconstruction in the browser. This is a 3D plot where all the initial energy
45+
deposits are visualised, with colours that indicate in which final cluster the
46+
deposit ended up in.

‎docs/src/index.md

+146
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# Jet Reconstruction
2+
3+
This package implements sequential Jet Reconstruction (clustering) algorithms,
4+
which are used in high-energy physics as part of event reconstruction for $pp$
5+
and $e^+e^-$ colliders.
6+
7+
## Algorithms
8+
9+
Algorithms used are based on the C++ FastJet package (<https://fastjet.fr>,
10+
[hep-ph/0512210](https://arxiv.org/abs/hep-ph/0512210),
11+
[arXiv:1111.6097](https://arxiv.org/abs/1111.6097)), reimplemented natively in
12+
Julia.
13+
14+
The algorithms include ``\text{anti}-{k}_\text{T}``, Cambridge/Aachen and
15+
inclusive ``k_\text{T}``.
16+
17+
## Reconstruction Interface
18+
19+
The main interface for reconstruction is:
20+
21+
```@docs
22+
jet_reconstruct(particles; p = -1, R = 1.0, recombine = +, strategy = RecoStrategy.Best)
23+
```
24+
25+
The object returned is a `ClusterSequence`, which internally tracks all merge steps.
26+
27+
```@docs
28+
ClusterSequence
29+
```
30+
31+
## Strategy
32+
33+
Three strategies are available for the different algorithms:
34+
35+
| Strategy Name | Notes | Interface |
36+
|---|---|---|
37+
| `RecoStrategy.Best` | Dynamically switch strategy based on input particle density | `jet_reconstruct` |
38+
| `RecoStrategy.N2Plain` | Global matching of particles at each interation (works well for low $N$) | `plain_jet_reconstruct` |
39+
| `RecoStrategy.N2Tiled` | Use tiles of radius $R$ to limit search space (works well for higher $N$) | `tiled_jet_reconstruct` |
40+
41+
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.
42+
43+
Another option, if one wishes to use a specific strategy, is to call that strategy's interface directly, e.g.,
44+
45+
```julia
46+
# For N2Plain strategy called directly
47+
plain_jet_reconstruct(particles::Vector{T}; p = -1, R = 1.0, recombine = +)
48+
```
49+
50+
Note that there is no `strategy` option in these interfaces.
51+
52+
## Inclusive and Exclusive Selections
53+
54+
To obtain final jets both inclusive (``p_T`` cut) and exclusive (``n_{jets}`` or
55+
``d_{ij}`` cut) selections are supported:
56+
57+
```@docs
58+
inclusive_jets(clusterseq::ClusterSequence, ptmin = 0.0)
59+
```
60+
61+
```@docs
62+
exclusive_jets(clusterseq::ClusterSequence; dcut = nothing, njets = nothing)
63+
```
64+
65+
The number of exclusive jets passing a particular `dcut` can be obtained:
66+
67+
```@docs
68+
n_exclusive_jets(clusterseq::ClusterSequence; dcut::AbstractFloat)
69+
```
70+
71+
### Sorting
72+
73+
Sorting vectors is trivial in Julia, no special sorting methods are provided. As
74+
an example, to sort exclusive jets of ``>5.0`` (usually GeV, depending on your
75+
EDM) from highest energy to lowest:
76+
77+
```julia
78+
sorted_jets = sort!(inclusive_jets(cs::ClusterSequence; ptmin=5.0),
79+
by=JetReconstruction.energy, rev=true)
80+
```
81+
82+
## Plotting
83+
84+
![illustration](assets/jetvis.png)
85+
86+
To visualise the clustered jets as a 3d bar plot (see illustration above) we now
87+
use `Makie.jl`. See the `jetsplot` function in `ext/JetVisualisation.jl` and its
88+
documentation for more. There are two worked examples in the `examples`
89+
directory.
90+
91+
The plotting code is a package extension and will load if the one of the `Makie`
92+
modules is loaded in the environment.
93+
94+
## Serialisation
95+
96+
The package also provides methods such as `loadjets`, `loadjets!`, and
97+
`savejets` that one can use to save and load objects on/from disk easily in a
98+
very flexible format. See documentation for more.
99+
100+
## Reference
101+
102+
Although it has been developed further since the CHEP2023 conference, the CHEP
103+
conference proceedings,
104+
[10.1051/epjconf/202429505017](https://doi.org/10.1051/epjconf/202429505017),
105+
should be cited if you use this package:
106+
107+
```bibtex
108+
@article{refId0,
109+
author = {{Stewart, Graeme Andrew} and {Gras, Philippe} and {Hegner, Benedikt} and {Krasnopolski, Atell}},
110+
doi = {10.1051/epjconf/202429505017},
111+
journal = {EPJ Web of Conf.},
112+
pages = {05017},
113+
title = {Polyglot Jet Finding},
114+
url = {https://doi.org/10.1051/epjconf/202429505017},
115+
volume = 295,
116+
year = 2024,
117+
eprint={2309.17309},
118+
archivePrefix={arXiv},
119+
primaryClass={hep-ex}
120+
}
121+
```
122+
123+
The original paper on [arXiv](https://arxiv.org/abs/2309.17309) is:
124+
125+
```bibtex
126+
@misc{stewart2023polyglot,
127+
title={Polyglot Jet Finding},
128+
author={Graeme Andrew Stewart and Philippe Gras and Benedikt Hegner and Atell Krasnopolski},
129+
year={2023},
130+
eprint={2309.17309},
131+
archivePrefix={arXiv},
132+
primaryClass={hep-ex}
133+
}
134+
```
135+
136+
## Authors and Copyright
137+
138+
Code in this package is authored by:
139+
140+
- Atell Krasnopolski <[email protected]>
141+
- Graeme A Stewart <[email protected]>
142+
- Philippe Gras <[email protected]>
143+
144+
and is Copyright 2022-2024 The Authors, CERN.
145+
146+
The code is under the MIT License.

‎src/ClusterSequence.jl

+1-1
Original file line numberDiff line numberDiff line change
@@ -236,7 +236,7 @@ or a cut on the maximum distance parameter.
236236
**Note**: Either `dcut` or `njets` must be provided (but not both).
237237
238238
# Returns
239-
- `excl_jets::Array{LorentzVectorCyl}`: An array of `LorentzVectorCyl` objects representing the exclusive jets.
239+
- An array of `LorentzVectorCyl` objects representing the exclusive jets.
240240
241241
# Exceptions
242242
- `ArgumentError`: If neither `dcut` nor `njets` is provided.

‎src/GenericAlgo.jl

+23-5
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,35 @@
11
"""
22
jet_reconstruct(particles; p = -1, R = 1.0, recombine = +, strategy = RecoStrategy.Best)
33
4-
Reconstructs jets from a collection of particles using a specified algorithm and strategy
4+
Reconstructs jets from a collection of particles using a specified algorithm and
5+
strategy
56
67
# Arguments
7-
- `particles`: A collection of particles used for jet reconstruction.
8-
- `p=-1`: The power value used for the distance measure, which maps to a particular reconstruction algorithm (-1 = AntiKt, 0 = Cambridge/Aachen, 1 = Kt).
8+
- `particles`: A collection of particles used for jet reconstruction.
9+
- `p=-1`: The power value used for the distance measure for generalised k_T,
10+
which maps to a particular reconstruction algorithm (-1 = AntiKt, 0 =
11+
Cambridge/Aachen, 1 = Kt).
912
- `R=1.0`: The jet radius parameter.
1013
- `recombine=+`: The recombination scheme used for combining particles.
11-
- `strategy=RecoStrategy.Best`: The jet reconstruction strategy to use. `RecoStrategy.Best` makes a dynamic decision based on the number of starting particles.
14+
- `strategy=RecoStrategy.Best`: The jet reconstruction strategy to use.
15+
`RecoStrategy.Best` makes a dynamic decision based on the number of starting
16+
particles.
1217
1318
# Returns
14-
A cluster sequence object containing the reconstructed jets and the merging history.
19+
A cluster sequence object containing the reconstructed jets and the merging
20+
history.
21+
22+
# Details
23+
24+
## `particles` argument
25+
Any type that supplies the methods `pt2()`, `phi()`, `rapidity()`, `px()`,
26+
`py()`, `pz()`, `energy()` (in the `JetReconstruction` namespace) can be used.
27+
This includes `LorentzVector`, `LorentzVectorCyl`, and `PseudoJet`, for which
28+
these methods are already predefined in the `JetReconstruction` namespace.
29+
30+
## `recombine` argument
31+
The `recombine` argument is the function used to merge pairs of particles. The
32+
default is simply `+(jet1,jet2)`, i.e. 4-momenta addition or the *E*-scheme.
1533
1634
# Example
1735
```julia

‎src/JetReconstruction.jl

+1-1
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ export RecoStrategy, JetAlgorithm
4444

4545
# ClusterSequence type
4646
include("ClusterSequence.jl")
47-
export ClusterSequence, inclusive_jets, exclusive_jets
47+
export ClusterSequence, inclusive_jets, exclusive_jets, n_exclusive_jets
4848

4949
## N2Plain algorithm
5050
# Algorithmic part for simple sequential implementation

0 commit comments

Comments
 (0)