Add support for EDM4hep inputs (#80)

* Jet class constructors from Real

The jet class constructors (EEjet, Pseudojet) were typed to Float64, which is too narrow.
Now retype to Real (which in particular allows passing in Float32s).

* Add EDM4hep extensions

Accessors px, py, pz, energy for EDM4hep reconstructed particles
Allow direct construction of internal jet structs from a reco particle

This extension only activated if EDM4hep is loaded in the environment

* Add example of reconstruction from EDM4hep

Simple example of how to run jet reconstruction from an EDM4hep input file

* Change input particle type to 1D AbstractArray

There is no need that the input particles be explicitly a vector, in fact
from EDM4hep files one gets a StructArrays.StructVector, which is a subtype
of AbstractArray.

This allows jet reconstruction directly from the ReconstructedParticles object
of EDM4hep, without needing to copy the data into another container.

* Add a REPL friendly EDM4hep testing script

* Update documentation for EDM4hep

* Allow 0.20 versions of Makie

Overcomes compatibility issues with EDM4hep via FHist

* Rework documentation

Remove Vitepress formatting from documentation as it is impossible to preview
correctly locally (even with suggested work arounds).

Add documentation to the EDM4hep extension file.

* Update compatibility requirements

Author: graeme-a-stewart

.github/workflows/Documentation.yml

@@ -19,7 +19,7 @@ jobs:
       - uses: julia-actions/setup-julia@v2
         with:
           version: '1'
-      - uses: julia-actions/cache@v1
+      - uses: julia-actions/cache@v2
       - name: Install dependencies
         run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
       - name: Build and deploy

Project.toml

@@ -17,19 +17,22 @@ StructArrays = "09ab397b-f2b6-538f-b94a-2f83cf4a842a"
 
 [weakdeps]
 Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
+EDM4hep = "eb32b910-dde9-4347-8fce-cd6be3498f0c"
 
 [extensions]
 JetVisualisation = "Makie"
+EDM4hepJets = "EDM4hep"
 
 [compat]
 Accessors = "0.1.36"
 CodecZlib = "0.7.4"
+EDM4hep = "0.4.0"
 EnumX = "1.0.4"
 JSON = "0.21.4"
 LoopVectorization = "0.12.170"
 LorentzVectorHEP = "0.1.6"
 LorentzVectors = "0.4.3"
-Makie = "0.21"
+Makie = "0.20, 0.21"
 MuladdMacro = "0.2.4"
 StructArrays = "0.6.18"
 julia = "1.9"

README.md

@@ -22,13 +22,13 @@ algorithm and generalised $`k_\text{T}`$ for $`e^+e^-`$.
 The simplest interface is to call:
 
 ```julia
-cs = jet_reconstruct(particles::Vector{T}; algorithm = JetAlgorithm.AntiKt, R = 1.0, [p = -1,] [recombine = +,] [strategy = RecoStrategy.Best])
+cs = jet_reconstruct(particles::AbstractArray{T, 1}; algorithm = JetAlgorithm.AntiKt, R = 1.0, [p = -1,] [recombine = +,] [strategy = RecoStrategy.Best])
 ```
 
-- `particles` - a vector of input particles for the clustering
+- `particles` - a one dimensional array (vector) of input particles for the clustering
   - Any type that supplies the methods `pt2()`, `phi()`, `rapidity()`, `px()`, `py()`, `pz()`, `energy()` can be used
   - These methods have to be defined in the namespace of this package, i.e., `JetReconstruction.pt2(::T)`
-  - The `PseudoJet` type from this package, or a 4-vector from `LorentzVectorHEP` are suitable (and have the appropriate definitions)
+  - The `PseudoJet` or `EEjet` types from this package, a 4-vector from `LorentzVectorHEP`, or a `ReconstructedParticle` from [EDM4hep](https://github.com/peremato/EDM4hep.jl) are suitable (and have the appropriate definitions)
 - `algorithm` is the name of the jet algorithm to be used (from the `JetAlgorithm` enum)
   - `JetAlgorithm.AntiKt` anti-$`{k}_\text{T}`$ clustering (default)
   - `JetAlgorithm.CA` Cambridge/Aachen clustering
@@ -59,7 +59,7 @@ To obtain the final inclusive jets, use the `inclusive_jets` method:
 final_jets = inclusive_jets(cs::ClusterSequence; ptmin=0.0)
 ```
 
-Only jets passing the cut $p_T > p_{Tmin}$ will be returned. The result is returned as a `Vector{LorentzVectorHEP}`.
+Only jets passing the cut $p_T > p_{Tmin}$ will be returned. The result is returned as a `Vector{LorentzVectorHEP}`, but different return types can be specified (e.g., `T = EEjet`).
 
 #### Sorting
 

docs/Project.toml

@@ -1,9 +1,12 @@
 [deps]
 CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
-DocumenterVitepress = "4710194d-e776-4893-9690-8d956a29c365"
+EDM4hep = "eb32b910-dde9-4347-8fce-cd6be3498f0c"
 JetReconstruction = "44e8cb2c-dfab-4825-9c70-d4808a591196"
+LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"
 Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
 
 [compat]
 Documenter = "1.4"
+EDM4hep = "0.4"
+Makie = "0.20, 0.21"

docs/make.jl

@@ -1,20 +1,22 @@
 using Documenter
-using DocumenterVitepress
 using CairoMakie
+using EDM4hep
 using JetReconstruction
 
 push!(LOAD_PATH, "../ext/")
 
 include(joinpath(@__DIR__, "..", "ext", "JetVisualisation.jl"))
+include(joinpath(@__DIR__, "..", "ext", "EDM4hepJets.jl"))
 
 makedocs(sitename = "JetReconstruction.jl",
-         format = MarkdownVitepress(repo = "github.com/JuliaHEP/JetReconstruction.jl"),
+         clean = false,
          pages = [
              "Home" => "index.md",
              "Examples" => "examples.md",
+             "EDM4hep" => "EDM4hep.md",
+             "Visualisation" => "visualisation.md",
              "Reference" => Any["Public API" => "lib/public.md",
-                                "Internal API" => "lib/internal.md",
-                                "Visualisation API" => "lib/visualisation.md"]
+                                "Internal API" => "lib/internal.md"]
          ])
 
 deploydocs(repo = "github.com/JuliaHEP/JetReconstruction.jl.git",

docs/src/EDM4hep.md

@@ -0,0 +1,16 @@
+# EDM4hep
+
+Extension functionality to read EDM4hep ReconstructedParticles
+
+## Index
+
+```@index
+Pages = ["EDM4hep.md"]
+```
+
+## EDM4hep Interfaces
+
+```@autodocs
+Modules = [EDM4hepJets]
+Order = [:function]
+```

docs/src/examples.md

@@ -6,7 +6,9 @@ usage.
 *Note:* because of extra dependencies in these scripts, one must use the
 `Project.toml` file in the `examples` directory.
 
-## `jetreco.jl`
+## Standalone Examples
+
+### `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)
@@ -23,7 +25,7 @@ julia --project=examples examples/jetreco.jl --maxevents=10 --strategy=N2Plain -
 
 There are options to explicitly set the algorithm (use `--help` to see these).
 
-## `instrumented-jetreco.jl`
+### `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
@@ -34,20 +36,26 @@ performance for the AntiKt algorithm using the tiled strategy:
 julia --project instrumented-jetreco.jl -S N2Tiled -A AntiKt --nsamples 100 ../test/data/events.hepmc3
 ```
 
-## `visualise-jets.jl`
+### `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`
+### `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.
 
-## `animate-reconstruction.jl`
+### `animate-reconstruction.jl`
 
 Performs jet reconstruction and then produces and animation of the process,
 showing how the jets merge from their different constituents.
+
+## EDM4hep
+
+The `examples/EDM4hep` folder contains examples of using EDM4hep reconstructed
+particles as input to jet reconstruction. See the specific `README.md` file in
+that directory.

docs/src/index.md

@@ -1,29 +1,8 @@
-```@raw html
----
-layout: home
-
-hero:
-  name: "JetReconstruction.jl"
-  tagline:  "Jet reconstruction (reclustering) with Julia"
-  image:
-    src: /logo.png
-    alt: DocumenterVitepress
-  actions:
-    - theme: brand
-      text: Examples
-      link: /examples
-    - theme: alt
-      text: Public APIs
-      link: /lib/public
-
----
-```
-
 # 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.
+which are used in high-energy physics as part of event reconstruction for ``pp``
+and ``e^+e^-`` colliders.
 
 ## Algorithms
 
@@ -59,6 +38,31 @@ the `R` value is ignored.
 The object returned is a [`ClusterSequence`](@ref), which internally tracks all
 merge steps.
 
+### Input Particle Types
+
+For the `particles` input to the reconstruction any one dimensional
+`AbstractArray{T, 1}` can be used, where the type `T` has to implement methods
+to extract the 4-vector components, viz, the following are required:
+
+- `JetReconstuction.px(particle::T)`
+- `JetReconstuction.py(particle::T)`
+- `JetReconstuction.pz(particle::T)`
+- `JetReconstuction.energy(particle::T)`
+
+Currently built-in supported types are
+[`LorentzVectorHEP`](https://github.com/JuliaHEP/LorentzVectorHEP.jl), the
+`PseudoJet` and `EEjet`s from this package, and `ReconstructedParticles` from
+[EDM4hep](https://github.com/peremato/EDM4hep.jl).
+
+If you require support for a different input collection type then ensure you
+define the `px()`, etc. methods *for your specific type* and *in the
+`JetReconstruction` package*. This use of what might be considered type piracy
+is blessed as long as you are en *end user* of the jet reconstruction package.
+
+If your type is used in several places or by different users, please consider
+writing a package extension that will support your type, following the model for
+EDM4hep in `ext/EDM4hepJets.jl`.
+
 ### Algorithm Types
 
 Each known algorithm is referenced using a `JetAlgorithm` scoped enum value.
@@ -80,8 +84,8 @@ given instead of the algorithm name. However, this should be considered
 
 ## Strategy
 
-Three strategies are available for the different algorithms, which can be
-specified by passing the named argument `strategy=...`.
+For the ``pp`` algorithms three strategies are available for the different
+algorithms, which can be specified by passing the named argument `strategy=...`.
 
 | Strategy Name | Notes | Interface |
 |---|---|---|
@@ -93,15 +97,8 @@ 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}; algorithm = JetAlgorithm.AntiKt, R = 1.0, recombine = +)
-```
-
-(There is no `strategy` option in these interfaces.)
+For ``e^+e^-`` algorithms particle densities are low, so the only implementation
+is of the same type as `N2Plain`.
 
 ## Inclusive and Exclusive Selections
 

docs/src/lib/internal.md

@@ -14,7 +14,7 @@ CollapsedDocStrings = true
 Pages = ["internal.md"]
 ```
 
-## Public Interface
+## Internal Methods and Types
 
 ```@autodocs
 Modules = [JetReconstruction]