Trajectory Package

The trajectory package houses modules that turn initial orbital parameters into phase-space trajectories (orbital phases and orbital parameters). These are determined by numerical integrators that interpolate over the relevant quantities.

class few.trajectory.base.TrajectoryBase(*args, **kwargs)

Bases: Citable, ABC

Base class used for trajectory modules.

This class provides a flexible interface to various trajectory implementations. Specific arguments to each trajectory can be found with each associated trajectory module discussed below.

abstractmethod classmethod get_inspiral(*args, **kwargs)

Inspiral Generator

@classmethod that requires a child class to have a get_inspiral method.

Raises:

NotImplementedError – The child class does not have this method.

__call__(*args, in_coordinate_time=True, dt=10.0, T=1.0, new_t=None, spline_kwargs=None, DENSE_STEPPING=False, buffer_length=1000, upsample=False, err=1e-11, fix_t=False, integrate_backwards=False, **kwargs)

Call function for trajectory interface.

This is the function for calling the creation of the trajectory. Inputs define the output time spacing.

Parameters:

  • *args – Input of variable number of arguments specific to the inspiral model (see the trajectory class’ get_inspiral method). Important Note: M must be the first parameter of any model that uses this base class.

  • in_coordinate_time (bool) – If True, the trajectory will be outputted in coordinate time. If False, the trajectory will be outputted in units of M. Default is True.

  • dt (float) – Time step for output waveform in seconds. Also sets initial step for integrator. Default is 10.0.

  • T (float) – Total observation time in years. Sets the maximum time for the integrator to run. Default is 1.0.

  • new_t (ndarray | None) – If given, this represents the final time array at which the trajectory is analyzed. This is performed by using a cubic spline on the integrator output. Default is None.

  • spline_kwargs (dict | None) – If using upsampling, spline_kwargs provides the kwargs desired for scipy.interpolate.CubicSpline. Default is {}.

  • DENSE_STEPPING (bool) – If True, the trajectory used in the integrator will be densely stepped at steps of dt. If False, the integrator will determine its stepping. Default is False.

  • buffer_length (int) – Sets the allocation of memory for trajectory parameters. This should be the maximum length expected for a trajectory. If it is reached, output arrays will be extended, but this is more expensive than allocating a larger array initially. Trajectories with default settings will be ~100 points. Default is 1000.

  • upsample (bool) – If True, upsample, with a cubic spline, the trajectories from 0 to T in steps of dt. Default is False.

  • err (float) – Tolerance for integrator. Default is 1e-10. Decreasing this parameter will give more steps over the trajectory, but if it is too small, memory issues will occur as the trajectory length will blow up. We recommend not adjusting this parameter.

  • fix_T – If upsampling, this will affect excess points in the t array. If True, it will shave any excess on the trajectories arrays where the time is greater than the overall time of the trajectory requested.

  • **kwargs – kwargs passed to trajectory module. Default is {}.

  • fix_t (bool)

  • integrate_backwards (bool)

Returns:

Tuple of (t, p, e, Phi_phi, Phi_r, flux_norm).

Raises:

ValueError – If input parameters are not allowed in this model.

Return type:

tuple[ndarray]

classmethod citation()

Return the module references as a printable BibTeX string.

Return type:

str

classmethod module_references()

Method implemented by each class to define its list of references

Return type:

List[REFERENCE | str]

Generic Inspiral Generator

class few.trajectory.inspiral.EMRIInspiral(*args, func, integrate_constants_of_motion=False, enforce_schwarz_sep=False, convert_to_pex=True, rootfind_separatrix=True, **kwargs)

Bases: TrajectoryBase

EMRI trajectory module.

This module implements generic trajectories by integrating with a DOP853 Runge-Kutta integrator (see few.trajectory.integrate). Both adaptive (default) and fixed timesteps are supported. For an adaptive integration, a continuous solution is generated that can be evaluated at any point in time.

The trajectory operates on generic ODE functions that are defined in few.trajectory.ode. Flux-based trajectories (which interpolate data grids) can be found in few.trajectory.ode.flux. A generic Post-Newtonian trajectory is also provided in few.trajectory.ode.pn5. Users can subclass few.trajectory.ode.base.ODEBase to define their own ODE functions. See the documentation for examples on how to do this.

