APIs

There are 6 functions that are exported, namely

Teukolsky_radial
GSN_radial
Teukolsky_pointparticle_mode
GSN_pointparticle_mode
rstar_from_r
r_from_rstar

and there are 7 custom types that are exported, i.e.

BoundaryCondition
NormalizationConvention
Mode
GSNRadialFunction
TeukolskyRadialFunction
GSNPointParticleMode
TeukolskyPointParticleMode

Currently, only the exported functions and types are documented below. Documentations for private (i.e. unexported) functions will be added at a later stage.

Functions

GeneralizedSasakiNakamura.Teukolsky_radial — Function

Teukolsky_radial(s::Int, l::Int, m::Int, a, omega, boundary_condition, rsin, rsout; horizon_expansion_order::Int=_DEFAULT_horizon_expansion_order, infinity_expansion_order::Int=_DEFAULT_infinity_expansion_order, method="auto", data_type=Solutions._DEFAULTDATATYPE,  ODE_algorithm=Solutions._DEFAULTSOLVER, tolerance=Solutions._DEFAULTTOLERANCE, rsmp=nothing)

Compute the Teukolsky function for a given mode (specified by s the spin weight, l the harmonic index, m the azimuthal index, a the Kerr spin parameter, and omega the frequency [which can be complex]) and boundary condition specified by boundary_condition, which can be either

- `IN` for purely-ingoing at the horizon,
- `UP` for purely-outgoing at infinity,
- `OUT` for purely-outgoing at the horizon,
- `DOWN` for purely-ingoing at infinity.

Note that the OUT and DOWN solutions are constructed by linearly combining the IN and UP solutions, respectively.

The full GSN solution is converted to the corresponding Teukolsky solution $(R(r), dR/dr)$ and the incidence, reflection and transmission amplitude are converted from the GSN formalism to the Teukolsky formalism with the normalization convention that the transmission amplitude is normalized to 1 (i.e. normalization_convention=UNIT_TEUKOLSKY_TRANS).

Note, however, when omega = 0, the exact Teukolsky function expressed using Gauss hypergeometric functions will be returned (i.e., instead of using the GSN formalism). In this case, only s, l, m, a, omega, boundary_condition will be parsed.

With complex values of omega, the Teukolsky function is evaluated as a function of $r$, where the value at the corresponding location $\rho = r_{*}(r) \in \mathbb{R}$ along the rotated integration path on the complex plane is returned.

source

Teukolsky_radial(s::Int, l::Int, m::Int, a, omega; data_type=Solutions._DEFAULTDATATYPE, ODE_algorithm=Solutions._DEFAULTSOLVER, tolerance=Solutions._DEFAULTTOLERANCE, method="auto")

Compute the Teukolsky function for a given mode (specified by s the spin weight, l the harmonic index, m the azimuthal index, a the Kerr spin parameter, and omega the frequency) with the purely-ingoing boundary condition at the horizon (IN) and the purely-outgoing boundary condition at infinity (UP).

Note that for real frequencies, the numerical inner boundary (rsin) and outer boundary (rsout) are set to the default values _DEFAULT_rsin and _DEFAULT_rsout, respectively, while the order of the asymptotic expansion at the horizon and infinity are determined automatically. As for complex frequencies, the numerical inner and the outer boundaries are determined automatically, while the order of the asymptotic expansion at the horizon and infinity are set to _DEFAULT_horizon_expansion_order_for_cplx_freq and _DEFAULT_infinity_expansion_order_for_cplx_freq, respectively.

source

GeneralizedSasakiNakamura.GSN_radial — Function

GSN_radial(s::Int, l::Int, m::Int, a, omega, boundary_condition, rsin, rsout; horizon_expansion_order::Int=_DEFAULT_horizon_expansion_order, infinity_expansion_order::Int=_DEFAULT_infinity_expansion_order, method="auto", data_type=Solutions._DEFAULTDATATYPE,  ODE_algorithm=Solutions._DEFAULTSOLVER, tolerance=Solutions._DEFAULTTOLERANCE, rsmp=nothing)

