From 20ef2c65b3fc0c96bc929f3ea9ee5a44437d434e Mon Sep 17 00:00:00 2001 From: Graeme A Stewart Date: Thu, 13 Jun 2024 15:55:37 +0200 Subject: [PATCH] Refine documentation Add more details on the main interface Split examples into their own section --- docs/make.jl | 1 - docs/src/examples.md | 46 ++++++++++++++++++++++++++++++++++++++++++++ docs/src/index.md | 30 +++-------------------------- src/GenericAlgo.jl | 14 +++++++++++++- 4 files changed, 62 insertions(+), 29 deletions(-) create mode 100644 docs/src/examples.md diff --git a/docs/make.jl b/docs/make.jl index 724425f..227bfdb 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,5 +1,4 @@ using Documenter using JetReconstruction -# makedocs(sitename="JetReconstruction.jl", modules = [JetReconstruction]) makedocs(sitename = "JetReconstruction.jl") diff --git a/docs/src/examples.md b/docs/src/examples.md new file mode 100644 index 0000000..b417f0d --- /dev/null +++ b/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. diff --git a/docs/src/index.md b/docs/src/index.md index c0b9dc8..4d61247 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -1,4 +1,4 @@ -# JetReconstruction.jl +# Jet Reconstruction This package implements sequential Jet Reconstruction (clustering) algorithms, which are used in high-energy physics as part of event reconstruction for $pp$ @@ -11,7 +11,7 @@ Algorithms used are based on the C++ FastJet package (, [arXiv:1111.6097](https://arxiv.org/abs/1111.6097)), reimplemented natively in Julia. -The algorithms include anti-``{k}_\text{T}``, Cambridge/Aachen and inclusive ``k_\text{T}``. +The algorithms include ``\text{anti}-{k}_\text{T}``, Cambridge/Aachen and inclusive ``k_\text{T}``. ## Reconstruction Interface @@ -78,30 +78,6 @@ sorted_jets = sort!(inclusive_jets(cs::ClusterSequence; ptmin=5.0), by=JetReconstruction.energy, rev=true) ``` -## Examples - -In the examples directory there are a number of example scripts. - -See the `jetreco.jl` script for an example of how to call jet reconstruction. - -```sh -julia --project=. examples/jetreco.jl --maxevents=100 --nsamples=1 --strategy=N2Plain test/data/events.hepmc3 -... -julia --project=. examples/jetreco.jl --maxevents=100 --nsamples=1 --strategy=N2Tiled test/data/events.hepmc3 -... -``` - -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 ![illustration](assets/jetvis.png) @@ -143,7 +119,7 @@ should be cited if you use this package: } ``` -The original paper on arXiv is: +The original paper on [arXiv](https://arxiv.org/abs/2309.17309) is: ```bibtex @misc{stewart2023polyglot, diff --git a/src/GenericAlgo.jl b/src/GenericAlgo.jl index e5e4823..6e2a392 100644 --- a/src/GenericAlgo.jl +++ b/src/GenericAlgo.jl @@ -5,7 +5,7 @@ Reconstructs jets from a collection of particles using a specified algorithm and strategy # Arguments -- `particles`: A collection of particles used for jet reconstruction. +- `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). @@ -19,6 +19,18 @@ strategy 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 jet_reconstruct(particles; p = -1, R = 0.4)