Parameters:

  • func (str | Type[ODEBase]) – Function name for the ode to use in the integration. This must be given as a keyword argument, even though it is required. To get inbuilt stock options for this argument, check few.trajectory.ode._STOCK_TRAJECTORY_OPTIONS.

  • integrate_constants_of_motion (bool) – If True, the trajectory will integrate the constants of motion (E, L, Q). Default is False.

  • enforce_schwarz_sep (bool) – Enforce the separatrix of Schwarzschild spacetime. This can mitigate issues at higher spin and/or higher eccentricity where (e.g.) PN approximations become increasingly inaccurate. Default is False.

  • convert_to_pex (bool) – Convert the output from ELQ to pex coordinates (only used if integrating constants of motion). Default is True.

  • rootfind_separatrix (bool) – Finish trajectory by performing a numerical root-finding operation to place the final point of the trajectory. If False, performs Euler integration to the final point. Default is True.

  • *args – Any arguments for parent class few.trajectory.base.TrajectoryBase

  • **kwargs – Any keyword arguments for the integrator and ODE classes few.trajectory.integrate.Integrate and few.trajectory.ode.ODEBase.

Raises:

  • ValueError – func kwarg not given or not available.

  • ValueError – File necessary for ODE not found.

inspiral_generator

Integrator class for the trajectory.

Type:

class

specific_kwarg_keys

Specific keywords that need to transferred to the inspiral function that can be adjusted with each call.

Type:

dict

classmethod module_references()

Return citations related to this module

Return type:

list[REFERENCE]

__call__(*args, in_coordinate_time=True, dt=10.0, T=1.0, new_t=None, spline_kwargs=None, DENSE_STEPPING=False, buffer_length=1000, upsample=False, err=1e-11, fix_t=False, integrate_backwards=False, **kwargs)

Call function for trajectory interface.

This is the function for calling the creation of the trajectory. Inputs define the output time spacing.

Parameters:

  • *args – Input of variable number of arguments specific to the inspiral model (see the trajectory class’ get_inspiral method). Important Note: M must be the first parameter of any model that uses this base class.

  • in_coordinate_time (bool) – If True, the trajectory will be outputted in coordinate time. If False, the trajectory will be outputted in units of M. Default is True.

  • dt (float) – Time step for output waveform in seconds. Also sets initial step for integrator. Default is 10.0.

  • T (float) – Total observation time in years. Sets the maximum time for the integrator to run. Default is 1.0.

  • new_t (ndarray | None) – If given, this represents the final time array at which the trajectory is analyzed. This is performed by using a cubic spline on the integrator output. Default is None.

  • spline_kwargs (dict | None) – If using upsampling, spline_kwargs provides the kwargs desired for scipy.interpolate.CubicSpline. Default is {}.

  • DENSE_STEPPING (bool) – If True, the trajectory used in the integrator will be densely stepped at steps of dt. If False, the integrator will determine its stepping. Default is False.

  • buffer_length (int) – Sets the allocation of memory for trajectory parameters. This should be the maximum length expected for a trajectory. If it is reached, output arrays will be extended, but this is more expensive than allocating a larger array initially. Trajectories with default settings will be ~100 points. Default is 1000.

  • upsample (bool) – If True, upsample, with a cubic spline, the trajectories from 0 to T in steps of dt. Default is False.

  • err (float) – Tolerance for integrator. Default is 1e-10. Decreasing this parameter will give more steps over the trajectory, but if it is too small, memory issues will occur as the trajectory length will blow up. We recommend not adjusting this parameter.

  • fix_T – If upsampling, this will affect excess points in the t array. If True, it will shave any excess on the trajectories arrays where the time is greater than the overall time of the trajectory requested.

  • **kwargs – kwargs passed to trajectory module. Default is {}.

  • fix_t (bool)

  • integrate_backwards (bool)

Returns:

Tuple of (t, p, e, Phi_phi, Phi_r, flux_norm).

Raises:

ValueError – If input parameters are not allowed in this model.

Return type:

tuple[ndarray]

classmethod citation()

Return the module references as a printable BibTeX string.

Return type:

str

get_inspiral(M, mu, a, y1, y2, y3, *args, Phi_phi0=0.0, Phi_theta0=0.0, Phi_r0=0.0, **kwargs)

Generate the inspiral.

This is the function for calling the creation of the trajectory. Inputs define the output time spacing.