Compute the GSN function for a given mode (specified by s the spin weight, l the harmonic index, m the azimuthal index, a the Kerr spin parameter, and omega the frequency [which can be complex]) and boundary condition specified by boundary_condition, which can be either

- `IN` for purely-ingoing at the horizon,
- `UP` for purely-outgoing at infinity,
- `OUT` for purely-outgoing at the horizon,
- `DOWN` for purely-ingoing at infinity.

Note that the OUT and DOWN solutions are constructed by linearly combining the IN and UP solutions, respectively.

The GSN function is numerically solved, for real values of omega, in the interval of tortoise coordinates $r_{*} \in$ [rsin, rsout] using the ODE solver (from DifferentialEquations.jl) specified by ODE_algorithm (default: Vern9()) with tolerance specified by tolerance (default: 1e-12). The ODE to be solved is determined by the keyword method (default: auto), which can be either linear (solving the GSN equation in a linear form) or Riccati (solving the GSN equation in a nonlinear form). By default the data type used is ComplexF64 (i.e. double-precision floating-point number) but it can be changed by specifying data_type (e.g. Complex{BigFloat} for complex arbitrary precision number).

With complex values of omega, the GSN function is solved along a rotated path on the complex plane of $r_*$, where the path consists of two broken line segments parametrized by a real variable/a new coordinate $\rho$. The angle with which the path is rotated is determined by the frequency $\omega$, the Kerr spin parameter $a$ and the azimuthal index $m$, such that the GSN function still behaves like a plane wave near the horizon and spatial infinity. At $\rho = 0$, the path intersects with the real axis at $r_{*} = r_{*}^{\rm{mp}}$ (rsmp, default to be nothing, which means it will be determined automatically). Both the numerical and semi-analytical GSN solutions are evaluated as functions of $\rho$ instead of the now-complex $r_{*}$.

While the numerical GSN solution is only accurate in the range [rsin, rsout], the full GSN solution is constructed by smoothly attaching the asymptotic solutions near horizon (up to horizon_expansion_order-th order) and infinity (up to infinity_expansion_order-th order). Therefore, the now-semi-analytical GSN solution is accurate everywhere.

Note, however, when omega = 0, the exact GSN function expressed using Gauss hypergeometric functions will be returned (i.e., instead of being solved numerically). In this case, only s, l, m, a, omega, boundary_condition will be parsed.

Return a GSNRadialFunction object which contains all the information about the GSN solution.

source

GSN_radial(s::Int, l::Int, m::Int, a, omega; data_type=Solutions._DEFAULTDATATYPE, ODE_algorithm=Solutions._DEFAULTSOLVER, tolerance=Solutions._DEFAULTTOLERANCE, method="auto")

Compute the GSN function for a given mode (specified by s the spin weight, l the harmonic index, m the azimuthal index, a the Kerr spin parameter, and omega the frequency) with the purely-ingoing boundary condition at the horizon (IN) and the purely-outgoing boundary condition at infinity (UP).

source

GeneralizedSasakiNakamura.Coordinates.rstar_from_r — Function

rstar_from_r(a, r)

Convert a Boyer-Lindquist coordinate r to the corresponding tortoise coordinate rstar.

source

GeneralizedSasakiNakamura.Coordinates.r_from_rstar — Function

r_from_rstar(a, rstar)

Convert a tortoise coordinate rstar to the corresponding Boyer-Lindquist coordiante r. It uses a bisection method when rstar <= 0, and Newton method otherwise.

The function assumes that $r \geq r_{+}$ where $r_{+}$ is the outer event horizon.

source

GeneralizedSasakiNakamura.Teukolsky_pointparticle_mode — Function

Teukolsky_pointparticle_mode(s::Int, l::Int, m::Int, n::Int, k::Int, a, p, e, x; method="auto", N::Int, K::Int)

