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

.github/workflows/Documentation.yml

@@ -0,0 +1,28 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+    tags: '*'
+  pull_request:
+
+jobs:
+  build:
+    permissions:
+      contents: write
+      pull-requests: read
+      statuses: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: '1'
+      - uses: julia-actions/cache@v1
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token
+        run: julia --project=docs/ docs/make.jl

README.md

@@ -97,7 +97,7 @@ examples is different from the package itself.
 
 ### Plotting
 
-![illustration](img/jetvis.png)
+![illustration](docs/src/assets/jetvis.png)
 
 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

docs/Project.toml

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

docs/make.jl

@@ -0,0 +1,4 @@
+using Documenter
+using JetReconstruction
+
+makedocs(sitename = "JetReconstruction.jl")

docs/src/examples.md

@@ -0,0 +1,46 @@
+# Jet Reconstruction Examples
+
+The Jet Reconstruction package has a number of example files that show how to
+usage.
+
+*Note:* because of extra dependencies in these scripts, one must use the
+`Project.toml` file in the `examples` directory.
+
+## `jetreco.jl`
+
+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.
+
+```sh
+julia --project=. examples/jetreco.jl --maxevents=100 --strategy=N2Plain test/data/events.hepmc3
+...
+julia --project=. examples/jetreco.jl --maxevents=100 --strategy=N2Tiled test/data/events.hepmc3
+...
+```
+
+There are options to explicitly set the algorithm (use `--help` to see these).
+
+## `instrumented-jetreco.jl`
+
+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
+```
+
+## `visualise-jets.jl`
+
+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.
+
+## `visualise-jets.ipynb`
+
+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.

docs/src/index.md

@@ -0,0 +1,146 @@
+# Jet Reconstruction
+
+This package implements sequential Jet Reconstruction (clustering) algorithms,
+which are used in high-energy physics as part of event reconstruction for $pp$
+and $e^+e^-$ colliders.
+
+## Algorithms
+
+Algorithms used are based on the C++ FastJet package (<https://fastjet.fr>,
+[hep-ph/0512210](https://arxiv.org/abs/hep-ph/0512210),
+[arXiv:1111.6097](https://arxiv.org/abs/1111.6097)), reimplemented natively in
+Julia.
+
+The algorithms include ``\text{anti}-{k}_\text{T}``, Cambridge/Aachen and
+inclusive ``k_\text{T}``.
+
+## Reconstruction Interface
+
+The main interface for reconstruction is:
+
+```@docs
+jet_reconstruct(particles; p = -1, R = 1.0, recombine = +, strategy = RecoStrategy.Best)
+```
+
+The object returned is a `ClusterSequence`, which internally tracks all merge steps.
+
+```@docs
+ClusterSequence
+```
+
+## 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 interation (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
+plain_jet_reconstruct(particles::Vector{T}; p = -1, R = 1.0, recombine = +)
+```
+
+Note that there is no `strategy` option in these interfaces.
+
+## Inclusive and Exclusive Selections
+
+To obtain final jets both inclusive (``p_T`` cut) and exclusive (``n_{jets}`` or
+``d_{ij}`` cut) selections are supported:
+
+```@docs
+inclusive_jets(clusterseq::ClusterSequence, ptmin = 0.0)
+```
+
+```@docs
+exclusive_jets(clusterseq::ClusterSequence; dcut = nothing, njets = nothing)
+```
+
+The number of exclusive jets passing a particular `dcut` can be obtained:
+
+```@docs
+n_exclusive_jets(clusterseq::ClusterSequence; dcut::AbstractFloat)
+```
+
+### Sorting
+
+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)
+```
+
+## Plotting
+
+![illustration](assets/jetvis.png)
+
+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.
+
+## Serialisation
+
+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.
+
+## Reference
+
+Although it has been developed further since the CHEP2023 conference, the CHEP
+conference proceedings,
+[10.1051/epjconf/202429505017](https://doi.org/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}
+}
+```
+
+The original paper on [arXiv](https://arxiv.org/abs/2309.17309) is:
+
+```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}
+}
+```
+
+## Authors and Copyright
+
+Code in this package is authored by:
+
+- Atell Krasnopolski <[email protected]>
+- Graeme A Stewart <[email protected]>
+- Philippe Gras <[email protected]>
+
+and is Copyright 2022-2024 The Authors, CERN.
+
+The code is under the MIT License.

src/ClusterSequence.jl

@@ -236,7 +236,7 @@ or a cut on the maximum distance parameter.
 **Note**: Either `dcut` or `njets` must be provided (but not both).
 
 # Returns
-- `excl_jets::Array{LorentzVectorCyl}`: An array of `LorentzVectorCyl` objects representing the exclusive jets.
+- An array of `LorentzVectorCyl` objects representing the exclusive jets.
 
 # Exceptions
 - `ArgumentError`: If neither `dcut` nor `njets` is provided.

src/GenericAlgo.jl

@@ -1,17 +1,35 @@
 """
     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
+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, which maps to a particular reconstruction algorithm (-1 = AntiKt, 0 = Cambridge/Aachen, 1 = Kt).
+- `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.
+- `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.
+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.
 
 # Example
 ```julia

src/JetReconstruction.jl

@@ -44,7 +44,7 @@ export RecoStrategy, JetAlgorithm
 
 # ClusterSequence type
 include("ClusterSequence.jl")
-export ClusterSequence, inclusive_jets, exclusive_jets
+export ClusterSequence, inclusive_jets, exclusive_jets, n_exclusive_jets
 
 ## N2Plain algorithm
 # Algorithmic part for simple sequential implementation