Parameters:

  • M (float) – Mass of massive black hole in solar masses.

  • mu (float) – Mass of compact object in solar masses.

  • a (float) – Dimensionless spin of massive black hole.

  • p0 – Initial semi-latus rectum in terms units of M (p/M).

  • e0 – Initial eccentricity (dimensionless).

  • x0 – Initial \(\cos{\iota}\). Note: This value is different from \(x_I\)

  • waveforms. (used in the relativistic)

  • *args – Added for flexibility.

  • Phi_phi0 (float) – Initial phase for \(\Phi_\phi\). Default is 0.0.

  • Phi_theta0 (float) – Initial phase for \(\Phi_\Theta\). Default is 0.0.

  • Phi_r0 (float) – Initial phase for \(\Phi_r\). Default is 0.0.

  • **kwargs – kwargs passed from parent.

  • y1 (float)

  • y2 (float)

  • y3 (float)

Returns:

Tuple of (t, p, e, x, Phi_phi, Phi_theta, Phi_r).

Return type:

tuple[ndarray]

get_rhs_ode(M, mu, a, y1, y2, y3, *args, Phi_phi0=0.0, Phi_theta0=0.0, Phi_r0=0.0, **kwargs)

Compute the right hand side of the ordinary differential equation.

This is a convenience function for interfacing with the call method of the ODE class.

Parameters:

  • M (float) – Mass of massive black hole in solar masses.

  • mu (float) – Mass of compact object in solar masses.

  • a (float) – Dimensionless spin of massive black hole.

  • p0 – Initial semi-latus rectum in terms units of M (p/M).

  • e0 – Initial eccentricity (dimensionless).

  • x0 – Initial \(\cos{\iota}\). Note: This value is different from \(x_I\)

  • waveforms. (used in the relativistic)

  • *args – Added for flexibility.

  • Phi_phi0 (float) – Initial phase for \(\Phi_\phi\). Default is 0.0.

  • Phi_theta0 (float) – Initial phase for \(\Phi_\Theta\). Default is 0.0.

  • Phi_r0 (float) – Initial phase for \(\Phi_r\). Default is 0.0.

  • **kwargs – kwargs passed from parent.

  • y1 (float)

  • y2 (float)

  • y3 (float)

Returns:

Tuple of (t, p, e, x, Phi_phi, Phi_theta, Phi_r).

Return type:

tuple[ndarray]

ODE Integrators

class few.trajectory.integrate.Integrate(func, integrate_constants_of_motion=False, buffer_length=1000, enforce_schwarz_sep=False, **kwargs)

Bases: object

Custom integrator class.

Flexible integration options. # TODO: discuss options

Parameters:

  • func (Type[ODEBase]) – ODE base function to integrate.

  • integrate_constants_of_motion (bool) – If True, integrate in ELQ rather than orbital parameters.

  • buffer_length (int) – Initial buffer length for trajectory. Will adjust itself if needed.

  • enforce_schwarz_sep (bool) – If True, enforce the Schwarzschild separatrix as the separatrix. \(p_s = 6 + 2e\).

  • **kwargs – Keyword arguments for the ODE function, func.

property nparams: int

Dimensionality of ODE

property num_add_args: int

Number of additional arguments to the ODE

property convert_Y

Convert to Y if needed.

property background

Spacetime background (spin or no spin)

property equatorial

Orbit limited to equatorial plane.

property circular

Circular orbit.

property integrate_constants_of_motion

Integrating in ELQ.

property separatrix_buffer_dist

Buffer distance from separatrix.

distance_to_outer_boundary(y)

Distance to outer boundary of interpolation grid.

take_step(t, h, y)

Take a step of the integrator.

Parameters:

  • t (float) – Time.

  • h (float) – Step size.

  • y (ndarray) – Current position of integrator.

Returns:

(new time, new step size, new position)

Return type:

Tuple[float, float, ndarray]

log_failed_step()

Add to and check failed step count.

Raises:

ValueError – Too many failed tries.

integrate(t0, y0)

Integrate from (t0, y0).

Parameters:

  • t0 (float) – Initial time.

  • y0 (ndarray) – Initial position.

Returns:

(Time array, Position array).

Return type:

Tuple[ndarray, ndarray]

action_function(t, y)

Act on the integrator.

Parameters:

  • t (float) – Time.

  • y (ndarray) – Current position of integrator.

Return type:

None

initialize_integrator(err=1e-11, DENSE_STEPPING=False, integrate_backwards=False, **kwargs)

Setup the integrator.

