Improved examples and dependencies

.github/workflows/CI.yml

@@ -18,7 +18,7 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - '1.8'
+          - '1.9'
           - '1'
           - 'nightly'
         os:

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Atell Krasnopolski
+Copyright (c) 2022-2024 The Authors, CERN
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Project.toml

@@ -1,26 +1,31 @@
 name = "JetReconstruction"
 uuid = "44e8cb2c-dfab-4825-9c70-d4808a591196"
 authors = ["Atell Krasnopolski <[email protected]>", "Graeme A Stewart <[email protected]", "Philippe Gras <[email protected]>"]
-version = "0.2.0"
+version = "0.3.0"
 
 [deps]
 Accessors = "7d9f7c33-5ae7-4f3b-8dc6-eff91059b697"
-ArgParse = "c7e460c6-2fb9-53a9-8c5b-16f535851c63"
-Colors = "5ae59095-9a9b-59fe-a467-6f913c188581"
 EnumX = "4e289a0a-7415-4d19-859d-a7e5c4648b56"
-FlameGraphs = "08572546-2f56-4bcf-ba4e-bab62c3a3f89"
 JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
 Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
 LoopVectorization = "bdcacae8-1622-11e9-2a5c-532679323890"
 LorentzVectorHEP = "f612022c-142a-473f-8cfd-a09cf3793c6c"
 LorentzVectors = "3f54b04b-17fc-5cd4-9758-90c048d965e3"
-Profile = "9abbd945-dff8-562f-b5e8-e1ebf5ef1b79"
-ProfileSVG = "132c30aa-f267-4189-9183-c8a63c7e05e6"
-StatProfilerHTML = "a8a75453-ed82-57c9-9e16-4cd1196ecbf5"
+
+[weakdeps]
+Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
+
+[extensions]
+JetVisualisation = "Makie"
 
 [compat]
+Accessors = "0.1.36"
+EnumX = "1.0.4"
+JSON = "0.21.4"
+Makie = "0.21"
 LorentzVectorHEP = "0.1.6"
-julia = "1.8"
+LorentzVectors = "0.4.3"
+julia = "1.9"
 
 [extras]
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

README.md

@@ -10,7 +10,7 @@ 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 anti-${k}_\text{T}$, Cambridge/Aachen and inclusive $k_\text{T}$.
+The algorithms include anti-$`{k}_\text{T}`$, Cambridge/Aachen and inclusive $`k_\text{T}`$.
 
 ### Interface
 
@@ -71,9 +71,11 @@ plain_jet_reconstruct(particles::Vector{T}; p = -1, R = 1.0, recombine = +)
 
 Note that there is no `strategy` option in these interfaces.
 
-### Example
+### Examples
 
-See the `examples/jetreco.jl` script for a full example of how to call jet reconstruction.
+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
@@ -82,21 +84,40 @@ julia --project=. examples/jetreco.jl --maxevents=100 --nsamples=1 --strategy=N2
 ...
 ```
 
-The example also shows how to use `JetReconstruction.HepMC3` to read HepMC3 ASCII files (via the `read_final_state_particles()` wrapper).
+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](img/illustration.jpeg)
+![illustration](img/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.
 
-To visualise the clustered jets as a 3d bar plot (see illustration above) we now use `Makie.jl`. See the `jetsplot` function and its documentation for more. 
+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.
+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, [arXiv:2309.17309](https://arxiv.org/abs/2309.17309), should be cited if you use this package:
+Although it has been developed further since the CHEP2023 conference, the CHEP
+conference proceedings, [arXiv:2309.17309](https://arxiv.org/abs/2309.17309),
+should be cited if you use this package:
 
 ```bibtex
 @misc{stewart2023polyglot,

examples/.gitignore

@@ -0,0 +1,3 @@
+# Ignore visualisation outputs
+*.pdf
+*.png

examples/Project.toml

@@ -0,0 +1,12 @@
+[deps]
+ArgParse = "c7e460c6-2fb9-53a9-8c5b-16f535851c63"
+CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
+Colors = "5ae59095-9a9b-59fe-a467-6f913c188581"
+FlameGraphs = "08572546-2f56-4bcf-ba4e-bab62c3a3f89"
+JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
+JetReconstruction = "44e8cb2c-dfab-4825-9c70-d4808a591196"
+LorentzVectorHEP = "f612022c-142a-473f-8cfd-a09cf3793c6c"
+Profile = "9abbd945-dff8-562f-b5e8-e1ebf5ef1b79"
+ProfileSVG = "132c30aa-f267-4189-9183-c8a63c7e05e6"
+StatProfilerHTML = "a8a75453-ed82-57c9-9e16-4cd1196ecbf5"
+WGLMakie = "276b4fcb-3e11-5398-bf8b-a0c2d153d008"

examples/README.md

@@ -0,0 +1,31 @@
+# JetReconstruction.jl Examples
+
+This directory has a number of example files that show how to used the
+`JetReconstruction.jl` package.
+
+Because of extra dependencies in these scripts, one must use the `Project.toml`
+file in this 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.
+
+## `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).
+
+## `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`
+
+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.