Compute the amplitude of the inhomogeneous Teukolsky solution at infinity (for s = - 2) and at horizon (for s = + 2) due to a point particle on a generic timelike bound orbit around a Kerr black hole, with a spin parameter of a, for a given mode (specified by s the spin weight, l the harmonic index, m the azimuthal index, n the radial index and k the polar index). The orbit is specified by p the semi-latus rectum, e the eccentricity and x the inclination parameter ($x \equiv \cos \theta_{\mathrm{inc}}$).

In addition, we compute also the energy, angular momentum and Carter constant flux at infinity (for s = - 2) and the horizon (for s = + 2). Note that these values are formalism-independent.

The numerical method to compute the convolution integral is specified by method (default: auto), which can either be trapezoidal or levin. We sample the trajectory over a grid of size N x K, where N and K are the number of Chebyshev nodes in the radial and the polar direction, respectively. Note that they must be powers of 2.

source

GeneralizedSasakiNakamura.GSN_pointparticle_mode — Function

GSN_pointparticle_mode(s::Int, l::Int, m::Int, n::Int, k::Int, a, p, e, x; method="auto", N::Int, K::Int)

Compute the amplitude of the inhomogeneous GSN solution at infinity (for s = - 2) and at horizon (for s = + 2) due to a point particle on a generic timelike bound orbit around a Kerr black hole, with a spin parameter of a, for a given mode (specified by s the spin weight, l the harmonic index, m the azimuthal index, n the radial index and k the polar index). The orbit is specified by p the semi-latus rectum, e the eccentricity and x the inclination parameter ($x \equiv \cos \theta_{\mathrm{inc}}$).

In addition, we compute also the energy, angular momentum and Carter constant flux at infinity (for s = - 2) and the horizon (for s = + 2). Note that these values are formalism-independent.

source

Types

BoundaryCondition

This is an enum type that can take either one of the four values

value
`IN`	purely ingoing at the horizon
`UP`	purely outgoing at infinity
`OUT`	purely outgoing at the horizon
`DOWN`	purely ingoing at infinity

NormalizationConvention

This is an enum type that can take either one of the two values

value
`UNIT_GSN_TRANS`	normalized to have a unit transmission amplitude for the GSN function
`UNIT_TEUKOLSKY_TRANS`	normalized to have a unit transmission amplitude for the Teukolsky function

Mode

This is a composite struct type that stores information about a mode

field
`s`	spin weight $s$
`l`	harmonic index $\ell$
`m`	azimuthal index $m$
`a`	Kerr spin parameter $a/M$
`omega`	frequency $M\omega$
`lambda`	spin-weighted spheroidal eigenvalue $\lambda$

GSNRadialFunction

This is a composite struct type that stores the output from GSN_radial

Tip

GSNRadialFunction(rstar) is equivalent to GSNRadialFunction.GSN_solution(rstar)[1], returning only the value of the GSN function evaluated at the tortoise coordinate rstar

field
`mode`	a Mode object storing information about the mode
`boundary_condition`	a BoundaryCondition object storing which boundary condition this function satisfies
`rsin`	numerical inner boundary $r_{}^{\mathrm{in}}/M$ where the GSN equation is numerically evolved ($r_{}$ is a tortoise coordinate)
`rsout`	numerical outer boundary $r_{}^{\mathrm{out}}/M$ where the GSN equation is numerically evolved ($r_{}$ is a tortoise coordinate)
`rsmp`	The matching point in tortoise coordinate $r_{*}^{\mathrm{mp}}$ if used
`horizon_expansion_order`	order of the asymptotic expansion at the horizon
`infinity_expansion_order`	order of the asymptotic expansion at infinity
`transmission_amplitude`	transmission amplitude in the GSN formalism of this function
`incidence_amplitude`	incidence amplitude in the GSN formalism of this function
`reflection_amplitude`	reflection amplitude in the GSN formalism of this function
`numerical_GSN_solution`	numerical solution (`ODESolution` object from `DifferentialEquations.jl`) to the GSN equation in [`rsin`, `rsout`] if applicable; output is a vector $[ \hat{X}(r_{}), d\hat{X}(r_{})/dr_{*} ]$
`numerical_Riccati_solution`	numerical solution (`ODESolution` object from `DifferentialEquations.jl`) to the GSN equation in the Riccati form if applicable; output is a vector $[ \hat{\Phi}(r_{}), d\hat{\Phi}(r_{})/dr_{*} ]$
`GSN_solution`	full GSN solution where asymptotic solutions are smoothly attached; output is a vector $[ \hat{X}(r_{}), d\hat{X}(r_{})/dr_{*} ]$
`normalization_convention`	a NormalizationConvention object storing which normalization convention this function adheres to