Parameters:

  • err (float) – Absolute tolerance of the integrator.

  • DENSE_STEPPING (bool) – If True, use fixed stepping.

  • integrate_backwards (bool) – If True, integrate backwards.

  • **kwargs – For future interoperability.

property trajectory: ndarray

Trajectory array.

property integrator_t_cache: ndarray

Time array.

property integrator_spline_coeff: ndarray

Spline coefficients from dopr backend.

save_point(t, y, spline_output=None)

Save point in trajectory array.

Parameters:

  • t (float) – Time.

  • y (ndarray) – Current position of integrator.

  • spline_output (ndarray | None) – Spline coefficients from the backend.

Return type:

None

eval_integrator_spline(t_new)

Evaluate integration at new time array.

Parameters:

t_new (ndarray) – New time array.

Returns:

New trajectory.

Return type:

ndarray

eval_integrator_derivative_spline(t_new, order=1)

Evaluate integration derivatives at new time array.

Parameters:

  • t_new (ndarray) – New time array.

  • order (int) – Order of derivative to evaluate. Defaults to 1.

Returns:

New trajectory derivatives.

run_inspiral(M, mu, a, y0, additional_args, T=1.0, dt=10.0, **kwargs)

Run inspiral integration.

Parameters:

  • M (float) – Larger mass in solar masses.

  • mu (float) – Small mass in solar masses.

  • a (float) – Dimensionless spin of central black hole.

  • y0 (ndarray) – Initial set of coordinates for integration.

  • additional_args (list | ndarray)

  • T (float)

  • dt (float)

Returns:

Trajectory array for integrated coefficients.

Return type:

ndarray

stop_integrate_check(t, y)
Stop the inspiral when close to the separatrix (forwards integration)

or when close to the outer grid boundary (backwards integration).

Parameters:

  • t (float) – Time.

  • y (ndarray) – Current position of integrator.

Returns:

True if integration should be stopped. False otherwise.

Return type:

bool

inner_func_forward(t_step)

Evaluates the distance from the inner boundary at t=t_step. Also caches the state of the system as self._y_inner_cache.

inner_func_backward(t_step)

Evaluates the distance from the outer boundary at t=t_step. Also caches the state of the system as self._y_inner_cache.

finishing_function(t, y)

This function is called when the integrator has finished due to reaching a stopping condition. The function identifies the stopping condition and places the final point at the stopping boundary accordingly.

Parameters:
classmethod get_pex(y)

Handles integrator-specific conversion from y to pex and returns the result.

Parameters:

y (ndarray)

Return type:

ndarray

class few.trajectory.integrate.APEXIntegrate(func, integrate_constants_of_motion=False, buffer_length=1000, enforce_schwarz_sep=False, **kwargs)

Bases: Integrate

An subclass of Integrate for integrating in pex coordinates.

Parameters:

  • func (Type[ODEBase])

  • integrate_constants_of_motion (bool)

  • buffer_length (int)

  • enforce_schwarz_sep (bool)

get_pex(y)

Handles integrator-specific conversion from y to pex and returns the result.

action_function(t, y)

Act on the integrator.

Parameters:

  • t (float) – Time.

  • y (ndarray) – Current position of integrator.

Return type:

None

property background

Spacetime background (spin or no spin)

property circular

Circular orbit.

property convert_Y

Convert to Y if needed.

distance_to_outer_boundary(y)

Distance to outer boundary of interpolation grid.

property equatorial

Orbit limited to equatorial plane.

eval_integrator_derivative_spline(t_new, order=1)

Evaluate integration derivatives at new time array.

Parameters:

  • t_new (ndarray) – New time array.

  • order (int) – Order of derivative to evaluate. Defaults to 1.

Returns:

New trajectory derivatives.

eval_integrator_spline(t_new)

Evaluate integration at new time array.

Parameters:

t_new (ndarray) – New time array.

Returns:

New trajectory.

Return type:

ndarray

finishing_function(t, y)

This function is called when the integrator has finished due to reaching a stopping condition. The function identifies the stopping condition and places the final point at the stopping boundary accordingly.

Parameters:
initialize_integrator(err=1e-11, DENSE_STEPPING=False, integrate_backwards=False, **kwargs)

Setup the integrator.

Parameters:

  • err (float) – Absolute tolerance of the integrator.

  • DENSE_STEPPING (bool) – If True, use fixed stepping.

  • integrate_backwards (bool) – If True, integrate backwards.

  • **kwargs – For future interoperability.

