Point functions

abstract type AbstractGeodesicPoint{T}

Supertype for geodesic points, used to store information about specific points along geodesic trajectories.

Must minimally have the same fields as GeodesicPoint. Examples include Gradus.FirstOrderGeodesicPoint.

struct GeodesicPoint <: AbstractGeodesicPoint

A structure that represents the start and end point along a geodesic. To obtain a GeodesicPoint, use unpack_solution or unpack_solution_full on the result of a tracegeodesics.

Fields:

• status::StatusCodes.T: A StatusCodes code of the integrator for this geodesic.
• λ_min::T: Start affine time
• λ_max::T: End affine time
• x_init::SVector{4,T}: Start four position
• x::SVector{4,T}: End four position
• v_init::SVector{4,T}: Start four velocity
• v::SVector{4,T}: End four velocity
• aux::A: Auxillary values (polarisation, intensities, etc.)

Example

sol = tracegeodesics(m, x, v, 100.0)
gp = unpack_solution(sol)
gp.status

unpack_solution_full

Unpacks each point in the solution, similar to unpack_solution but returns an array of GeodesicPoint.

abstract type AbstractPointFunction

Abstract super type for point functions. Must have f::Function field.

struct PointFunction <: AbstractPointFunction
PointFunction(func)

Point functions are functions that are used to calculate physical parameters from geodesic integrations, and to compose more complex models. A number of default and utility PointFunction are defined in Gradus.ConstPointFunctions.

Principally, point functions return a single value per geodesic, and are used to fill rendered images with values, e.g. colouring redshift.

Point functions may be instantiated by wrapping a function with the following signature

function func(m::AbstractMetric{T}, gp::AbstractGeodesicPoint, max_time::T; kwargs...)::T where {T}
    # ...
end

pf = PointFunction(func)

• The AbstractMetric argument may be used to dispatch for different metrics.
• gp is an AbstractGeodesicPoint corresponding to a given geodesic.
• The max_time parameter is the maximum integration time used to integrate the geodesics. This may be useful when trying to determine whether a geodesic terminated early or not.

They may be invoked by invoking the instance

result = pf(m, gp, max_time)

Multiple AbstractPointFunction may be chained together using the ∘ operator, and are evaluated from right to left

pf3 = pf2 ∘ pf1

This may be useful for constructing filters using FilterPointFunction. When used with two PointFunction objects, the output of the previous PointFunction is passed to the next via the value keyword argument.

struct FilterPointFunction <: AbstractPointFunction
FilterPointFunction(func, default_value)

Point functions used to filter geodesics. They may be constructed with

function func(m::AbstractMetric{T}, gp::AbstractGeodesicPoint, max_time::T; kwargs...)::Bool where {T}
    # ... return Bool
end

fpf = FilterPointFunction(func, NaN64)

The second argument to the constructor is the default value, given to the pixel if the boolean condition of func is false.

Example

A filter for geodesics within a certain radius, used to only calculate redshift within 10 $\r_\text{g}$

func(m, gp, max_time) = gp.u[2] < 10.0
pf = ConstPointFunctions.redshift(m, u) ∘ FilterPointFunction(func, NaN64)

module ConstPointFunctions

Module defining a number of const Gradus.AbstractPointFunction, serving different utility or common purposes for analysis.

filter_early_term(m::AbstractMetric, gp::AbstractGeodesicPoint, max_time)

A FilterPointFunction that filters geodesics that termined early (i.e., did not reach maximum integration time or effective infinity). Default: NaN.

filter_intersected(m::AbstractMetric, gp::AbstractGeodesicPoint, max_time)

A FilterPointFunction that filters geodesics which intersected with the accretion disc. Default: NaN.

affine_time(m::AbstractMetric, gp::AbstractGeodesicPoint, max_time)

A PointFunction returning the affine integration time at the endpoint of the geodesic.

shadow(m::AbstractMetric, gp::AbstractGeodesicPoint, max_time)

A PointFunction which colours the shadow of the black hole for any disc-less render. Equivalent to ConstPointFunctions.affine_time ∘ ConstPointFunctions.filter_early_term.

redshift(m::AbstractMetric, x_obs)

Returns a PointFunction that calculates the redshift of a medium as observed by an observer at x_obs.

Calculate the analytic redshift at a given geodesic point, assuming equatorial, geometrically thin accretion disc. Implementation depends on the metric type, with non-Kerr metrics using an interpolation scheme within the plunging region via interpolate_redshift.

Calls redshift_function to dispatch different implementations.