xhorizon.tortoise.tortoise module

This module contains functions for numerically evaluating the global tortoise function F(r), and its inverse F^{-1}_{j}(rstar).

After the main block of code, there are supporting utilities and tests.

class xhorizon.tortoise.tortoise.F_by_interp(f, rj, eps, npoints=500)

Bases: object

Our numerical implementation of the global tortoise function is always defined by linear interpolation of densely spaced reference arrays. This method is used even when an analytically defined alternative is possible (note that analytical alternatives are rarely available for Finv). The interpolation method is generally valid, and allows F and Finv to be implemented symmetrically.

The F_by_interp class is necessary in order to avoid accidentally overwriting the objects containing the reference arrays. Since a new F_by_interp instance is created when the class is called, each function F (and Finv) will have its own copy of the reference arrays.

The class methods make_F() and make_Finv() generate functions F(r) and Finv(j, rstar) respectively:

The inputs r and rstar should be arrays. The input j is the interval index label. It may be either a scalar (float or int), or an array of equal length to rstar.

In order to create the reference arrays, F_by_interp calls create_reference, which in turn calls other subroutines. The call hierarchy is:

F_by_interp < create_reference < F_by_integration < F_refpoints.

The heavy lifting is done in F_by_integration, which implements the integral definition of the tortoise function. The function F_refpoints supports this task by preliminarily determining the reference values F(r_j+eps) in each interval.

make_F()

Using the reference arrays, returns a function object F(r). Values outside the valid range return nan.

Input r to F(r) should be an array.

make_Finv()

Using the reference arrays, returns a function object Finv(j, rstar). Values outside the valid range return nan.

Inputs rstar and j to Finv(j,r) should be equal length arrays.

If input j is a scalar (float or int), it is converted to an array of correct length with uniform value.

xhorizon.tortoise.tortoise.create_reference(f, rj, eps, npoints=500)

Create a well-spaced array of r values and calculate the corresponding values rstar = F(r). Return both arrays to use as interpolation reference for forward and inverse tortoise functions.

xhorizon.tortoise.tortoise.F_by_integration(f, rj, eps, r)

Given the metric function f(r) and the values of r_j and epsilon, returns an array rstar=F(r) from an array r. The values are determined by performing the defining definite integral.

xhorizon.tortoise.tortoise.F_refpoints(f, rj, eps)

Given the metric function f(r) and the values of r_j and epsilon, returns an array of of the values F(r_j+eps) == F_j. Special Values:

F(eps) = F(r_0 + eps) = 0 F(inf + eps) = F(r_{N+1} + eps) = nan F(r_i + eps) = F(r_i - eps)

Recursive Formula:

F_0 = 0 F_k = F_{k-1} + int_{r_{k-1}+eps}^{r_{k}-eps}

xhorizon.tortoise.tortoise.integrate(func, a, b)

Wrapper for definite integration using scipy.integrate.quad().

xhorizon.tortoise.tortoise.which_interval(r, rj, asint=True)

Given the radii r_j, determine which interval I_j a radius belongs to. Return nan if error. Inputs are the array rj and an arbitrary length array r. Output is an array j of equal length as r giving the corresponding interval for each radius in array r.

xhorizon.tortoise.tortoise.rspace0(r0, r1, eps, npoints=500)

Provide a dense array of r values for interpolating F and Finv. Must have extra values near exponential tails to smoothly interpolate there.

xhorizon.tortoise.tortoise.rspace1(rj, eps, npoints=500)

Like rspace0(), but gives values over all intervals I_j simultaneously.

xhorizon.tortoise.tortoise.first_trapped_j(f, rj)

xhorizon.tortoise.tortoise.test1()

Tests whether the function scipy.quad(h,a,b) obeys int_a^b = - int_b^a, even when endpoints approach singular points of the integral. This would be unlikely for numerical integration of an ODE, but for this area-based quadrature it appears to be true. In fact, it appears to be true even when the integral method provides a warning. Since this is true, integrals of the form int_{rj+eps}^b are admissible, and using a less extreme integration point in the middle of the interval will not increase accuracy.

xhorizon.tortoise.tortoise.test2()

Demonstrate the functionality of F_refpoints.

xhorizon.tortoise.tortoise.test3()

Test of which_interval().

xhorizon.tortoise.tortoise.test4()

Demonstrate the functionality of F_by_integration.

xhorizon.tortoise.tortoise.test5()

Demonstrate the functionality of rspace0().

xhorizon.tortoise.tortoise.test6()

Demonstrate the functionality of rspace1().

xhorizon.tortoise.tortoise.test7()

Demonstrate the functionality of create_reference().

xhorizon.tortoise.tortoise.test8()

Demonstrate the functionality of F_by_interp.make_F().

xhorizon.tortoise.tortoise.test9()

Demonstrate the functionality of F_by_interp.make_Finv().