inner_func_backward(t_step)

Evaluates the distance from the outer boundary at t=t_step. Also caches the state of the system as self._y_inner_cache.

inner_func_forward(t_step)

Evaluates the distance from the inner boundary at t=t_step. Also caches the state of the system as self._y_inner_cache.

integrate(t0, y0)

Integrate from (t0, y0).

Parameters:

  • t0 (float) – Initial time.

  • y0 (ndarray) – Initial position.

Returns:

(Time array, Position array).

Return type:

Tuple[ndarray, ndarray]

property integrate_constants_of_motion

Integrating in ELQ.

property integrator_spline_coeff: ndarray

Spline coefficients from dopr backend.

property integrator_t_cache: ndarray

Time array.

log_failed_step()

Add to and check failed step count.

Raises:

ValueError – Too many failed tries.

property nparams: int

Dimensionality of ODE

property num_add_args: int

Number of additional arguments to the ODE

run_inspiral(M, mu, a, y0, additional_args, T=1.0, dt=10.0, **kwargs)

Run inspiral integration.

Parameters:

  • M (float) – Larger mass in solar masses.

  • mu (float) – Small mass in solar masses.

  • a (float) – Dimensionless spin of central black hole.

  • y0 (ndarray) – Initial set of coordinates for integration.

  • additional_args (list | ndarray)

  • T (float)

  • dt (float)

Returns:

Trajectory array for integrated coefficients.

Return type:

ndarray

save_point(t, y, spline_output=None)

Save point in trajectory array.

Parameters:

  • t (float) – Time.

  • y (ndarray) – Current position of integrator.

  • spline_output (ndarray | None) – Spline coefficients from the backend.

Return type:

None

property separatrix_buffer_dist

Buffer distance from separatrix.

stop_integrate_check(t, y)
Stop the inspiral when close to the separatrix (forwards integration)

or when close to the outer grid boundary (backwards integration).

Parameters:

  • t (float) – Time.

  • y (ndarray) – Current position of integrator.

Returns:

True if integration should be stopped. False otherwise.

Return type:

bool

take_step(t, h, y)

Take a step of the integrator.

Parameters:

  • t (float) – Time.

  • h (float) – Step size.

  • y (ndarray) – Current position of integrator.

Returns:

(new time, new step size, new position)

Return type:

Tuple[float, float, ndarray]

property trajectory: ndarray

Trajectory array.

class few.trajectory.integrate.AELQIntegrate(func, integrate_constants_of_motion=False, buffer_length=1000, enforce_schwarz_sep=False, **kwargs)

Bases: Integrate

An subclass of Integrate for integrating in ELQ coordinates.

Parameters:

  • func (Type[ODEBase])

  • integrate_constants_of_motion (bool)

  • buffer_length (int)

  • enforce_schwarz_sep (bool)

get_pex(y)

Handles integrator-specific conversion from y to pex and returns the result.

action_function(t, y)

Act on the integrator.

Parameters:

  • t (float) – Time.

  • y (ndarray) – Current position of integrator.

Return type:

None

property background

Spacetime background (spin or no spin)

property circular

Circular orbit.

property convert_Y

Convert to Y if needed.

distance_to_outer_boundary(y)

Distance to outer boundary of interpolation grid.

property equatorial

Orbit limited to equatorial plane.

eval_integrator_derivative_spline(t_new, order=1)

Evaluate integration derivatives at new time array.

Parameters:

  • t_new (ndarray) – New time array.

  • order (int) – Order of derivative to evaluate. Defaults to 1.

Returns:

New trajectory derivatives.

eval_integrator_spline(t_new)

Evaluate integration at new time array.

Parameters:

t_new (ndarray) – New time array.

Returns:

New trajectory.

Return type:

ndarray

finishing_function(t, y)

This function is called when the integrator has finished due to reaching a stopping condition. The function identifies the stopping condition and places the final point at the stopping boundary accordingly.

Parameters:
initialize_integrator(err=1e-11, DENSE_STEPPING=False, integrate_backwards=False, **kwargs)

Setup the integrator.

Parameters:

  • err (float) – Absolute tolerance of the integrator.

  • DENSE_STEPPING (bool) – If True, use fixed stepping.

  • integrate_backwards (bool) – If True, integrate backwards.

  • **kwargs – For future interoperability.

