Improved examples and dependencies (#48)

* Tidy up info messages

Exclusive jet messages should be debug

Format Pseudojet.jl

* Rename Cambridge algorithm to CA

Give Aachen their due!

* Simplified example

Remove the machinery for timing and profiling
in order to have a simpler example

* Rename example codes to be clearer

Simple example is now just called jetreco.jl

Example with timing and profiling is called instrumented-jetreco.jl

* Change message level

An info message should be debug

* Switch from power to algorithm

Power as a proxy for algorithm only works for pp reconstruction algorithms
As the intention is to add ee algorithms too, then move to using
algorithm name as the steering parameter

* Basic jet visualisation example

Read an event from a HepMC3 file, reconstruct and then visualise it
(save to file)

Fixes to JetViz.jl to allow it to be used more easily from example
scripts by specifying JetReconstruction module and using namespace

* Fix event selector and allow output file to be named

Fix the event selector to the odd way that the HepMC3 reader works
(to be changed!)

Allow output file to be specified

* Restructure dependencies

Remove all extra dependencies from main package
Move JetVisualisation code to an extension (weak depends on CairoMakie)
Add separate Project.toml for examples, with extra packages

* Used shared try_parse include

All the example scripts need this to change CLI options to
strategy and algorithm enums

* Add README for examples

Finesse the weak dependency to be Makie
rather than a specific backend (CairoMakie, GLMakie, etc.)

Ignore graphics outputs in the example directory

* Add visualisation example notebook

Uses WGLMakie to render in the browser

* Update documentation

* Trim whitespace around figure

* Minor README update

* Version updates

Add version numbers for all dependencies
Bump minimum Julia to 1.9 (needed for package extensions)
Tweak LICENSE file authors and year

* Fix LaTeX markup

Use $` `$ as the underscores mess things up otherwise

Author: graeme-a-stewart

.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.