Improve docs; add tests

.github/workflows/CI.yml

@@ -0,0 +1,41 @@
+
+name: CI
+on:
+  - push
+
+jobs:
+  test:
+    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        version:
+          - '1.6'
+          - 'nightly'
+        os:
+          - ubuntu-latest
+        arch:
+          - x64
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: ${{ matrix.version }}
+          arch: ${{ matrix.arch }}
+      - uses: actions/cache@v1
+        env:
+          cache-name: cache-artifacts
+        with:
+          path: ~/.julia/artifacts
+          key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-test-${{ env.cache-name }}-
+            ${{ runner.os }}-test-
+            ${{ runner.os }}-
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-runtest@v1
+      - uses: julia-actions/julia-processcoverage@v1
+      - uses: codecov/codecov-action@v4.0.1
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/documentation.yml

@@ -3,7 +3,7 @@ name: Documentation
 on:
   push:
     branches:
-      - documentation # update to match your development branch (master, main, dev, trunk, ...)
+      - main 
     tags: '*'
   pull_request:
 

Project.toml

@@ -1,7 +1,7 @@
 name = "AstroBasis"
 uuid = "f9f069e8-36d3-4f22-8c0d-26ca7e8540d8"
 authors = ["Mike Petersen <michael.petersen@roe.ac.uk>", "Mathieu Roule <roule@iap.fr>"]
-version = "0.2.0"
+version = "0.3.0"
 
 [deps]
 HDF5 = "f67ccb44-e63f-5c2f-98bd-6dc0ccc4ba2f"
@@ -10,3 +10,9 @@ SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"
 
 [compat]
 julia = "1.6" # Equivalent to "^1.6", will allow any 1.a.b version with a>=6
+
+[extras]
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[targets]
+test = ["Test"]

docs/make.jl

@@ -6,6 +6,8 @@ using Documenter, AstroBasis
 makedocs(sitename = "AstroBasis.jl",
          pages=[
                 "Home" => "index.md",
+                "Quickstart" => "quickstart.md",
+                "Common Interface" => "common.md",
                 "Bases" => "bases.md"
                ],
          format = Documenter.HTML(prettyurls=false))

docs/src/bases.md