inner_func_backward(t_step)

Evaluates the distance from the outer boundary at t=t_step. Also caches the state of the system as self._y_inner_cache.

inner_func_forward(t_step)

Evaluates the distance from the inner boundary at t=t_step. Also caches the state of the system as self._y_inner_cache.

integrate(t0, y0)

Integrate from (t0, y0).

Parameters:

  • t0 (float) – Initial time.

  • y0 (ndarray) – Initial position.

Returns:

(Time array, Position array).

Return type:

Tuple[ndarray, ndarray]

property integrate_constants_of_motion

Integrating in ELQ.

property integrator_spline_coeff: ndarray

Spline coefficients from dopr backend.

property integrator_t_cache: ndarray

Time array.

log_failed_step()

Add to and check failed step count.

Raises:

ValueError – Too many failed tries.

property nparams: int

Dimensionality of ODE

property num_add_args: int

Number of additional arguments to the ODE

run_inspiral(M, mu, a, y0, additional_args, T=1.0, dt=10.0, **kwargs)

Run inspiral integration.

Parameters:

  • M (float) – Larger mass in solar masses.

  • mu (float) – Small mass in solar masses.

  • a (float) – Dimensionless spin of central black hole.

  • y0 (ndarray) – Initial set of coordinates for integration.

  • additional_args (list | ndarray)

  • T (float)

  • dt (float)

Returns:

Trajectory array for integrated coefficients.

Return type:

ndarray

save_point(t, y, spline_output=None)

Save point in trajectory array.

Parameters:

  • t (float) – Time.

  • y (ndarray) – Current position of integrator.

  • spline_output (ndarray | None) – Spline coefficients from the backend.

Return type:

None

property separatrix_buffer_dist

Buffer distance from separatrix.

stop_integrate_check(t, y)
Stop the inspiral when close to the separatrix (forwards integration)

or when close to the outer grid boundary (backwards integration).

Parameters:

  • t (float) – Time.

  • y (ndarray) – Current position of integrator.

Returns:

True if integration should be stopped. False otherwise.

Return type:

bool

take_step(t, h, y)

Take a step of the integrator.

Parameters:

  • t (float) – Time.

  • h (float) – Step size.

  • y (ndarray) – Current position of integrator.

Returns:

(new time, new step size, new position)

Return type:

Tuple[float, float, ndarray]

property trajectory: ndarray

Trajectory array.

ODE Classes

Contains the ODEBase baseclass that handles evaluating the ODE

class few.trajectory.ode.base.ODEBase(*args, use_ELQ=False, **kwargs)

Bases: object

A baseclass for handling the evaluation of ODE derivatives in the trajectory module.

To define a new trajectory function, subclass this function and define evaluate_rhs. Make sure to update the relevant class attributes as well. See the documentation for examples on how to do this.

use_ELQ

If True, the ODE will take as input (and output derivatives of) the integrals of motion (E, L, Q). Defaults to False.

Type:

bool

num_add_args

Number of additional arguments being passed to the ODE function.

Type:

int

property convert_Y

If True, the inclination coordinate is assumed to be Y and is converted accordingly. Defaults to False.

property equatorial

If True, the inclination coordinate is assumed to be +/- 1. Defaults to False.

property circular

If True, the eccentricity coordinate is assumed to be 0. Defaults to False.

property supports_ELQ

If True, this ODE can take as input (and output derivatives of) the integrals of motion (E, L, Q) if initialised with use_ELQ=True. Defaults to False.

property background

A string describing the background spacetime. Either “Kerr” or “Schwarzschild”. Defaults to “Kerr”.

property separatrix_buffer_dist

A float describing the value of “p” at which the trajectory should terminate at, with respect to the separatrix. A value of 0 would mean that the trajectory terminates at the separatrix. Defaults to 0.05

property nparams

An integer describing the number of parameters this ODE will integrate. Defaults to 6 (three orbital elements, three orbital phases).

property flux_output_convention

A string describing the coordinate convention of the fluxes for this model, as output by evaluate_rhs. These are either “pex” or “ELQ”. If “ELQ”, a Jacobian transformation is performed if the output derivatives of the model are expected to be in the “pex” convention. Defaults to “ELQ”.

For models that do not perform interpolation to generate fluxes (e.g., PN5), this property is not accessed.

evaluate_rhs(y, **kwargs)

This function evaluates the right-hand side of the ODE at the point y. An ODE model can be defined by subclassing the ODEBase class and implementing this method.

