Update input particles to be AbstractVector (#150)

* Update input particles to be AbstractVector

Take an AbstractVector for the algorithm entry points, which allows EDM4hep data
to be used correctly again.

(cherry picked from commit b935be9)

* Allow AbstractVector for backend algorithms

To avoid the situation where the input particle collection is
copied from an AbstractVector, relax the stipulation
that the algorithm imlemenation must be a Vector.

For consistency, the main user entry point, jet_reconstruct()
also should take an AbstractVector as input.

(cherry picked from commit f8ad488)

Author: graeme-a-stewart

src/EEAlgorithm.jl

@@ -191,14 +191,14 @@ Copy the contents of slot `i` in the `eereco` array to slot `j`.
 end
 
 """
-    ee_genkt_algorithm(particles::Vector{T}; p = -1, R = 4.0,
+    ee_genkt_algorithm(particles::AbstractVector{T}; p = -1, R = 4.0,
                        algorithm::JetAlgorithm.Algorithm = JetAlgorithm.Durham,
                        recombine = +) where {T}
 
 Run an e+e- reconstruction algorithm on a set of initial particles.
 
 # Arguments
-- `particles::Vector{T}`: A vector of particles to be clustered.
+- `particles::AbstractVector{T}`: A vector of particles to be clustered.
 - `p = 1`: The power parameter for the algorithm. Not required / ignored for
   the Durham algorithm when it is set to 1.
 - `R = 4.0`: The jet radius parameter. Not required / ignored for the Durham
@@ -221,7 +221,7 @@ If the algorithm is Durham, `p` is set to 1 and `R` is nominally set to 4.
 Note that unlike `pp` reconstruction the algorithm has to be specified
 explicitly.
 """
-function ee_genkt_algorithm(particles::Vector{T}; p = 1,
+function ee_genkt_algorithm(particles::AbstractVector{T}; p = 1,
                             algorithm::JetAlgorithm.Algorithm = JetAlgorithm.Durham,
                             R = 4.0, recombine = +) where {T}
 
@@ -258,13 +258,13 @@ function ee_genkt_algorithm(particles::Vector{T}; p = 1,
 end
 
 """
-    _ee_genkt_algorithm(; particles::Vector{EEJet}, p = 1, R = 4.0,
+    _ee_genkt_algorithm(; particles::AbstractVector{EEJet}, p = 1, R = 4.0,
                        algorithm::JetAlgorithm.Algorithm = JetAlgorithm.Durham,
                        recombine = +)
 
 This function is the actual implementation of the e+e- jet clustering algorithm.
 """
-function _ee_genkt_algorithm(; particles::Vector{EEJet}, p = 1, R = 4.0,
+function _ee_genkt_algorithm(; particles::AbstractVector{EEJet}, p = 1, R = 4.0,
                              algorithm::JetAlgorithm.Algorithm = JetAlgorithm.Durham,
                              recombine = +)
     # Bounds

src/GenericAlgo.jl

@@ -1,5 +1,5 @@
 """
-    jet_reconstruct(particles; p::Union{Real, Nothing} = nothing,
+    jet_reconstruct(particles::AbstractVector; p::Union{Real, Nothing} = nothing,
                          algorithm::Union{JetAlgorithm.Algorithm, Nothing} = nothing,
                          R = 1.0, recombine = +,
                          strategy::RecoStrategy.Strategy = RecoStrategy.Best)
@@ -8,10 +8,11 @@ Reconstructs jets from a collection of particles using a specified algorithm and
 strategy.
 
 # Arguments
-- `particles`: A collection of particles used for jet reconstruction. 
-- `p::Union{Real, Nothing} = nothing`: 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).
+- `particles::AbstractVector`: A collection of particles used for jet
+  reconstruction. 
+- `p::Union{Real, Nothing} = nothing`: 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).
 - `algorithm::Union{JetAlgorithm.Algorithm, Nothing} = nothing`: The algorithm
   to use for jet reconstruction.
 - `R = 1.0`: The jet radius parameter.
@@ -20,7 +21,8 @@ strategy.
    strategy to use. `RecoStrategy.Best` makes a dynamic decision based on the
    number of starting particles.
 
-Note that one of `p` or `algorithm` must be specified, with `algorithm` preferred.
+Note that one of `p` or `algorithm` must be specified, with `algorithm`
+preferred.
 
 # Returns
 A cluster sequence object containing the reconstructed jets and the merging
@@ -44,8 +46,8 @@ it or `nothing`. If the algorithm is one where `p` can vary, then it has to be
 given, along with the algorithm.
 
 If the `p` parameter is passed and `algorithm=nothing`, then pp-type
-reconstruction is implied (i.e., AntiKt, CA, Kt or GenKt will be used,
-depending on the value of `p`).
+reconstruction is implied (i.e., AntiKt, CA, Kt or GenKt will be used, depending
+on the value of `p`).
 
 When an algorithm has no `R` dependence the `R` parameter is ignored.
 
@@ -57,7 +59,7 @@ jet_reconstruct(particles; algorithm = JetAlgorithm.Durham)
 jet_reconstruct(particles; algorithm = JetAlgorithm.GenKt, p = 0.5, R = 1.0)
 ```
 """
-function jet_reconstruct(particles; p::Union{Real, Nothing} = nothing,
+function jet_reconstruct(particles::AbstractVector; p::Union{Real, Nothing} = nothing,
                          algorithm::Union{JetAlgorithm.Algorithm, Nothing} = nothing,
                          R = 1.0, recombine = +,
                          strategy::RecoStrategy.Strategy = RecoStrategy.Best)

src/PlainAlgo.jl

@@ -187,16 +187,17 @@ Base.@propagate_inbounds function upd_nn_step!(i, j, k, N, Nn, kt2_array, rapidi
 end
 
 """
-    plain_jet_reconstruct(particles::Vector{T}; p::Union{Real, Nothing} = -1,
+    plain_jet_reconstruct(particles::AbstractVector{T}; p::Union{Real, Nothing} = -1,
                                algorithm::Union{JetAlgorithm.Algorithm, Nothing} = nothing,
                                R = 1.0, recombine = +) where {T}
 
 Perform pp jet reconstruction using the plain algorithm.
 
 # Arguments
-- `particles::Vector{T}`: A vector of particles used for jet reconstruction, any
-   array of particles, which supports suitable 4-vector methods, viz. pt2(),
-   phi(), rapidity(), px(), py(), pz(), energy(), can be used. for each element.
+- `particles::AbstractVector{T}`: A vector of particles used for jet
+   reconstruction, any array of particles, which supports suitable 4-vector
+   methods, viz. pt2(), phi(), rapidity(), px(), py(), pz(), energy(), can be
+   used. for each element.
 - `p::Union{Real, Nothing} = -1`: The power value used for jet reconstruction.
 - `algorithm::Union{JetAlgorithm, Nothing} = nothing`: The explicit jet
   algorithm to use.
@@ -207,7 +208,8 @@ Perform pp jet reconstruction using the plain algorithm.
 **Note** for the `particles` argument, the 4-vector methods need to exist in the
 JetReconstruction package namespace.
 
-This code will use the `k_t` algorithm types, operating in `(rapidity, φ)` space.
+This code will use the `k_t` algorithm types, operating in `(rapidity, φ)`
+space.
 
 It is not necessary to specify both the `algorithm` and the `p` (power) value.
 If both are given they must be consistent or an exception is thrown.
@@ -221,7 +223,7 @@ jets = plain_jet_reconstruct(particles; p = -1, R = 0.4)
 jets = plain_jet_reconstruct(particles; algorithm = JetAlgorithm.Kt, R = 1.0)
 ```
 """
-function plain_jet_reconstruct(particles::Vector{T}; p::Union{Real, Nothing} = -1,
+function plain_jet_reconstruct(particles::AbstractVector{T}; p::Union{Real, Nothing} = -1,
                                algorithm::Union{JetAlgorithm.Algorithm, Nothing} = nothing,
                                R = 1.0, recombine = +) where {T}
 
@@ -253,7 +255,7 @@ function plain_jet_reconstruct(particles::Vector{T}; p::Union{Real, Nothing} = -
 end
 
 """
-    _plain_jet_reconstruct(; particles::Vector{PseudoJet}, p = -1, 
+    _plain_jet_reconstruct(; particles::AbstractVector{PseudoJet}, p = -1, 
                                 algorithm::JetAlgorithm.Algorithm = JetAlgorithm.AntiKt,
                                 R = 1.0, recombine = +)
 
@@ -284,7 +286,7 @@ power parameter.
 - `clusterseq`: The resulting `ClusterSequence` object representing the
   reconstructed jets.
 """
-function _plain_jet_reconstruct(; particles::Vector{PseudoJet}, p = -1,
+function _plain_jet_reconstruct(; particles::AbstractVector{PseudoJet}, p = -1,
                                 algorithm::JetAlgorithm.Algorithm = JetAlgorithm.AntiKt,
                                 R = 1.0, recombine = +)
     # Bounds

src/TiledAlgoLL.jl

@@ -330,7 +330,7 @@ function find_tile_neighbours!(tile_union, jetA, jetB, oldB, tiling)
 end
 
 """
-    tiled_jet_reconstruct(particles::Vector{T}; p::Union{Real, Nothing} = -1,
+    tiled_jet_reconstruct(particles::AbstractVector{T}; p::Union{Real, Nothing} = -1,
                                algorithm::Union{JetAlgorithm.Algorithm, Nothing} = nothing,
                                R = 1.0, recombine = +) where {T}
 
@@ -347,13 +347,13 @@ It is not necessary to specify both the `algorithm` and the `p` (power) value.
 If both are given they must be consistent or an exception is thrown.
 
 ## Arguments
-- `particles::Vector{T}`: A vector of particles used as input for jet
+- `particles::AbstractVector{T}`: A vector of particles used as input for jet
   reconstruction. T must support methods px, py, pz and energy (defined in the
   JetReconstruction namespace)
 - `p::Union{Real, Nothing} = -1`: The power parameter for the jet reconstruction
   algorithm, thus switching between different algorithms.
-- `algorithm::Union{JetAlgorithm.Algorithm, Nothing} = nothing`: The explicit jet
-  algorithm to use.
+- `algorithm::Union{JetAlgorithm.Algorithm, Nothing} = nothing`: The explicit
+  jet algorithm to use.
 - `R::Float64 = 1.0`: The jet radius parameter for the jet reconstruction
   algorithm.
 - `recombine::Function = +`: The recombination function used for combining
@@ -367,7 +367,7 @@ If both are given they must be consistent or an exception is thrown.
 tiled_jet_reconstruct(particles::Vector{LorentzVectorHEP}; p = -1, R = 0.4, recombine = +)
 ```
 """
-function tiled_jet_reconstruct(particles::Vector{T}; p::Union{Real, Nothing} = -1,
+function tiled_jet_reconstruct(particles::AbstractVector{T}; p::Union{Real, Nothing} = -1,
                                algorithm::Union{JetAlgorithm.Algorithm, Nothing} = nothing,
                                R = 1.0, recombine = +) where {T}
 
@@ -399,7 +399,7 @@ Main jet reconstruction algorithm, using PseudoJet objects
 """
 
 """
-    _tiled_jet_reconstruct(particles::Vector{PseudoJet}; p::Real = -1,
+    _tiled_jet_reconstruct(particles::AbstractVector{PseudoJet}; p::Real = -1,
                                 algorithm::JetAlgorithm.Algorithm = JetAlgorithm.AntiKt,
                                 R = 1.0, recombine = +)
 
@@ -408,7 +408,7 @@ of data types are done. The algorithm parameter must be consistent with the
 power parameter.
 
 ## Arguments
-- `particles::Vector{PseudoJet}`: A vector of `PseudoJet` particles used as input for jet
+- `particles::AbstractVector{PseudoJet}`: A vector of `PseudoJet` particles used as input for jet
   reconstruction.
 - `p::Real = -1`: The power parameter for the jet reconstruction algorithm, thus
   switching between different algorithms.
@@ -427,7 +427,7 @@ power parameter.
 tiled_jet_reconstruct(particles::Vector{PseudoJet}; p = 1, R = 1.0, recombine = +)
 ```
 """
-function _tiled_jet_reconstruct(particles::Vector{PseudoJet}; p::Real = -1,
+function _tiled_jet_reconstruct(particles::AbstractVector{PseudoJet}; p::Real = -1,
                                 algorithm::JetAlgorithm.Algorithm = JetAlgorithm.AntiKt,
                                 R = 1.0, recombine = +)
     # Bounds