Document requirements for input jets' history indices (#174)

* fix typos

* add note about input history indices

* update notice to mention manualy created jets

* fix note

Co-authored-by: Graeme A Stewart <[email protected]>

* add message to history index assert

---------

Co-authored-by: Graeme A Stewart <[email protected]>

Author: m-fila

src/ClusterSequence.jl

@@ -92,7 +92,7 @@ function initial_history(particles)
 
         # get cross-referencing right from the Jets
         # particles[i]._cluster_hist_index = i
-        @assert cluster_hist_index(particles[i]) == i
+        @assert cluster_hist_index(particles[i])==i "Cluster history index should match jet's index in the input vector"
 
         # determine the total energy in the event
         Qtot += particles[i].E

src/EEJet.jl

@@ -51,7 +51,7 @@ end
 """
     EEJet(jet::Any; cluster_hist_index::Int = 0)
 
-Construct a PseudoJet from a generic object `jet` with the given cluster index.
+Construct a EEJet from a generic object `jet` with the given cluster index.
 This functions also for `LorentzVectorCyl` objects.
 
 # Details

src/GenericAlgo.jl

@@ -36,9 +36,14 @@ history.
 ## `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.
+This includes `LorentzVector`, `LorentzVectorCyl`, `PseudoJet` and `EEJet`,
+for which these methods are already predefined in the `JetReconstruction` namespace.
 
+**Note** when using `PseudoJet` or `EEJet`, the history indices (`_cluster_hist_index`)
+must be set correctly. For initial jets, this means assigning to each jet its index
+in the vector if you construct them manually. When using other jet types correct
+indices are set automatically internally.
+    
 ## `recombine` argument
 The `recombine` argument is the function used to merge pairs of particles. The
 default is `addjets`, which uses 4-momenta addition (a.k.a. the E-scheme).

src/PlainAlgo.jl

@@ -27,7 +27,7 @@ end
 Compute the dij value for a given index `i` to its nearest neighbor. The nearest
 neighbor is determined from `nn[i]`, and the metric distance to the nearest
 neighbor is given by the distance `nndist[i]` applying the lower of the
-`kt2_array` values for the two particles.ßß
+`kt2_array` values for the two particles.
 
 # Arguments
 - `i`: The index of the element.
@@ -198,7 +198,7 @@ Perform pp jet reconstruction using the plain algorithm.
 - `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.
+   used for each element.
 - `algorithm::JetAlgorithm.Algorithm`: The jet algorithm to use.
 - `p::Union{Real, Nothing} = nothing`: The power value used for jet reconstruction.
    Must be specified for GenKt algorithm. Other algorithms will ignore this value.

src/TiledAlgoLL.jl

@@ -302,7 +302,7 @@ If both are given they must be consistent or an exception is thrown.
 ## Arguments
 - `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)
+  JetReconstruction namespace).
 - `algorithm::JetAlgorithm.Algorithm`: The jet algorithm to use.
 - `p::Union{Real, Nothing} = nothing`: The power value used for jet reconstruction.
   Must be specified for GenKt algorithm. Other algorithms will ignore this value.