@@ -8,6 +8,11 @@
 AstroBasis.CB73Basis
 ```
 
+### Hernquist (1992)
+```@docs
+AstroBasis.HernquistBasis
+```
+
 
 ## Razor-thin bases
 

docs/src/common.md

@@ -0,0 +1,22 @@
+# Functions common to all bases
+
+To seamlessly allow for switching between different bases, the bases are all organised around common functions.
+
+## Accessing potential functions
+```@docs
+AstroBasis.getUln
+```
+
+```@docs
+AstroBasis.tabUl!
+```
+
+## Accessing density functions
+
+```@docs
+AstroBasis.getDln
+```
+
+```@docs
+AstroBasis.tabDl!
+```

docs/src/index.md

@@ -2,3 +2,4 @@
 
 *Bi-orthogonal bases for galactic dynamics in Julia*
 
+AstroBasis.jl implements several common basis sets (see 'Bases') in galactic dynamics, with a common interface (see 'Common Interfaces'). A quickstart is availabe, which will walk you through how to construct an image of the basis sets.

docs/src/quickstart.md

@@ -0,0 +1,58 @@
+# Quickstart Example
+
+In this example code, we will make a figure of the radial basis elements from Clutton-Brock (1973).
+
+```julia
+import AstroBasis
+using Plots
+using LaTeXStrings
+```
+
+Now create the basis:
+
+```julia
+println("Creating the basis ... ")
+G, rb = 1., 1.
+ltest, nradial = 2, 5
+basis = AstroBasis.CB73Basis(lmax=ltest,nradial=nradial,G=G, rb=rb)
+```
+
+Define where to make the basis points:
+
+```julia
+# Points (rescaled radius)
+println("Compute basis values ... ")
+nx = 200
+rmin, rmax = 0., 3.
+tabx = collect(LinRange(rmin/basis.rb,rmax/basis.rb,nx))
+```
+
+Use the common function `tabUl!` to fill the table:
+
+```julia
+# Compute the values of the potential basis elements and store them
+tabU = zeros(nradial,nx) # Storage for the basis values
+for j = 1:nx
+    # Compute all the basis elements values at a given location r (the result is stored in basis.tabUl)
+    AstroBasis.tabUl!(basis,ltest,tabx[j]*basis.rb)
+    # Store them in tabU
+    for i = 1:nradial
+        tabU[i,j] = basis.tabUl[i]
+    end
+end
+```
+
+And finally plot:
+
+```julia
+# Plot the curves
+println("Plotting ... ")
+labels = reshape(["n="*string(k) for k=1:nradial],(1,nradial)) #Need to be row
+plU=plot(tabx, transpose(tabU), title = "Potential basis elements: Clutton-Brock (1973)",label=labels)
+xlabel!(plU, L"$r / r_{\mathrm{b}}$")
+ylabel!(plU, L"$U^{\ell}_n (r)\quad \ell=$"*string(ltest))
+savefig(plU,"CluttonBrock73.png")
+println("The plot has been saved in the same folder as this example script under the name 'CluttonBrock73.png'.")
+```
+
+![`Clutton-Brock (1973)`](../../examples/CluttonBrock73_original.png)

src/AstroBasis.jl

@@ -2,31 +2,44 @@ module AstroBasis
 
 using HDF5
 
-# make an abstract Basis type
-# @WARNING: Should be defined before any basis definition
-abstract type AbstractAstroBasis  end
+# define an abstract Basis type; define a function to get the dimension for each basis type
+abstract type AbstractAstroBasis end
+dimension(basis::AbstractAstroBasis) = dimension(typeof(basis))
+
+
+# split Basis types by dimension; specify the dimensionality for safety; correctly dispatch dimension for subtypes
+abstract type RazorThinBasis <: AbstractAstroBasis end
+dimension(::Type{<:RazorThinBasis}) = 2
+
+abstract type SphericalBasis <: AbstractAstroBasis end
+dimension(::Type{<:SphericalBasis}) = 3
+
+# make dimension available
+export dimension
 
 # Documentation of the function needed in a basis
 include("Utils/IO.jl")
+export getparameters
 
 # Documentation of the function needed in a basis
 include("Basisdoc.jl")
+export getUln,getDln,tabUl!,tabDl!
 
 # bring in the Clutton-Brock (1973) spherical basis
 include("CB73.jl")
 
-# @IMPROVE, add Bessel basis
-
 # bring in the Hernquist & Ostriker (1992) disc basis
 include("Hernquist.jl")
 
+# @IMPROVE, add Bessel basis
+
+# @IMPROVE, add readers for EXP empirical bases
+
 # bring in the Clutton-Brock (1972) disc basis
 include("CB72.jl")
 
 # bring in the Kalnajs (1976) disc basis
 include("Kalnajs76.jl")
 
-# @IMPROVE, add readers for EXP empirical bases
-
 
 end # module

src/Basisdoc.jl

@@ -60,13 +60,27 @@ end
 
 
 """
-    tabUl!(basis,l)
+    tabUl!(basis, l, r)
 
-Compute potential table for a given l and r, and for 0 <= n <= nmax
+Compute the basis potential elements for a given basis structure.
 
-To avoid repeated memory allocations, this overwrites the 'basis.tabUl' table
+# Arguments
+- `basis`: The structure containing basis parameters and prefactors. This should be a subtype of `AbstractAstroBasis`.
+- `l::Int64`: The harmonic/azimuthal index.
+- `r::Float64`: The radial coordinate.
+
+# Description
+This function computes the basis elements for the provided structure. It updates the
+potential or density basis elements in-place within the given structure.
+
+# Implementation Details
+- The function initializes the recurrence relation for the adimensional subpart of the basis elements.
+- It then iterates through the radial basis numbers, updating the basis elements using a recurrence relation.
+- Finally, it multiplies the computed values by the appropriate prefactors.
+
+# Warning
+> l=0 is index 1, n=0 is index 1.
 
-@WARNING:: l=0 is index 1, n=0 is index 1.
 """
 function tabUl!(basis,l,r)
     # ... [implementation sold separately] ...