APIs
There are 4 functions that are exported, namely
and there are 5 custom types that are exported, i.e.
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 — FunctionTeukolsky_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.
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.
GeneralizedSasakiNakamura.GSN_radial — FunctionGSN_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.
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).
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.
GeneralizedSasakiNakamura.Coordinates.rstar_from_r — Functionrstar_from_r(a, r)Convert a Boyer-Lindquist coordinate r to the corresponding tortoise coordinate rstar.
GeneralizedSasakiNakamura.Coordinates.r_from_rstar — Functionr_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.
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
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
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 |