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.utils.baseclasses.TrajectoryBase(*args, **kwargs)

Bases: 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.

property citation: Return citation for this class

classmethod get_inspiral(*args, **kwargs)

Inspiral Generator

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

Returns:

t, p, e, Phi_phi, Phi_r, flux with shape:: (params, traj length).

Return type:

2D double np.ndarray

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={}, DENSE_STEPPING=0, max_init_len=1000, upsample=False, err=1e-10, use_rk4=False, fix_t=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 (list) – 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, optional) – 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 (double, optional) – Time step for output waveform in seconds. Also sets initial step for integrator. Default is 10.0.
T (double, optional) – Total observation time in years. Sets the maximum time for the integrator to run. Default is 1.0.
new_t (1D np.ndarray, optional) – 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, optional) – If using upsampling, spline_kwargs provides the kwargs desired for scipy.interpolate.CubicSpline. Default is {}.
DENSE_STEPPING (int, optional) – If 1, the trajectory used in the integrator will be densely stepped at steps of dt. If 0, the integrator will determine its stepping. Default is 0.
max_init_len (int, optional) – Sets the allocation of memory for trajectory parameters. This should be the maximum length expected for a trajectory. Trajectories with default settings will be ~100 points. Default is 1000.
upsample (bool, optional) – If True, upsample, with a cubic spline, the trajectories from 0 to T in steps of dt. Default is False.
err (double, optional) – 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 (bool, optional) – 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.
use_rk4 (bool, optional) – If True, use rk4 integrator from gsl. If False, use rk8. Default is False (rk8).
**kwargs (dict, optional) – kwargs passed to trajectory module. Default is {}.

Returns:

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

Return type:

tuple

Raises:

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

Generic Inspiral Generator from C/C++ functions

class few.trajectory.inspiral.EMRIInspiral(*args, func=None, enforce_schwarz_sep=False, test_new_version=True, **kwargs)

Bases: TrajectoryBase

EMRI trajectory module.

This module implements generic trajectories by integrating with an RK8 integrator. It can also adjust the output time-spacing using cubic spline interpolation. Additionally, it gives the option for a dense trajectory, which integrates the trajectory at the user-defined timestep.

The trajectory operates on generic ODE functions that are defined in src/ode_base.cc and include/ode_base.hh. The ODE can be either a function or a C++ class that has constructor function, destructor function, and function for get the derivatives called deriv_func. Implemented examples for the Schwarzchild eccentric flux-based trajectory (ODE class) and the 5PN trajecotry (ODE function) can be found in the ode_base files. The ODE as a function or the deriv_func method must take an exact set of arguments:

__deriv__
func(double* pdot, double* edot, double* xdot,
     double* Omega_phi, double* Omega_theta, double* Omega_r,
     double epsilon, double a, double p, double e, double Y, double* additional_args)

pdot, edot, xdot, Omega_phi, Omega_theta The __deriv__ decorator let’s the installer know which functions are actually the derivative functions, in case there are other auxillary functions in the file. The user then uses #define lines to indicate to the code limitations or settings specific to that ODE. See the tutorial documentation for more detail.

Parameters:

func (str) – 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 the options for this argument, use few.utils.utility.get_ode_function_options(). Stock options include "SchwarzEccFlux" and "pn5".
enforce_schwarz_sep (bool, optional) – Enforce the separatrix of Schwarzschild spacetime. This helps to midigate issues at higher spin and/or higher eccentricity where the PN approximations are more likely to fail. Default is False.
*args (list) – Any arguments for parent class few.utils.baseclasses.TrajectoryBase or class few.utils.baseclasses.Pn5AAK.
**kwargs (dict) – Any keyword arguments for parent class few.utils.baseclasses.TrajectoryBase or class few.utils.baseclasses.Pn5AAK.

num_add_args

Number of additional arguments for the ODE function.

Type:: int

background

“Either Schwarzschild” or “Kerr”.

Type:: str

equatorial

True if equatorial orbit.

Type:: bool

circular

True if circular orbit.

Type:: bool

convert_Y

If the ODE is integrated in \(Y\) rather than \(x_I\).

Type:: bool

files

List of files necessary for this ODE.

Type:: list

citations

list of additional citations for this ODE.

Type:: list

enforce_schwarz_sep

Enforce the separatrix of Schwarzschild spacetime.

Type:: bool

inspiral_generator

Inspiral C/C++ wrapped function.

Type:: func

func

ODE function name.

Type:: str

specific_kwarg_keys

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

Type:: dict

Raises:

ValueError – func kwarg not given or not available.
ValueError – File necessary for ODE not found.

attributes_EMRIInspiral()

inspiral_generator

C++ class for inspiral trajectory generation.

Type:: obj

specific_kwarg_keys

specific kwargs from few.utils.baseclasses.TrajectoryBase that apply to this inspiral generator.

Type:: list

property citation: Return citation for this class

__call__(*args, in_coordinate_time=True, dt=10.0, T=1.0, new_t=None, spline_kwargs={}, DENSE_STEPPING=0, max_init_len=1000, upsample=False, err=1e-10, use_rk4=False, fix_t=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 (list) – 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, optional) – 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 (double, optional) – Time step for output waveform in seconds. Also sets initial step for integrator. Default is 10.0.
T (double, optional) – Total observation time in years. Sets the maximum time for the integrator to run. Default is 1.0.
new_t (1D np.ndarray, optional) – 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, optional) – If using upsampling, spline_kwargs provides the kwargs desired for scipy.interpolate.CubicSpline. Default is {}.
DENSE_STEPPING (int, optional) – If 1, the trajectory used in the integrator will be densely stepped at steps of dt. If 0, the integrator will determine its stepping. Default is 0.
max_init_len (int, optional) – Sets the allocation of memory for trajectory parameters. This should be the maximum length expected for a trajectory. Trajectories with default settings will be ~100 points. Default is 1000.
upsample (bool, optional) – If True, upsample, with a cubic spline, the trajectories from 0 to T in steps of dt. Default is False.
err (double, optional) – 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 (bool, optional) – 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.
use_rk4 (bool, optional) – If True, use rk4 integrator from gsl. If False, use rk8. Default is False (rk8).
**kwargs (dict, optional) – kwargs passed to trajectory module. Default is {}.

Returns:

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

Return type:

tuple

Raises:

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

get_inspiral(M, mu, a, p0, e0, x0, *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.

This class can be used on its own. However, it is generally accessed through the __call__ method associated with its base class: (few.utils.baseclasses.TrajectoryBase).

Parameters:

M (double) – Mass of massive black hole in solar masses.
mu (double) – Mass of compact object in solar masses.
a (double) – Dimensionless spin of massive black hole.
p0 (double) – Initial semi-latus rectum in terms units of M (p/M).
e0 (double) – Initial eccentricity (dimensionless).
x0 (double) – Initial \(\cos{\iota}\). Note: This value is different from \(x_I\)
waveforms. (used in the relativistic) –
*args (list, placeholder) – Added for flexibility.
Phi_phi0 (double, optional) – Initial phase for \(\Phi_\phi\). Default is 0.0.
Phi_theta0 (double, optional) – Initial phase for \(\Phi_\Theta\). Default is 0.0.
Phi_r0 (double, optional) – Initial phase for \(\Phi_r\). Default is 0.0.
**kwargs (dict, optional) – kwargs passed from parent.

Returns:

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

Return type:

tuple