Parameters:

y (ndarray)

Return type:

NotImplementedError

modify_rhs_before_Jacobian(ydot, y, **kwargs)

This function allows the user to modify the right-hand side of the ODE before the Jacobian transform is applied. This is particularly useful if the user wishes to apply modifications to fluxes of the integrals of motion “ELQ”, but integrate a trajectory in terms of “pex”.

By default, this function returns the input right-hand side unchanged.

Parameters:

  • ydot (ndarray)

  • y (ndarray)

Return type:

ndarray

modify_rhs(ydot, y, **kwargs)

This function allows the user to modify the right-hand side of the ODE after any required Jacobian transforms have been applied.

By default, this function returns the input right-hand side unchanged.

Parameters:

  • ydot (ndarray)

  • y (ndarray)

Return type:

ndarray

interpolate_flux_grids(*args)

This function handles the interpolation of the fluxes from the precomputed grids, including parameter transformations. Each stock model implements this function to handle the specifics of their own interpolants. To easily incorporate interpolated fluxes into their own models, users can subclass the stock models; the interpolated fluxes can then be accessed from evaluate_rhs by calling this function.

This method should also handle checking that the input parameters are within the bounds of the precomputed grids. Failure to do so may result in erroneous behaviour during trajectory evaluation in which fluxes are extrapolated.

Return type:

NotImplementedError

distance_to_outer_boundary(y)

This function returns the distance to the outer boundary of the interpolation grid. This is necessary for backwards integration, which performs root-finding to ensure that the trajectory ends on this outer boundary. Root-finding is initiated when this function returns a negative value.

Each stock model implements this function to handle the specifics of their own interpolants. For models that do not use interpolation, this function returns a positive constant (such that root-finding never occurs) and does not need to be implemented.

Parameters:

y (ndarray)

Return type:

float

get_pex(y)

This function converts the integrals of motion (E, L, Q) to the orbital elements (p, e, x), if required.

Parameters:

y (ndarray)

Return type:

tuple[float]

cache_values_and_check_bounds(y)

This function checks the input points to ensure they are within the physical bounds of the inspiral parameter space. These checks include ensuring that the separatrix has not been crossed, and that the eccentricity is within bounds.

Returns a boolean indicating whether the input was in bounds.

Parameters:

y (ndarray)

Return type:

bool

__call__(y, out=None, scale_by_eps=False, **kwargs)

Call self as a function.

Parameters:

  • y (list | ndarray)

  • out (ndarray | None)

  • kwargs (dict | None)

Return type:

ndarray

class few.trajectory.ode.flux.SchwarzEccFlux(*args, use_ELQ=False, **kwargs)

Bases: ODEBase

Schwarzschild eccentric flux ODE.

Parameters:

use_ELQ (bool) – If True, the ODE will output derivatives of the orbital elements of (E, L, Q). Defaults to False.

property supports_ELQ

If True, this ODE can take as input (and output derivatives of) the integrals of motion (E, L, Q) if initialised with use_ELQ=True. Defaults to False.

distance_to_outer_boundary(y)

This function returns the distance to the outer boundary of the interpolation grid. This is necessary for backwards integration, which performs root-finding to ensure that the trajectory ends on this outer boundary. Root-finding is initiated when this function returns a negative value.

Each stock model implements this function to handle the specifics of their own interpolants. For models that do not use interpolation, this function returns a positive constant (such that root-finding never occurs) and does not need to be implemented.

interpolate_flux_grids(p, e, Omega_phi)

This function handles the interpolation of the fluxes from the precomputed grids, including parameter transformations. Each stock model implements this function to handle the specifics of their own interpolants. To easily incorporate interpolated fluxes into their own models, users can subclass the stock models; the interpolated fluxes can then be accessed from evaluate_rhs by calling this function.

This method should also handle checking that the input parameters are within the bounds of the precomputed grids. Failure to do so may result in erroneous behaviour during trajectory evaluation in which fluxes are extrapolated.

Parameters:
Return type:

tuple[float]

evaluate_rhs(y)

This function evaluates the right-hand side of the ODE at the point y. An ODE model can be defined by subclassing the ODEBase class and implementing this method.

Parameters:

y (list[float] | ndarray)

Return type:

list[float | ndarray]

class few.trajectory.ode.flux.KerrEccEqFlux(*args, use_ELQ=False, downsample=None, **kwargs)

