Documentation workflow (#27)

* updated docstrings in places

* added documentation directory

* ci deploy

* test workflow for documentation

* fix glaring typo

* documentation badge

* updated documentation workflow

.github/workflows/docs.yml

@@ -0,0 +1,24 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  docs:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1'
+      - run: |
+          julia --project=docs -e '
+            using Pkg
+            Pkg.develop(PackageSpec(path=pwd()))
+            Pkg.instantiate()'
+      - run: julia --project=docs docs/make.jl
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -9,6 +9,9 @@
 <a href="https://doi.org/10.5281/zenodo.6471796">
     <img src="https://zenodo.org/badge/DOI/10.5281/zenodo.6471796.svg" alt="DOI">
 </a> 
+<a href="https://astro-group-bristol.github.io/Gradus.jl/dev/">
+<img alt="Docs" src="https://img.shields.io/badge/docs-dev-blue.svg"/>
+</a>
 
 
 A spacetime generic, relativistic ray tracing toolkit, leveraging AD and CAS, capable of calculating reverberation lags around accreting black holes and observational signatures.
@@ -17,7 +20,7 @@ A spacetime generic, relativistic ray tracing toolkit, leveraging AD and CAS, ca
 
 ## About
 
-A pure Julia geodesic integration system build on [DifferentialEquations.jl](https://github.com/SciML/DifferentialEquations.jl) using automatic differentiation (AD) and computer algebra systems (CAS) to efficiently compute the geodesic equation. This package requires only a specification of the non-zero metric components in order to solve the 2nd order geodesic system. Alternatively, an implementation of the four velocity components may be specified to integrate a regular 1st order system.
+A pure Julia geodesic integration system built on [DifferentialEquations.jl](https://github.com/SciML/DifferentialEquations.jl) using automatic differentiation (AD) and computer algebra systems (CAS) to efficiently compute the geodesic equation. This package requires only a specification of the non-zero metric components in order to solve the 2nd order geodesic system. Alternatively, an implementation of the four velocity components may be specified to integrate a regular 1st order system.
 
 The motivation behind this package began with an interest in studying reverberation lags around accreting black holes, however the scope has since expanded to facilitate the exploration of generic metrics through time-like, space-like, and null geodesics. 
 

docs/Project.toml

@@ -0,0 +1,2 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"

docs/make.jl

@@ -0,0 +1,30 @@
+push!(LOAD_PATH,"src")
+
+using Documenter
+using Gradus
+
+makedocs(
+    modules=[Gradus],
+    clean=true,
+    sitename="Gradus.jl Documentation",
+
+    pages = [
+        "Home" => "index.md",
+        "Overview" => [
+            # "Examples"
+            "Geodesic integration" => "overview/geodesic-integration.md"
+            "Implemented metrics" => "overview/metrics.md"
+        ],
+        "Internals" => [
+            "Custom metrics" => "internals/custom-metrics.md"
+        ],
+        "Module API" => [
+            "Gradus" => "api-documentation/Gradus.md",
+            "GradusBase" => "api-documentation/GradusBase.md"
+        ]
+    ]
+)
+
+deploydocs(
+    repo = "github.com/astro-group-bristol/Gradus.jl.git"
+)

docs/src/api-documentation/Gradus.md

@@ -0,0 +1,13 @@
+# Gradus API
+
+```@meta
+CurrentModule = Gradus
+```
+## Special radii
+
+```@docs
+isco
+r_ph
+r_mb
+r_s
+```

docs/src/api-documentation/GradusBase.md

@@ -0,0 +1,29 @@
+# GradusBase API
+
+```@meta
+CurrentModule = Gradus.GradusBase
+```
+
+```@docs
+AbstractMetricParams
+geodesic_eq
+geodesic_eq!
+constrain
+inner_radius
+metric
+vector_to_local_sky
+```
+
+## Physical Quantities
+```@docs
+E
+Lz
+```
+
+## Geodesic Points
+
+```@docs
+GeodesicPoint
+getgeodesicpoint
+unpack_solution
+```

docs/src/index.md

@@ -0,0 +1,26 @@
+# Gradus.jl Documentation
+
+A pure Julia geodesic integration system built on [DifferentialEquations.jl](https://github.com/SciML/DifferentialEquations.jl) using automatic differentiation (AD) and computer algebra systems (CAS) to efficiently compute the geodesic equation. This package requires only a specification of the non-zero metric components in order to solve the 2nd order geodesic system. Alternatively, an implementation of the four velocity components may be specified to integrate a regular 1st order system.
+
+The motivation behind this package began with an interest in studying reverberation lags around accreting black holes, however the scope has since expanded to facilitate the exploration of generic metrics through time-like, space-like, and null geodesics. 
+
+Our aim is to make testing modified Kerr metrics and alternative gravity theories _fast_.
+
+```@raw html
+<p align="center" pa="0" ma="0">
+<img width="30%" src="assets/uob-astro-grey.png">
+</p>
+```
+
+Gradus.jl allows for drastically different relativistic simulations to be computed with a composable and reusable API, permitting an end user to simply and expressively calculate physical formulae, create observational signatures, and interface with other popular astrophysics tools. Gradus.jl implements a number of high level abstractions, on the path towards a fully parallelized, high performance numerical relativity ecosystem, scalable from personal computers to super computers.
+
+## About
+
+Gradus.jl is a research tool for calculating geodesic paths in arbitrary space-times. It is currently work-in-progress, and breaking changes are frequent, as the interface is redesigned to match changing use-cases.
+
+It is part of a larger developing eco-system of *Strong Gravity Codes*, created by members of the University of Bristol Astrophysics Group
+
+- Fergus Baker (PhD Student)
+- Dr. Andrew Young (Associate Professor)
+
+For more University of Bristol Astrophysics Group codes, see [our GitHub organisation](https://github.com/astro-group-bristol).

docs/src/internals/custom-metrics.md

@@ -0,0 +1,26 @@
+# Defining a new metric
+
+```@meta
+CurrentModule = Gradus
+```
+
+Gradus.jl is able to integrate any 3+1 dimensional metric, however provides a few derivative abstract types to implement to ensure the most efficient code is executed for a given metric. Currently, Gradus differentiates the following specializations:
+
+
+## First-Order
+
+```@docs
+FirstOrderMethods.AbstractFirstOrderMetricParams
+FirstOrderMethods.four_velocity
+FirstOrderMethods.calc_lq
+FirstOrderMethods.Vr
+FirstOrderMethods.Vθ
+```
+
+## Second-Order
+
+```@docs
+GeodesicTracer.AbstractAutoDiffMetricParams
+GeodesicTracer.metric_components
+GeodesicTracer.AbstractAutoDiffStaticAxisSymmetricParams
+```

docs/src/overview/geodesic-integration.md

@@ -0,0 +1,34 @@
+# Geodesic integration strategies
+
+
+## Second-Order
+
+The motivation behind the second-order methods is to permit the computation of geodesics in generic spacetimes, via the geodesic equation
+
+```math
+\frac{\text{d}^2 x^\mu}{\text{d} \lambda^2} 
+    + \Gamma^{\mu}_{\phantom{\mu}\nu\sigma}
+    \frac{\text{d}x^\nu}{\text{d} \lambda}
+    \frac{\text{d}x^\sigma}{\text{d} \lambda}
+= 0,
+```
+
+where ``x^\mu`` is a position four-vector, ``\Gamma^{\mu}_{\phantom{\mu}\nu\sigma}`` are the Christoffel symbols of the second kind, and ``\lambda`` the affine parameter describing the curve.
+
+The above can be solved as a second-order ODE, subject to an initial position and initial velocity
+
+```math
+u^\mu = \left(t, r, \theta, \phi \right),
+\quad
+\text{and}
+\quad
+\dot{u}^\mu  
+    = \left( \dot{t}, \dot{r}, \dot{\theta}, \dot{\phi} \right),
+```
+where the dot refers to the derivative with respect to ``\lambda``. In general, the spatial components of the initial velocity are known _a priori_, and the time-component is determined via the constraint:
+
+```math
+g_{\sigma\nu} \dot{u}^\sigma \dot{u}^\nu = -\mu^2,
+```
+
+with the metric tensor ``g_{\mu\nu}``, and where ``\mu`` is related to the effective mass associated with the geodesic.

docs/src/overview/metrics.md

@@ -0,0 +1,19 @@
+# Implemented Metrics
+
+```@meta
+CurrentModule = Gradus
+```
+
+## First-Order
+```@docs
+BoyerLindquistFO
+```
+
+## Second-Order
+```@docs
+BoyerLindquistAD
+JohannsenAD
+KerrRefractiveAD
+DilatonAxionAD
+MorrisThorneAD
+```

src/AccretionGeometry/AccretionGeometry.jl

@@ -89,6 +89,7 @@ export AbstractAccretionGeometry,
     GeometricThinDisc,
     inpolygon,
     getarea,
+    getbarycenter,
     CircularOrbits
 
 end # module

src/AccretionGeometry/geometry.jl

@@ -32,7 +32,7 @@ function line_element(u, integrator)
 end
 
 # most of these functions are utility methods for GeometryBasics
-# which may or may not be included. GeometryBasics seems to be about 
+# which may or may not be included. GeometryBasics seems to be about
 # to undergo major breaking changes, which would refine the package
 # so may wait before using another libraries version of these:
 
@@ -97,3 +97,17 @@ function getarea(poly)
     end
     abs(a / 2)
 end
+
+function getbarycenter(poly)
+    pts = getpoints(poly)
+    n_points = length(pts)
+
+    x_sum = 0.0
+    y_sum = 0.0
+    for pt in pts
+        x_sum += pt[1]
+        y_sum += pt[2]
+    end
+
+    @SVector [x_sum / n_points, y_sum / n_points]
+end

src/DiscProfiles/disc-profiles.jl

@@ -109,6 +109,16 @@ end
 
 getareas(vdp::VoronoiDiscProfile{D,T}) where {D,T} = getarea.(vdp.polys)
 
+function getproperarea(poly, m::AbstractMetricParams{T}) where {T}
+    A = getarea(poly)
+    c = getbarycenter(poly)
+    m_params = metric_components(m, (sqrt(c[1]^2 + c[2]^2), π / 2))
+    sqrt(m_params[2] * m_params[3]) * A
+end
+
+getproperareas(vdp::VoronoiDiscProfile{D,T}, m::AbstractMetricParams{T}) where {D,T} =
+    map(p -> getproperarea(p, m), vdp.polys)
+
 function unpack_polys(
     polys::AbstractVector{GeometryBasics.Polygon{2,T,GeometryBasics.Point2{T},L,V}},
 ) where {T,L,V}

src/FirstOrderMethods/FirstOrderMethods.jl

@@ -26,6 +26,22 @@ import ..GeodesicTracer:
     alpha_beta_to_vel,
     ensure_chart_callback
 
+"""
+    AbstractFirstOrderMetricParams{T} <: AbstractMetricParams{T}
+
+Abstract type for metrics using the 1st-order integration method. The 1st-order methods
+reuse the velocity vector as a parameter vector, where only element `vel[2]` and `vel[3]`
+are used, and are local observer ratios ``\\sin \\Theta`` and ``\\sin \\Phi`` respectively.
+
+Require implementation of
+- [`GradusBase.inner_radius`](@ref)
+- [`GradusBase.constrain`](@ref)
+- [`FirstOrderMethods.four_velocity`](@ref)
+- [`FirstOrderMethods.calc_lq`](@ref)
+- [`FirstOrderMethods.Vr`](@ref)
+- [`FirstOrderMethods.Vθ`](@ref)
+- [`GeodesicTracer.alpha_beta_to_vel`](@ref)
+"""
 abstract type AbstractFirstOrderMetricParams{T} <: AbstractMetricParams{T} end
 
 include("implementation.jl")

src/FirstOrderMethods/implementation.jl

@@ -46,6 +46,12 @@ function metric_callback(
     )
 end
 
+"""
+    $(TYPEDSIGNATURES)
+
+Calculate the four-velocity at a point `u`, given a set of metric parameters and the constants
+of motion in `p`.
+"""
 four_velocity(u, m::AbstractFirstOrderMetricParams{T}, p) where {T} =
     error("Not implmented for $(typeof(m)).")
 
@@ -79,10 +85,26 @@ end
 convert_velocity_type(u::StaticVector{S,T}, v) where {S,T} = convert(SVector{S,T}, v)
 convert_velocity_type(u::AbstractVector{T}, v) where {T} = convert(typeof(u), collect(v))
 
+"""
+    $(TYPEDSIGNATURES)
+
+Effective potential in the radial direction. Used only to track sign changes.
+"""
 Vr(m::AbstractFirstOrderMetricParams{T}, u, p) where {T} =
     error("Not implmented for $(typeof(m)).")
+"""
+    $(TYPEDSIGNATURES)
+
+Effective potential in the angular direction. Used only to track sign changes.
+"""
 Vθ(m::AbstractFirstOrderMetricParams{T}, u, p) where {T} =
     error("Not implmented for $(typeof(m)).")
 
-calc_lq(m::AbstractFirstOrderMetricParams{T}, pos, vel) where {T} =
+"""
+    $(TYPEDSIGNATURES)
+
+Calculate constants of motion ``L`` and ``Q``, given a set of metric parameters,
+the geodesic position, and the `param` vector.
+"""
+calc_lq(m::AbstractFirstOrderMetricParams{T}, pos, param) where {T} =
     error("Not implmented for $(typeof(m)).")

src/GeodesicTracer/GeodesicTracer.jl

@@ -9,7 +9,7 @@ using DocStringExtensions
 using Parameters
 
 import ..GradusBase:
-    AbstractMetricParams, geodesic_eq, constrain, onchart, inner_radius, metric
+    AbstractMetricParams, geodesic_eq, constrain, inner_radius, metric
 
 import ForwardDiff
 
@@ -22,15 +22,15 @@ include("auto-diff.jl")
 
 """
     tracegeodesics(
-        m::AbstractMetricParams{T}, 
-        position, velocity, 
+        m::AbstractMetricParams{T},
+        position, velocity,
         time_domain::Tuple{T,T}
-        ; 
-        μ = 0.0f0, 
+        ;
+        μ = 0.0f0,
         callbacks=Nothing,
         solver=Tsit5(),
         solver_opts...
-    ) 
+    )
 
 Integrate a geodesic for metric parameterised by `m`, for some initial positions and velocities.
 The positions and velocities may be