Add docstrings

Project.toml

@@ -1,6 +1,6 @@
 name = "NuFlux"
 uuid = "efbbe403-48f9-4d1c-bbe5-17d2c19d1ebf"
-authors = ["Johannes Schumann <johannes.schumann@fau.de>"]
+authors = ["Johannes Schumann <johannes.schumann@fau.de>", "Santiago Pena Martinez <spenam@unal.edu.co>"]
 version = "0.1.0"
 
 [deps]

docs/make.jl

@@ -2,12 +2,13 @@ using Documenter, NuFlux
 
 makedocs(;
     modules = [NuFlux],
-    authors = "Johannes Schumann",
+    authors = "Johannes Schumann, Santiago Pena Martinez",
     format = Documenter.HTML(
         prettyurls = get(ENV, "CI", nothing) == "true",
     ),
     pages=[
         "Introduction" => "index.md",
+        "API" => "api.md",
     ],
     repo="https://github.com/8me/NuFlux.jl/blob/{commit}{path}#L{line}",
     sitename="NuFlux.jl",

docs/src/api.md

@@ -0,0 +1,10 @@
+# API
+
+
+
+```@index
+```
+
+```@autodocs
+Modules = [NuFlux]
+```

docs/src/index.md

@@ -9,3 +9,41 @@
 with focus on parsing the flux tables used in ["Atmospheric neutrino flux calculation using the NRLMSISE-00 atmospheric model" (10.1103/PhysRevD.92.023004)](https://link.aps.org/doi/10.1103/PhysRevD.92.023004) 
 which are provided under [http://www.icrr.u-tokyo.ac.jp/~mhonda/](http://www.icrr.u-tokyo.ac.jp/~mhonda/).
 
+## Installation
+
+To install `NuFlux.jl`, clone this repo. Then open the Julia REPL as
+```shell
+julia --project=NuFlux.jl
+```
+Next step is to run the following command in the Julia REPL:
+
+```julia
+using Pkg
+Pkg.activate()
+```
+
+Then you are good to go to use `NuFlux.jl`
+
+## Example
+
+Here’s a simple example to get started with `NuFlux.jl`. This example demonstrates how to load a flux table and calculate the flux for a given energy, zenith angle, and azimuth angle.
+
+```julia
+using NuFlux
+
+# Load a flux table from a file, here we will use one of the default fluxes in the package, but you can use your own
+NUFLUX_PATH = split(Base.pathof(NuFlux), "src")[1]
+FLUX_DATA_DIR = joinpath(NUFLUX_PATH, "data")
+flux_dict = NuFlux.readfluxfile(joinpath(FLUX_DATA_DIR, "frj-ally-20-12-solmin.d"))
+
+# Select a specific flux table (e.g., for muon neutrinos)
+muon_neutrino_flux = flux_dict[NuFlux.NUMU_PDGID]  # We can use NuFlux defined variables which are just instances of particles from Corpuscles.jl
+
+# Calculate the flux for a given energy, zenith angle, and azimuth angle
+energy = 10.0  # Energy in GeV
+cosθ = 0.5     # Cosine of the zenith angle
+ϕ = 0.0        # Azimuth angle in radians
+
+flux_value = NuFlux.flux(muon_neutrino_flux, energy, cosθ, ϕ; interpol=true)
+println("Flux value: ", flux_value)
+```

src/NuFlux.jl

@@ -8,8 +8,28 @@ using Corpuscles
 using Interpolations
 using LRUCache
 
+const NUE_PDGID = Particle("nu(e)0").pdgid.value
+const ANUE_PDGID = Particle("~nu(e)0").pdgid.value
+const NUMU_PDGID = Particle("nu(mu)0").pdgid.value
+const ANUMU_PDGID = Particle("~nu(mu)0").pdgid.value
+
+"""
+Abstract type representing a neutrino flux model.
+"""
 abstract type Flux end
 
+"""
+    FluxTable
+
+A struct representing a tabulated neutrino flux model.
+
+# Fields
+- `coszentihbinedges::Vector{Float64}`: Bin edges for the cosine of the zenith angle.
+- `azimuthbinedges::Vector{Float64}`: Bin edges for the azimuth angle.
+- `energies::Vector{Float64}`: Energy values in GeV.
+- `particle::Particle`: The particle type (e.g., neutrino or antineutrino).
+- `flux::Array{Float64, 3}`: A 3D array of flux values, indexed by (cosθ, ϕ, energy).
+"""
 struct FluxTable <: Flux
     coszentihbinedges::Vector{Float64}
     azimuthbinedges::Vector{Float64}
@@ -18,29 +38,96 @@ struct FluxTable <: Flux
     flux::Array{Float64, 3}
 end
 
+"""
+    FluxBinInfo
+
+A struct representing bin information for a flux table.
+
+# Fields
+- `CosZenithBin::Tuple{Rational, Rational}`: Tuple of (min, max) cosine of the zenith angle for the bin.
+- `AzimutBin::Tuple{Rational, Rational}`: Tuple of (min, max) azimuth angle for the bin.
+"""
 struct FluxBinInfo
     CosZenithBin::Tuple{Rational, Rational}
     AzimutBin::Tuple{Rational, Rational}
 end
 
+"""
+    FluxBinInfo(cosZmin, cosZmax, azimutmin, azimutmax)
+
+Construct a `FluxBinInfo` instance from the given bin edges.
+
+# Arguments
+- `cosZmin`: Minimum cosine of the zenith angle.
+- `cosZmax`: Maximum cosine of the zenith angle.
+- `azimutmin`: Minimum azimuth angle.
+- `azimutmax`: Maximum azimuth angle.
+"""
 FluxBinInfo(cosZmin, cosZmax, azimutmin, azimutmax) = FluxBinInfo((cosZmin, cosZmax), (azimutmin, azimutmax)) 
 
+"""
+    parsefluxbininfo(line)
+
+Parse a line of text into a `FluxBinInfo` instance.
+
+# Arguments
+- `line`: A string containing bin edge information.
+
+# Returns
+- `FluxBinInfo`: A struct containing the parsed bin edges.
+"""
 function parsefluxbininfo(line)
     regex = eachmatch(r"-?\d+\.?\d*", line)
     numbers = collect(rationalize(parse(Float64, m.match)) for m in regex)
     FluxBinInfo(numbers...)
 end
 
+"""
+    _getbinmids(binedges)
+
+Calculate the midpoints of bins given their edges.
+
+# Arguments
+- `binedges`: A vector of bin edges.
+
+# Returns
+- `Vector{Float64}`: A vector of bin midpoints.
+"""
 function _getbinmids(binedges)
     Float64.(mean.(binedges[2:end] .+ binedges[1:end-1]) ./ 2)
 end
 
+"""
+    _makerange(x)
+
+Create a range from a vector of values, ensuring constant spacing.
+
+# Arguments
+- `x`: A vector of values.
+
+# Returns
+- `StepRangeLen`: A range with constant spacing.
+
+# Throws
+- `ErrorException`: If the spacing between values is not constant.
+"""
 function _makerange(x)
     diffs = x[2:end] - x[1:end-1]
     std(diffs) > 1e-4 && error("value spacing not constant")
     minimum(x):mean(diffs):maximum(x)
 end
 
+"""
+    readfluxfile(io)
+
+Read a flux file and construct a vector of `FluxTable` instances.
+
+# Arguments
+- `io`: An IO stream or file path to the flux data.
+
+# Returns
+- `Dict{FluxTable}`: A dictionary of `FluxTable` instances representing the flux data indexed by PDG ID.
+"""
 function readfluxfile(io)
     lines = readlines(io)
     idx = findall(l->occursin("average",l), lines)
@@ -73,23 +160,47 @@ function readfluxfile(io)
         data[coszbin, azimutbin, :, :] = v
     end
     retval = Vector{FluxTable}()
-    for (i,p) in enumerate([Particle(14), Particle(-14), Particle(12), Particle(-12)])
+    for (i,p) in enumerate([Particle(NUMU_PDGID), Particle(ANUMU_PDGID), Particle(NUE_PDGID), Particle(ANUE_PDGID)])
         tmp = data[:,:,:,i]
-        # itp = interpolate(tmp, BSpline(Cubic(Line(OnGrid()))))
-        # sitp = scale(itp, _makerange(_getbinmids(coszedges)), _makerange(_getbinmids(azimuthedges)), _makerange(log10.(energies)))
-        # etp = extrapolate(sitp, Flat())
         push!(retval, FluxTable(coszedges, azimuthedges, energies, p, tmp))
     end
-    retval
+    retdict = Dict(NUE_PDGID => retval[3],
+        NUMU_PDGID => retval[1],
+        ANUE_PDGID => retval[4],
+        ANUMU_PDGID => retval[2],)
+    retdict
 end
 
+"""
+    readfluxfile(filepath::String)
+
+Read a flux file from a file path and construct a vector of `FluxTable` instances.
+
+# Arguments
+- `filepath`: Path to the flux data file.
+
+# Returns
+- `Vector{FluxTable}`: A vector of `FluxTable` instances representing the flux data.
+"""
 function readfluxfile(filepath::String)
     io = open(filepath, "r")
     ret = readfluxfile(io)
     close(io)
     ret
 end
 
+"""
+    _getbinindex(binedges, x)
+
+Find the index of the bin that contains the value `x`.
+
+# Arguments
+- `binedges`: A vector of bin edges.
+- `x`: The value to find the bin for.
+
+# Returns
+- `Int`: The index of the bin containing `x`.
+"""
 function _getbinindex(binedges, x)
     if x ≈ first(binedges)
         return 1
@@ -107,6 +218,9 @@ $(SIGNATURES)
 - `flux`:       Flux data 
 - `energy`:     Energy in GeV
 - `interpol`:   Interpolate the data
+
+# Returns
+- `Float64`: The flux value at the given energy.
 """
 function flux(f::FluxTable, energy::S; interpol::Bool=false) where {S <: Real}
     if interpol
@@ -133,6 +247,9 @@ $(SIGNATURES)
 - `energy`:     Energy in GeV
 - `cosθ`:       Cosine of the zenith angle
 - `interpol`:   Interpolate the data
+
+# Returns
+- `Float64`: The flux value at the given energy and zenith angle.
 """
 function flux(f::FluxTable, energy::S, cosθ::T; interpol::Bool=false) where {S,T <: Real}
     if interpol
@@ -161,6 +278,9 @@ $(SIGNATURES)
 - `cosθ`:       Cosine of the zenith angle
 - `ϕ`:          Azimuth angle
 - `interpol`:   Interpolate the data
+
+# Returns
+- `Float64`: The flux value at the given energy, zenith angle, and azimuth angle.
 """
 function flux(f::FluxTable, energy::S, cosθ::T, ϕ::U; interpol::Bool=false) where {S,T,U <: Real}
     if interpol