Accretion geometry

abstract type AbstractAccretionGeometry{T}

Supertype of all accretion geometry. Concrete sub-types must minimally implement

• in_nearby_region
• has_intersect

Alternativey, for more control, either intersects_geometry or geometry_collision_callback may be implemented for a given geometry type.

Geometry intersection calculations are performed by strapping discrete callbacks to the integration procedure.

in_nearby_region(g::AbstractAccretionGeometry{T}, line_element)::Bool

Returns a boolean indicating whether the line_element is "close" to the geometry in question. Used to optimize when to call the intersection algorithm.

Contextually, "close" is a little arbitrary, and this function may always return True, however will suffer in performance if this is the case.

line_element is a tuple of two four-position vectors, indicating the last integration position, and current integration position, i.e. (u_prev, u_curr), in integrator coordinates.

Notes

This function actually depends on the step size of the integrator, but this is currently not considered in the implementation.

has_intersect(g::AbstractAccretionGeometry{T}, line_element)

Returns a boolean indicating whether line_element intersects the geometry g. The intersection algorithm used depends on the geometry considered. For meshes, this uses the jsf_algorithm.

line_element is a tuple of two four-position vectors, indicating the last integration position, and current integration position, i.e. (u_prev, u_curr), in integrator coordinates.

abstract type AbstractAccretionDisc{T} <: AbstractAccretionGeometry{T}

Supertype for axis-symmetric geometry, where certain optimizing assumptions may be made. Concrete subtypes must implement distance_to_disc.

distance_to_disc(d::AbstractAccretionGeometry, u; kwargs...)

Calculate distance to the closest element of the disc. The distance need not be metric or Pythagorean, but rather should be positive when the four vector u is distant, zero when u is on the surface, and negative when u is within the disc geometry.

Must return a floating point number.

abstract type AbstractThickAccretionDisc{T} <: AbstractAccretionDisc{T}

Supertype for axis-symmetric geometry that are specified by a height cross-section function. Subtypes are required to implement cross_section.

cross_section(d::AbstractThickAccretionDisc, u)

Return the height cross-section of a thick accretion disc at the (projected) coordinates of u. This function also incorporates bounds checking, and should return a negative value if the disc is not defined at u.

Example

For a top hat disc profile with constant height between two radii

struct TopHatDisc{T} <: AbstractThickAccretionDisc{T}
    inner_r::T
    outer_r::T
end

function Gradus.cross_section(d::TopHatDisc, u)
    # project u into equatorial plane
    r = u[2] * sin(u[3])
    if (r < d.inner_r) || (r > d.outer_r)
        return -1.0
    else
        return 1.0
    end
end

ThickDisc{T,F,P} <: AbstractThickAccretionDisc{T}
ThickDisc(f, params=nothing; T = Float64)

A standard wrapper for creating custom disc profiles from height cross-section function f. This function is given the disc parameters as unpacked arguments:

d.f(u, d.params...)

If no parameters are specified, none will be passed to f.

Example

Specifying a toroidal disc centered on r=10 with radius 1:

d = ThickDisc() do u
    r = u[2]
    if r < 9.0 || r > 11.0
        return -1.0
    else
        x = r - 10.0
        sqrt(1-x^2)
    end
end

ShakuraSunyaev{T} <: AbstractThickAccretionDisc{T}
ShakuraSunyaev(
    m::AbstractMetric;
    eddington_ratio = 0.3,
    η = nothing,
    contra_rotating = false,
)

The classic Shakura & Sunyaev (1973) accretion disc model, with height given by $2H$, where

\[H = \frac{3}{2} \frac{1}{\eta} \left( \frac{\dot{M}}{\dot{M}_\text{Edd}} \right) \left( 1 - \sqrt{\frac{r_\text{isco}}{\rho}} \right)\]

Here $\eta$ is the radiative efficiency, which, if unspecified, is determined by the circular orbit energy at the ISCO:

\[\eta = 1 - E_\text{isco}\]

MeshAccretionGeometry(mesh)