TeukolskyRadialFunction

This is a composite struct type that stores the output from Teukolsky_radial

Tip

TeukolskyRadialFunction(r) is equivalent to TeukolskyRadialFunction.Teukolsky_solution(r)[1], returning only the value of the Teukolsky function evaluated at the Boyer-Lindquist coordinate r

field
`mode`	a Mode object storing information about the mode
`boundary_condition`	a BoundaryCondition object storing which boundary condition this function satisfies
`transmission_amplitude`	transmission amplitude in the Teukolsky formalism of this function
`incidence_amplitude`	incidence amplitude in the Teukolsky formalism of this function
`reflection_amplitude`	reflection amplitude in the Teukolsky formalism of this function
`GSN_solution`	a GSNRadialFunction object storing the corresponding GSN function
`Teukolsky_solution`	Teukolsky solution where asymptotic solutions are smoothly attached; output is a vector $[ \hat{R}(r), d\hat{R}(r)/dr ]$
`normalization_convention`	a NormalizationConvention object storing which normalization convention this function adheres to

GSNPointParticleMode

This is a composite struct type that stores the output from GSN_pointparticle_mode

field
`mode`	a Mode object storing information about the mode (including the frequency)
`amplitude`	the amplitude of the inhomogeneous GSN solution at infinity or at the horizon such that $X^{\infty}_{\ell m \omega} =$ amplitude $e^{i \omega r_}$ or $X^{\mathrm{H}}_{\ell m \omega} =$ amplitude $e^{- i \left[ \omega - ma/(2r_{+}) \right] r_}$
`energy_flux`	the energy flux emitted towards infinity or towards the horizon
`angular_momentum_flux`	the angular momentum flux towards infinity or towards the horizon
`Carter_const_flux`	the Carter constant flux towards infinity or towards the horizon
`trajectory`	the trajectory/geodesic that the particle follows
`Y_solution`	the auxiliary function $Y$ used in the calculation
`SWSH`	the spin-weighted spheroidal harmonic used in the calculation
`method`	a named tuple storing the method and grid size used in computing the convolution integral

TeukolskyPointParticleMode

This is a composite struct type that stores the output from Teukolsky_pointparticle_mode

field
`mode`	a Mode object storing information about the mode (including the frequency)
`amplitude`	the amplitude of the inhomogeneous Teukolsky solution at infinity or at the horizon such that $R^{\infty}_{\ell m \omega} =$ amplitude $r^{-(2s+1)} e^{i \omega r_}$ or $R^{\mathrm{H}}_{\ell m \omega} =$ amplitude $\Delta^{-s} e^{- i \left[ \omega - ma/(2r_{+}) \right] r_}$
`energy_flux`	the energy flux emitted towards infinity or towards the horizon
`angular_momentum_flux`	the angular momentum flux towards infinity or towards the horizon
`Carter_const_flux`	the Carter constant flux towards infinity or towards the horizon
`trajectory`	the trajectory/geodesic that the particle follows
`Y_solution`	the auxiliary function $Y$ used in the calculation
`SWSH`	the spin-weighted spheroidal harmonic used in the calculation
`method`	a named tuple storing the method and grid size used in computing the convolution integral