From 3aac9cd53b7be36b6695654d91297e40c061a664 Mon Sep 17 00:00:00 2001 From: Graeme A Stewart Date: Tue, 8 Oct 2024 18:03:53 +0200 Subject: [PATCH] Improved documentation Restructure documentation to keep the main page short and with the most important information. Move other documentation to its oen pages and cross reference. --- docs/make.jl | 7 ++- docs/src/EDM4hep.md | 35 ++++++++++-- docs/src/examples.md | 6 ++- docs/src/extras/serialisation.md | 5 ++ docs/src/index.md | 93 +++++++------------------------- docs/src/particles.md | 24 +++++++++ docs/src/strategy.md | 18 +++++++ docs/src/visualisation.md | 18 ++++++- 8 files changed, 125 insertions(+), 81 deletions(-) create mode 100644 docs/src/extras/serialisation.md create mode 100644 docs/src/particles.md create mode 100644 docs/src/strategy.md diff --git a/docs/make.jl b/docs/make.jl index e1c8c7c..2682c29 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -15,8 +15,11 @@ makedocs(sitename = "JetReconstruction.jl", "Examples" => "examples.md", "EDM4hep" => "EDM4hep.md", "Visualisation" => "visualisation.md", - "Reference" => Any["Public API" => "lib/public.md", - "Internal API" => "lib/internal.md"] + "Particle Inputs" => "particles.md", + "Reconstruction Strategies" => "strategy.md", + "Reference Docs" => Any["Public API" => "lib/public.md", + "Internal API" => "lib/internal.md"], + "Extras" => Any["Serialisation" => "extras/serialisation.md"] ]) deploydocs(repo = "github.com/JuliaHEP/JetReconstruction.jl.git", diff --git a/docs/src/EDM4hep.md b/docs/src/EDM4hep.md index a2e98bc..00528b4 100644 --- a/docs/src/EDM4hep.md +++ b/docs/src/EDM4hep.md @@ -1,8 +1,37 @@ -# EDM4hep +# EDM4hep Inputs -Extension functionality to read EDM4hep ReconstructedParticles +Extension functionality to read EDM4hep ReconstructedParticles, using the +[EDM4hep.jl](https://github.com/peremato/EDM4hep.jl) package. -## Index +## Examples + +EDM4hep `ReconstructedParticles` can be used as direct input into jet +reconstruction. + +A number of working examples are maintained in the [EDM4hep examples +directory](https://github.com/JuliaHEP/JetReconstruction.jl/tree/main/examples/EDM4hep) +of the package's `examples`. + +Here is a snippet that shows the main steps: + +```julia +using EDM4hep +using EDM4hep.RootIO +using JetReconstruction + +# Change this to something that works on your system +input_file = joinpath("directory", "EDM4hep.root") +reader = RootIO.Reader(input_file) +events = RootIO.get(reader, "events") + +evt = events[1] + +recps = RootIO.get(reader, evt, "ReconstructedParticles") + +cs = jet_reconstruct(recps; algorithm = JetAlgorithm.Durham) +``` + +## Function Index ```@index Pages = ["EDM4hep.md"] diff --git a/docs/src/examples.md b/docs/src/examples.md index fe44cd5..c0fe09f 100644 --- a/docs/src/examples.md +++ b/docs/src/examples.md @@ -1,7 +1,9 @@ # Jet Reconstruction Examples The Jet Reconstruction package has a number of example files that show how to -usage. +usage. These are in the `examples` subdirectory of the package and can be +browsed directly on +[GitHub](https://github.com/JuliaHEP/JetReconstruction.jl/tree/main/examples). *Note:* because of extra dependencies in these scripts, one must use the `Project.toml` file in the `examples` directory. @@ -58,4 +60,4 @@ showing how the jets merge from their different constituents. 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. +that directory as well as [EDM4hep Inputs](@ref). diff --git a/docs/src/extras/serialisation.md b/docs/src/extras/serialisation.md new file mode 100644 index 0000000..02cec20 --- /dev/null +++ b/docs/src/extras/serialisation.md @@ -0,0 +1,5 @@ +# Jet Serialisation + +The package 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. diff --git a/docs/src/index.md b/docs/src/index.md index 17ba691..d0133f5 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -26,42 +26,22 @@ jet_reconstruct(particles; algorithm = JetAlgorithm.AntiKt, R = 1.0) or with some of the optional arguments, ```julia -jet_reconstruct(particles; algorithm = JetAlgorithm.GenKt, R = 0.4, p = 0.5, recombine = +, strategy = RecoStrategy.Best) +jet_reconstruct(particles; algorithm = JetAlgorithm.GenKt, R = 0.4, + p = 0.5, recombine = +, strategy = RecoStrategy.Best) ``` -Where `particles` is a collection of 4-vector objects to reconstruct and the -algorithm is either given explicitly or implied by the power value. For the case -of generalised ``k_T`` (for ``pp`` and ``e^+e^-``) both the algorithm -(`JetAlgorithm.GenKt`) and `p` are needed. For the case of the Durham algorithm -the `R` value is ignored. +Where `particles` is a collection of 4-vector objects (see [Input Particle +Types](@ref)) to reconstruct and the algorithm is either given explicitly or +implied by the power value. -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). +For the case of generalised ``k_T`` (for ``pp`` and ``e^+e^-``) both the +algorithm (`GenKt`, `EEKt`) and `p` are needed. -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. +The `R` value determines the cone size; in the case of the Durham algorithm the +`R` value is ignored. -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`. +The object returned is a [`ClusterSequence`](@ref), which internally tracks all +merge steps and is used for [Inclusive and Exclusive Selections](@ref). ### Algorithm Types @@ -76,37 +56,26 @@ Each known algorithm is referenced using a `JetAlgorithm` scoped enum value. | ``e^+e-`` ``k_\text{T}`` / Durham | `JetAlgorithm.Durham` | `R` value ignored and can be omitted | | generalised ``e^+e-`` ``k_\text{T}`` | `JetAlgorithm.EEKt` | For ``e^+e^-``, value of `p` must also be specified | -### ``pp`` Algorithms +#### ``pp`` Algorithms For the three ``pp`` algorithms with fixed `p` values, the `p` value can be given instead of the algorithm name. However, this should be considered *deprecated* and will be removed in a future release. -## 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 | -|---|---|---| -| `RecoStrategy.Best` | Dynamically switch strategy based on input particle density | `jet_reconstruct` | -| `RecoStrategy.N2Plain` | Global matching of particles at each interation (works well for low $N$) | `plain_jet_reconstruct` | -| `RecoStrategy.N2Tiled` | Use tiles of radius $R$ to limit search space (works well for higher $N$) | `tiled_jet_reconstruct` | - -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. +### Strategy -For ``e^+e^-`` algorithms particle densities are low, so the only implementation -is of the same type as `N2Plain`. +Generally one does not need to manually specify a strategy, but [Algorithm +Strategy](@ref) describes how to do this, if desired. ## Inclusive and Exclusive Selections To obtain final jets both inclusive (``p_T`` cut) and exclusive (``n_{jets}`` or ``d_{ij}`` cut) selections are supported: -- [inclusive_jets(clusterseq::ClusterSequence, ptmin = 0.0)](@ref) -- [exclusive_jets(clusterseq::ClusterSequence; dcut = nothing, njets = nothing)](@ref) +- [`inclusive_jets(clusterseq::ClusterSequence, ptmin = 0.0)`](@ref) +- [`exclusive_jets(clusterseq::ClusterSequence; dcut = nothing, njets = nothing)`](@ref) + +(For `exclusive_jets` either `dcut` or `njets` is needed, but not both.) ### Sorting @@ -119,29 +88,7 @@ sorted_jets = sort!(inclusive_jets(cs::ClusterSequence; ptmin=5.0), by=JetReconstruction.energy, rev=true) ``` -## Plotting and Animation - -![illustration](assets/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. - -The plotting code is a package extension and will load if the one of the `Makie` -modules is loaded in the environment. - -The [`animatereco`](@ref) function will animate the reconstruction sequence, given a -`ClusterSequence` object. See the function documentation for the many options -that can be customised. - -## 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. - -## Reference +## References Although it has been developed further since the CHEP2023 conference, the CHEP conference proceedings, diff --git a/docs/src/particles.md b/docs/src/particles.md new file mode 100644 index 0000000..6dd1d29 --- /dev/null +++ b/docs/src/particles.md @@ -0,0 +1,24 @@ +# 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 Inputs](@ref). + +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`. diff --git a/docs/src/strategy.md b/docs/src/strategy.md new file mode 100644 index 0000000..2dcac44 --- /dev/null +++ b/docs/src/strategy.md @@ -0,0 +1,18 @@ +# Algorithm Strategy + +For the ``pp`` algorithms three strategies are available for the different +algorithms, which can be specified by passing the named argument `strategy=...` +to the reconstruction. + +| Strategy Name | Notes | Interface | +|---|---|---| +| `RecoStrategy.Best` | Dynamically switch strategy based on input particle density | `jet_reconstruct` | +| `RecoStrategy.N2Plain` | Global matching of particles at each interation (works well for low $N$) | `plain_jet_reconstruct` | +| `RecoStrategy.N2Tiled` | Use tiles of radius $R$ to limit search space (works well for higher $N$) | `tiled_jet_reconstruct` | + +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. + +For ``e^+e^-`` algorithms particle densities are low, so the only implementation +is of the same type as `N2Plain`. diff --git a/docs/src/visualisation.md b/docs/src/visualisation.md index 16d1efd..0eb2d17 100644 --- a/docs/src/visualisation.md +++ b/docs/src/visualisation.md @@ -2,7 +2,23 @@ Documentation for visualisation interfaces extension module. -## Index +## Plotting and Animation + +![illustration](assets/jetvis.png) + +To visualise the clustered jets as a 3d bar plot (see illustration above) +`Makie.jl` is used. See the `jetsplot` function in `ext/JetVisualisation.jl` and +its documentation for more. There are two worked examples in the `examples` +directory of this package. + +The plotting code is a package extension and will load if the one of the `Makie` +modules is loaded in the environment. + +The [`animatereco`](@ref) function will animate the reconstruction sequence, +given a `ClusterSequence` object. See the function documentation below for the +many options that can be customised. + +## Function Index ```@index Pages = ["visualisation.md"]