Bases: ODEBase

Kerr eccentric equatorial flux ODE.

Parameters:

  • use_ELQ (bool) – If True, the ODE will output derivatives of the orbital elements of (E, L, Q). Defaults to False.

  • downsample – List of two 3-tuples of integers to downsample the flux grid in u, w, z. The first list element

  • grid (refers to the inner)

  • None (the second to the outer. Useful for testing error convergence. Defaults to)

property supports_ELQ

If True, this ODE can take as input (and output derivatives of) the integrals of motion (E, L, Q) if initialised with use_ELQ=True. Defaults to False.

property flux_output_convention

A string describing the coordinate convention of the fluxes for this model, as output by evaluate_rhs. These are either “pex” or “ELQ”. If “ELQ”, a Jacobian transformation is performed if the output derivatives of the model are expected to be in the “pex” convention. Defaults to “ELQ”.

For models that do not perform interpolation to generate fluxes (e.g., PN5), this property is not accessed.

interpolate_flux_grids(p, e, x)

This function handles the interpolation of the fluxes from the precomputed grids, including parameter transformations. Each stock model implements this function to handle the specifics of their own interpolants. To easily incorporate interpolated fluxes into their own models, users can subclass the stock models; the interpolated fluxes can then be accessed from evaluate_rhs by calling this function.

This method should also handle checking that the input parameters are within the bounds of the precomputed grids. Failure to do so may result in erroneous behaviour during trajectory evaluation in which fluxes are extrapolated.

Parameters:
Return type:

tuple[float]

evaluate_rhs(y)

This function evaluates the right-hand side of the ODE at the point y. An ODE model can be defined by subclassing the ODEBase class and implementing this method.

Parameters:

y (list[float] | ndarray)

Return type:

list[float | ndarray]

class few.trajectory.ode.flux.KerrEccEqFluxLegacy(*args, use_ELQ=False, **kwargs)

Bases: ODEBase

Kerr eccentric equatorial flux ODE.

Parameters:

use_ELQ (bool) – If True, the ODE will output derivatives of the orbital elements of (E, L, Q). Defaults to False.

property supports_ELQ

If True, this ODE can take as input (and output derivatives of) the integrals of motion (E, L, Q) if initialised with use_ELQ=True. Defaults to False.

property flux_output_convention

A string describing the coordinate convention of the fluxes for this model, as output by evaluate_rhs. These are either “pex” or “ELQ”. If “ELQ”, a Jacobian transformation is performed if the output derivatives of the model are expected to be in the “pex” convention. Defaults to “ELQ”.

For models that do not perform interpolation to generate fluxes (e.g., PN5), this property is not accessed.

interpolate_flux_grids(p, e, x)

This function handles the interpolation of the fluxes from the precomputed grids, including parameter transformations. Each stock model implements this function to handle the specifics of their own interpolants. To easily incorporate interpolated fluxes into their own models, users can subclass the stock models; the interpolated fluxes can then be accessed from evaluate_rhs by calling this function.

This method should also handle checking that the input parameters are within the bounds of the precomputed grids. Failure to do so may result in erroneous behaviour during trajectory evaluation in which fluxes are extrapolated.

Parameters:
Return type:

tuple[float]

evaluate_rhs(y)

This function evaluates the right-hand side of the ODE at the point y. An ODE model can be defined by subclassing the ODEBase class and implementing this method.

Parameters:

y (list[float] | ndarray)

Return type:

list[float | ndarray]

class few.trajectory.ode.pn5.PN5(*args, use_ELQ=False, **kwargs)

Bases: ODEBase

property supports_ELQ

If True, this ODE can take as input (and output derivatives of) the integrals of motion (E, L, Q) if initialised with use_ELQ=True. Defaults to False.

property flux_output_convention

A string describing the coordinate convention of the fluxes for this model, as output by evaluate_rhs. These are either “pex” or “ELQ”. If “ELQ”, a Jacobian transformation is performed if the output derivatives of the model are expected to be in the “pex” convention. Defaults to “ELQ”.

For models that do not perform interpolation to generate fluxes (e.g., PN5), this property is not accessed.

evaluate_rhs(y)

This function evaluates the right-hand side of the ODE at the point y. An ODE model can be defined by subclassing the ODEBase class and implementing this method.

Parameters:

y (list[float] | ndarray)

Return type:

list[float | ndarray]