Amplitude Package

The amplitude package houses modules for calculating Tuekolsky amplitudes from orbital parameter trajectories. The complex amplitudes are determined with various methods documented below. Some amplitude modules have gpu capabilities. It deals with \(A_{lmkn}\) in (1).

class few.amplitude.base.AmplitudeBase

Bases: Citable

Base class used for amplitude modules.

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

Parameters:

pad_output (bool, optional) – Add zero padding to the waveform for time between plunge and observation time. Default is False.

classmethod get_amplitudes(*args, **kwargs)

Amplitude Generator

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

Raises:

NotImplementedError – The child class does not have this method.

__call__(*args, specific_modes=None, **kwargs)

Common call for Teukolsky amplitudes

This function takes the inputs the trajectory in \((p,e)\) as arrays and returns the complex amplitude of all modes to adiabatic order at each step of the trajectory.

Parameters:

  • *args – Added to create future flexibility when calling different amplitude modules. Transfers directly into get_amplitudes function.

  • specific_modes (list | ndarray | None) – Either indices or mode index tuples of modes to be generated (optional; defaults to all modes). This is not available for all waveforms.

  • **kwargs (dict, placeholder) – Added to create flexibility when calling different amplitude modules. It is not used.

Returns:

If specific_modes is a list of tuples, returns a dictionary of complex mode amplitudes. Else, returns an array of complex mode amplitudes.

Return type:

dict | 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]

ROMAN Network

class few.amplitude.romannet.RomanAmplitude(buffer_length=1000, force_backend=None, **kwargs)

Bases: AmplitudeBase, SchwarzschildEccentric

Calculate Teukolsky amplitudes with a ROMAN.

ROMAN stands for reduced-order models with artificial neurons. Please see the documentations for few.utils.baseclasses.SchwarzschildEccentric for overall aspects of these models.

A reduced order model is computed for \(A_{lmn}\). The data sets that are provided over a grid of \((p,e)\) were provided by Scott Hughes.

A feed-foward neural network is then trained on the ROM. Its weights are used in this module.

When the user inputs \((p,e)\), the neural network determines coefficients for the modes in the reduced basic and transforms it back to amplitude space.

This module is available for GPU and CPU.

Parameters:

  • buffer_length (int, optional) – Number of points to initialize for buffers. This allows the user to limit memory usage. However, if the user requests more length, a warning will be thrown and the buffer_length will be increased accordingly and arrays reallocated. Default is 1000.

  • **kwargs (dict, optional) – Keyword arguments for the base classes: few.utils.baseclasses.SchwarzschildEccentric, few.utils.baseclasses.AmplitudeBase, few.utils.baseclasses.ParallelModuleBase. Default is {}.

  • force_backend (str | Backend | None)

attributes_RomanAmplitude()
few_dir

absolute path to the FastEMRIWaveforms directory

Type:

str

break_index

length of output vector from network divded by 2. It is really the number of pairs of real and imaginary numbers.

Type:

int

neural_layer

C++ class for computing neural network operations

Type:

obj

transform_output

C++ class for transforming output from neural network in the reduced basis to the full amplitude basis.

Type:

obj

num_teuk_modes

number of teukolsky modes in the data file.

Type:

int

transform_factor_inv

Inverse of the scalar transform factor. For this model, that is 1000.0.

Type:

double

buffer_length

This class uses buffers. This is the maximum length the user expects for the input arrays.

Type:

int

weights

List of the weight matrices for each layer of the neural network. They are flattened for entry into C++ in column-major order. They have shape (dim1, dim2).

Type:

list of xp.ndarrays

bias

List of the bias arrays for each layer of the neural network. They have shape (dim2,).

Type:

list of xp.ndarrays

dim1

List of 1st dimension length in each layer.

Type:

list of int

dim2

List of 2nd dimension length in each layer.

Type:

list of int

num_layers

Number of layers in the neural network.

Type:

int

transform_matrix

Matrix for tranforming output of neural network onto original amplitude basis.

Type:

2D complex128 xp.ndarray

max_num

Figures out the maximum dimension of all weight matrices for buffers.

Type:

int

temp_mats

List that holds temporary matrices for neural network evaluation. Each layer switches between which is the input and output to properly interface with cBLAS/cuBLAS.

Type:

len-2 list of double xp.ndarrays

run_relu_arr

Array holding information about whether each layer will run the relu activation. All layers have value 1, except for the last layer with value 0.

Type:

1D int xp.ndarray

num_teuk_modes: int

Number of Teukolsky modes in the model.

classmethod module_references()

Return citations related to this module

Return type:

list[REFERENCE]

classmethod supported_backends()

List of backends supported by a parallel module by order of preference.

get_amplitudes(a, p, e, xI, *args, specific_modes=None, **kwargs)

Calculate Teukolsky amplitudes for Schwarzschild eccentric.

This function takes the inputs the trajectory in \((p,e)\) as arrays and returns the complex amplitude of all modes to adiabatic order at each step of the trajectory.

Parameters:

  • p (1D double numpy.ndarray) – Array containing the trajectory for values of the semi-latus rectum.

  • e (1D double numpy.ndarray) – Array containing the trajectory for values of the eccentricity.

  • *args (tuple, placeholder) – Added to create flexibility when calling different amplitude modules. It is not used.

  • specific_modes (list, optional) – List of tuples for (l, m, n) values desired modes. Default is None.

  • **kwargs (dict, placeholder) – Added to create flexibility when calling different amplitude modules. It is not used.

Returns:

If specific_modes is None, Teukolsky modes in shape (number of trajectory points, number of modes) dict: Dictionary with requested modes.

Return type:

2D array (double)

static CPU_ONLY()

List of supported backend for CPU only class

Return type:

list[str]

List of supported backends for CPU-recommended class with GPU support

Return type:

list[str]

static GPU_ONLY()

List of supported backends for GPU-only class

Return type:

list[str]

List of supported backends for GPU-recommended class with CPU support

Return type:

list[str]

__call__(*args, specific_modes=None, **kwargs)

Common call for Teukolsky amplitudes

This function takes the inputs the trajectory in \((p,e)\) as arrays and returns the complex amplitude of all modes to adiabatic order at each step of the trajectory.

Parameters:

  • *args – Added to create future flexibility when calling different amplitude modules. Transfers directly into get_amplitudes function.

  • specific_modes (list | ndarray | None) – Either indices or mode index tuples of modes to be generated (optional; defaults to all modes). This is not available for all waveforms.

  • **kwargs (dict, placeholder) – Added to create flexibility when calling different amplitude modules. It is not used.

Returns:

If specific_modes is a list of tuples, returns a dictionary of complex mode amplitudes. Else, returns an array of complex mode amplitudes.

Return type:

dict | ndarray

adapt_backend_kwargs(kwargs=None)

Adapt a set of keyword arguments to add/set ‘force_backend’ to current backend

Parameters:

kwargs (dict | None)

Return type:

dict

property backend: Backend

Access the underlying backend.

property backend_name: str

Return the name of current backend

background: str = 'Schwarzschild'

The spacetime background for this model.

build_with_same_backend(module_class, args=None, kwargs=None)

Build an instance of module_class with same backend as current object.

Parameters:

  • module_class (type[ParallelModuleDerivate]) – class of the object to be built, must derive from ParallelModuleBase

  • args (list, optional) – positional arguments for module_class constructor

  • kwargs (dict, optional) – keyword arguments for module_class constructor (the ‘force_backend’ argument will be ignored and replaced)

Return type:

ParallelModuleDerivate

classmethod citation()

Return the module references as a printable BibTeX string.

Return type:

str

descriptor: str = 'eccentric'

Description of the inspiral trajectory properties for this model.

frame: str = 'source'

Frame in which source is generated. Is source frame.

needs_Y: bool = False

If True, model expects inclination parameter Y (rather than xI).

sanity_check_init(M, mu, a, p0, e0, xI)

Sanity check initial parameters.

Make sure parameters are within allowable ranges.

Parameters:

  • M (float) – Massive black hole mass in solar masses.

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

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

  • p0 (float) – Initial semilatus rectum (dimensionless) \((10\leq p_0\leq 16 + 2e_0)\). See the documentation for more information on \(p_0 \leq 10.0\).

  • e0 (float) – Initial eccentricity \((0\leq e_0\leq0.7)\).

  • xI (float) – Initial cosine(inclination) \((x_I = 1)\).

Returns:

a and xI in the correct convention (a >= 0).

Return type:

(a_fix, xI_fix)

Raises:

ValueError – If any of the parameters are not allowed.

sanity_check_traj(a, p, e, xI)

Sanity check on parameters output from the trajectory module.

Make sure parameters are within allowable ranges.

Parameters:

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

  • p (ndarray) – Array of semi-latus rectum values produced by the trajectory module.

  • e (ndarray) – Array of eccentricity values produced by the trajectory module.

  • xI (ndarray) – Array of cosine(inclination) values produced by the trajectory module.

Raises:

  • ValueError – If any of the trajectory points are not allowed.

  • warn – If any points in the trajectory are allowable, but outside calibration region.

sanity_check_viewing_angles(theta, phi)

Sanity check on viewing angles.

Make sure parameters are within allowable ranges.

Parameters:

  • theta (double) – Polar viewing angle.

  • phi (double) – Azimuthal viewing angle.

Returns:

(theta, phi). Phi is wrapped.

Return type:

tuple

Raises:

ValueError – If any of the angular values are not allowed.

property xp: ModuleType

Return the module providing ndarray capabilities

ndim: int

Number of phases in the model.

lmax: int

Maximum l value for the model.

nmax: int

Maximum n value for the model.

num_modes: int

Total number of modes in the model

m0sort: xp_ndarray

1D Array of sorted mode indices with m=0 first, then m<0, then m>0.

l_arr_no_mask: xp_ndarray

1D Array of l values for each mode before masking.

m_arr_no_mask: xp_ndarray

1D Array of m values for each mode before masking.

n_arr_no_mask: xp_ndarray

1D Array of n values for each mode before masking.

lmn_indices: dict[int, int]

Dictionary of mode indices to mode number.

m0mask: xp_ndarray

1D Array Mask for m != 0.

num_m_zero_up: int

Number of modes with m >= 0.

num_m0: int

Number of modes with m == 0.

num_m_1_up: int

Number of modes with m > 0.

l_arr: xp_ndarray

1D Array of l values for each mode.

m_arr: xp_ndarray

1D Array of m values for each mode.

n_arr: xp_ndarray

1D Array of n values for each mode.

m_zero_up_mask: xp_ndarray

1D Mask for m >= 0.

unique_l: xp_ndarray

1D Array of unique l values.

unique_m: xp_ndarray

1D Array of unique m values.

num_unique_lm: int

Number of unique (l,m) values.

index_map: dict[tuple[int, int, int], int]

Maps mode index to mode tuple.

special_index_map: dict[tuple[int, int, int], int]

Maps mode index to mode tuple with m > 0.

index_map_arr: xp_ndarray

Array mapping mode tuple to mode index - used for fast indexing. Returns -1 if mode does not exist.

special_index_map_arr: xp_ndarray

Array mapping mode tuple to mode index with m > 0 - used for fast indexing. Returns -1 if mode does not exist.

2D Cubic Spline Interpolation

class few.amplitude.ampinterp2d.AmpInterp2D(w_knots, u_knots, coefficients, l_arr, m_arr, n_arr, force_backend=None)

Bases: AmplitudeBase, ParallelModuleBase

Calculate Teukolsky amplitudes with a bicubic spline interpolation.

This class is initialised by providing mode index arrays and a corresponding spline coefficients array. These coefficients can be computed for user-supplied data with the TODO METHOD method of this class.

When called with arguments \((a, p, e, xI)\), these parameters are transformed into a set of interpolation coordinates and the bicubic spline interpolant is evaluated at these coordinates for all sets of coefficients.

This module is available for GPU and CPU.

Parameters:

  • w_knots (ndarray) – The knots in the w direction.

  • u_knots (ndarray) – The knots in the u direction.

  • coefficients (ndarray) – The Teukolsky mode amplitudes to be interpolated.

  • l_arr (xp_ndarray) – Array of \(\ell\) mode indices.

  • m_arr (xp_ndarray) – Array of \(m\) mode indices.

  • n_arr (xp_ndarray) – Array of \(n\) mode indices.

  • **kwargs – Optional keyword arguments for the base class: few.utils.baseclasses.AmplitudeBase, few.utils.baseclasses.ParallelModuleBase.

  • force_backend (str | Backend | None)

l_arr: xp_ndarray

1D Array of \(l\) mode indices.

m_arr: xp_ndarray

1D Array of \(m\) mode indices.

n_arr: xp_ndarray

1D Array of \(n\) mode indices.

num_teuk_modes: int

Total number of mode amplitude grids this interpolant stores.

knots: list[xp_ndarray]

Arrays holding spline knots in each dimension.

coeff: xp_ndarray

Array holding all spline coefficient information.

Type:

np.ndarray

len_indiv_c: int

Total number of coefficients per mode amplitude grid.

property interp2D: callable

GPU or CPU interp2D

classmethod module_references()

Return citations related to this module

Return type:

list[REFERENCE]

classmethod supported_backends()

List of backends supported by a parallel module by order of preference.

__call__(w, u, *args, mode_indexes=None, **kwargs)

Evaluate the spline or its derivatives at given positions.

Parameters:

  • w (float | xp_ndarray) – Eccentricity interpolation parameter.

  • u (float | xp_ndarray) – Dimensionless semi-latus rectum interpolation parameter.

  • mode_indexes (xp_ndarray | None) – Array indices of modes to be generated (optional; defaults to all modes).

Returns:

Complex Teukolsky mode amplitudes at the requested points.

Return type:

xp_ndarray

static CPU_ONLY()

List of supported backend for CPU only class

Return type:

list[str]

List of supported backends for CPU-recommended class with GPU support

Return type:

list[str]

static GPU_ONLY()

List of supported backends for GPU-only class

Return type:

list[str]

List of supported backends for GPU-recommended class with CPU support

Return type:

list[str]

adapt_backend_kwargs(kwargs=None)

Adapt a set of keyword arguments to add/set ‘force_backend’ to current backend

Parameters:

kwargs (dict | None)

Return type:

dict

property backend: Backend

Access the underlying backend.

property backend_name: str

Return the name of current backend

build_with_same_backend(module_class, args=None, kwargs=None)

Build an instance of module_class with same backend as current object.

Parameters:

  • module_class (type[ParallelModuleDerivate]) – class of the object to be built, must derive from ParallelModuleBase

  • args (list, optional) – positional arguments for module_class constructor

  • kwargs (dict, optional) – keyword arguments for module_class constructor (the ‘force_backend’ argument will be ignored and replaced)

Return type:

ParallelModuleDerivate

classmethod citation()

Return the module references as a printable BibTeX string.

Return type:

str

classmethod get_amplitudes(*args, **kwargs)

Amplitude Generator

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

Raises:

NotImplementedError – The child class does not have this method.

property xp: ModuleType

Return the module providing ndarray capabilities

class few.amplitude.ampinterp2d.AmpInterpKerrEqEcc(filename=None, downsample_Z=1, force_backend=None, **kwargs)

Bases: AmplitudeBase, KerrEccentricEquatorial

Calculate Teukolsky amplitudes in the Kerr eccentric equatorial regime with a bicubic spline + linear interpolation scheme.

When called with arguments \((a, p, e, xI)\), these parameters are transformed into a set of interpolation coordinates and the bicubic spline interpolant is evaluated at these coordinates for all sets of coefficients. To interpolate in the :math”a direction, the bicubic spline is evaluated at the adjacent grid points and a linear interpolation is performed.

This module is available for GPU and CPU.

Parameters:
get_amplitudes(a, p, e, xI, specific_modes=None)

Generate Teukolsky amplitudes for a given set of parameters.

Parameters:

  • a – Dimensionless spin parameter of MBH.

  • p – Dimensionless semi-latus rectum.

  • e – Eccentricity.

  • xI – Cosine of orbital inclination. Only \(|x_I| = 1\) is currently supported.

  • specific_modes – Either indices or mode index tuples of modes to be generated (optional; defaults to all modes).

Returns:

If specific_modes is a list of tuples, returns a dictionary of complex mode amplitudes. Else, returns an array of complex mode amplitudes.

Return type:

dict | ndarray

static CPU_ONLY()

List of supported backend for CPU only class

Return type:

list[str]

List of supported backends for CPU-recommended class with GPU support

Return type:

list[str]

static GPU_ONLY()

List of supported backends for GPU-only class

Return type:

list[str]

List of supported backends for GPU-recommended class with CPU support

Return type:

list[str]

__call__(*args, specific_modes=None, **kwargs)

Common call for Teukolsky amplitudes

This function takes the inputs the trajectory in \((p,e)\) as arrays and returns the complex amplitude of all modes to adiabatic order at each step of the trajectory.

Parameters:

  • *args – Added to create future flexibility when calling different amplitude modules. Transfers directly into get_amplitudes function.

  • specific_modes (list | ndarray | None) – Either indices or mode index tuples of modes to be generated (optional; defaults to all modes). This is not available for all waveforms.

  • **kwargs (dict, placeholder) – Added to create flexibility when calling different amplitude modules. It is not used.

Returns:

If specific_modes is a list of tuples, returns a dictionary of complex mode amplitudes. Else, returns an array of complex mode amplitudes.

Return type:

dict | ndarray

adapt_backend_kwargs(kwargs=None)

Adapt a set of keyword arguments to add/set ‘force_backend’ to current backend

Parameters:

kwargs (dict | None)

Return type:

dict

property backend: Backend

Access the underlying backend.

property backend_name: str

Return the name of current backend

background: str = 'Kerr'

The spacetime background for this model.

build_with_same_backend(module_class, args=None, kwargs=None)

Build an instance of module_class with same backend as current object.

Parameters:

  • module_class (type[ParallelModuleDerivate]) – class of the object to be built, must derive from ParallelModuleBase

  • args (list, optional) – positional arguments for module_class constructor

  • kwargs (dict, optional) – keyword arguments for module_class constructor (the ‘force_backend’ argument will be ignored and replaced)

Return type:

ParallelModuleDerivate

classmethod citation()

Return the module references as a printable BibTeX string.

Return type:

str

descriptor: str = 'eccentric equatorial'

Description of the inspiral trajectory properties for this model.

frame: str = 'source'

Frame in which source is generated. Is source frame.

classmethod module_references()

Method implemented by each class to define its list of references

Return type:

List[REFERENCE | str]

needs_Y: bool = False

If True, model expects inclination parameter Y (rather than xI).

sanity_check_init(M, mu, a, p0, e0, xI)

Sanity check initial parameters.

Make sure parameters are within allowable ranges.

Parameters:

  • M (float) – Massive black hole mass in solar masses.

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

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

  • p0 (float) – Initial semilatus rectum (dimensionless) \((10\leq p_0\leq 16 + 2e_0)\). See the documentation for more information on \(p_0 \leq 10.0\).

  • e0 (float) – Initial eccentricity \((0\leq e_0\leq0.7)\).

  • xI (float) – Initial cosine(inclination) \((|x_I| = 1)\).

Returns:

a and xI in the correct convention (a >= 0).

Return type:

(a_fix, xI_fix)

Raises:

ValueError – If any of the parameters are not allowed.

sanity_check_traj(a, p, e, xI)

Sanity check on parameters output from the trajectory module.

Make sure parameters are within allowable ranges.

Parameters:

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

  • p (ndarray) – Array of semi-latus rectum values produced by the trajectory module.

  • e (ndarray) – Array of eccentricity values produced by the trajectory module.

  • xI (ndarray) – Array of cosine(inclination) values produced by the trajectory module.

Raises:

  • ValueError – If any of the trajectory points are not allowed.

  • warn – If any points in the trajectory are allowable, but outside calibration region.

sanity_check_viewing_angles(theta, phi)

Sanity check on viewing angles.

Make sure parameters are within allowable ranges.

Parameters:

  • theta (double) – Polar viewing angle.

  • phi (double) – Azimuthal viewing angle.

Returns:

(theta, phi). Phi is wrapped.

Return type:

tuple

Raises:

ValueError – If any of the angular values are not allowed.

classmethod supported_backends()

List of backends supported by a parallel module by order of preference.

property xp: ModuleType

Return the module providing ndarray capabilities

ndim: int

Number of phases in the model.

lmax: int

Maximum l value for the model.

nmax: int

Maximum n value for the model.

num_modes: int

Total number of modes in the model

num_teuk_modes: int

Number of Teukolsky modes in the model.

m0sort: xp_ndarray

1D Array of sorted mode indices with m=0 first, then m<0, then m>0.

l_arr_no_mask: xp_ndarray

1D Array of l values for each mode before masking.

m_arr_no_mask: xp_ndarray

1D Array of m values for each mode before masking.

n_arr_no_mask: xp_ndarray

1D Array of n values for each mode before masking.

lmn_indices: dict[int, int]

Dictionary of mode indices to mode number.

m0mask: xp_ndarray

1D Array Mask for m != 0.

num_m_zero_up: int

Number of modes with m >= 0.

num_m0: int

Number of modes with m == 0.

num_m_1_up: int

Number of modes with m > 0.

l_arr: xp_ndarray

1D Array of l values for each mode.

m_arr: xp_ndarray

1D Array of m values for each mode.

n_arr: xp_ndarray

1D Array of n values for each mode.

m_zero_up_mask: xp_ndarray

1D Mask for m >= 0.

unique_l: xp_ndarray

1D Array of unique l values.

unique_m: xp_ndarray

1D Array of unique m values.

num_unique_lm: int

Number of unique (l,m) values.

index_map: dict[tuple[int, int, int], int]

Maps mode index to mode tuple.

special_index_map: dict[tuple[int, int, int], int]

Maps mode index to mode tuple with m > 0.

index_map_arr: xp_ndarray

Array mapping mode tuple to mode index - used for fast indexing. Returns -1 if mode does not exist.

special_index_map_arr: xp_ndarray

Array mapping mode tuple to mode index with m > 0 - used for fast indexing. Returns -1 if mode does not exist.

class few.amplitude.ampinterp2d.AmpInterpSchwarzEcc(filenames=None, force_backend=None, **kwargs)

Bases: AmplitudeBase, SchwarzschildEccentric

Calculate Teukolsky amplitudes in the Schwarzschild eccentric regime with a bicubic spline interpolation.

When called with arguments \((a, p, e, xI)\), these parameters are transformed into a set of interpolation coordinates and the bicubic spline interpolant is evaluated at these coordinates for all sets of coefficients.

This class is retained for legacy compatibility with the original Schwarzschild eccentric models. It is recommended to use AmpInterpKerrEqEcc instead of this class.

This module is available for GPU and CPU.

Parameters:
static CPU_ONLY()

List of supported backend for CPU only class

Return type:

list[str]

List of supported backends for CPU-recommended class with GPU support

Return type:

list[str]

static GPU_ONLY()

List of supported backends for GPU-only class

Return type:

list[str]

List of supported backends for GPU-recommended class with CPU support

Return type:

list[str]

__call__(*args, specific_modes=None, **kwargs)

Common call for Teukolsky amplitudes

This function takes the inputs the trajectory in \((p,e)\) as arrays and returns the complex amplitude of all modes to adiabatic order at each step of the trajectory.

Parameters:

  • *args – Added to create future flexibility when calling different amplitude modules. Transfers directly into get_amplitudes function.

  • specific_modes (list | ndarray | None) – Either indices or mode index tuples of modes to be generated (optional; defaults to all modes). This is not available for all waveforms.

  • **kwargs (dict, placeholder) – Added to create flexibility when calling different amplitude modules. It is not used.

Returns:

If specific_modes is a list of tuples, returns a dictionary of complex mode amplitudes. Else, returns an array of complex mode amplitudes.

Return type:

dict | ndarray

adapt_backend_kwargs(kwargs=None)

Adapt a set of keyword arguments to add/set ‘force_backend’ to current backend

Parameters:

kwargs (dict | None)

Return type:

dict

property backend: Backend

Access the underlying backend.

property backend_name: str

Return the name of current backend

background: str = 'Schwarzschild'

The spacetime background for this model.

build_with_same_backend(module_class, args=None, kwargs=None)

Build an instance of module_class with same backend as current object.

Parameters:

  • module_class (type[ParallelModuleDerivate]) – class of the object to be built, must derive from ParallelModuleBase

  • args (list, optional) – positional arguments for module_class constructor

  • kwargs (dict, optional) – keyword arguments for module_class constructor (the ‘force_backend’ argument will be ignored and replaced)

Return type:

ParallelModuleDerivate

classmethod citation()

Return the module references as a printable BibTeX string.

Return type:

str

descriptor: str = 'eccentric'

Description of the inspiral trajectory properties for this model.

frame: str = 'source'

Frame in which source is generated. Is source frame.

classmethod module_references()

Method implemented by each class to define its list of references

Return type:

List[REFERENCE | str]

needs_Y: bool = False

If True, model expects inclination parameter Y (rather than xI).

sanity_check_init(M, mu, a, p0, e0, xI)

Sanity check initial parameters.

Make sure parameters are within allowable ranges.

Parameters:

  • M (float) – Massive black hole mass in solar masses.

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

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

  • p0 (float) – Initial semilatus rectum (dimensionless) \((10\leq p_0\leq 16 + 2e_0)\). See the documentation for more information on \(p_0 \leq 10.0\).

  • e0 (float) – Initial eccentricity \((0\leq e_0\leq0.7)\).

  • xI (float) – Initial cosine(inclination) \((x_I = 1)\).

Returns:

a and xI in the correct convention (a >= 0).

Return type:

(a_fix, xI_fix)

Raises:

ValueError – If any of the parameters are not allowed.

sanity_check_traj(a, p, e, xI)

Sanity check on parameters output from the trajectory module.

Make sure parameters are within allowable ranges.

Parameters:

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

  • p (ndarray) – Array of semi-latus rectum values produced by the trajectory module.

  • e (ndarray) – Array of eccentricity values produced by the trajectory module.

  • xI (ndarray) – Array of cosine(inclination) values produced by the trajectory module.

Raises:

  • ValueError – If any of the trajectory points are not allowed.

  • warn – If any points in the trajectory are allowable, but outside calibration region.

sanity_check_viewing_angles(theta, phi)

Sanity check on viewing angles.

Make sure parameters are within allowable ranges.

Parameters:

  • theta (double) – Polar viewing angle.

  • phi (double) – Azimuthal viewing angle.

Returns:

(theta, phi). Phi is wrapped.

Return type:

tuple

Raises:

ValueError – If any of the angular values are not allowed.

classmethod supported_backends()

List of backends supported by a parallel module by order of preference.

property xp: ModuleType

Return the module providing ndarray capabilities

ndim: int

Number of phases in the model.

lmax: int

Maximum l value for the model.

nmax: int

Maximum n value for the model.

num_modes: int

Total number of modes in the model

m0sort: xp_ndarray

1D Array of sorted mode indices with m=0 first, then m<0, then m>0.

l_arr_no_mask: xp_ndarray

1D Array of l values for each mode before masking.

m_arr_no_mask: xp_ndarray

1D Array of m values for each mode before masking.

n_arr_no_mask: xp_ndarray

1D Array of n values for each mode before masking.

lmn_indices: dict[int, int]

Dictionary of mode indices to mode number.

m0mask: xp_ndarray

1D Array Mask for m != 0.

num_m_zero_up: int

Number of modes with m >= 0.

num_m0: int

Number of modes with m == 0.

num_m_1_up: int

Number of modes with m > 0.

l_arr: xp_ndarray

1D Array of l values for each mode.

m_arr: xp_ndarray

1D Array of m values for each mode.

n_arr: xp_ndarray

1D Array of n values for each mode.

m_zero_up_mask: xp_ndarray

1D Mask for m >= 0.

unique_l: xp_ndarray

1D Array of unique l values.

unique_m: xp_ndarray

1D Array of unique m values.

num_unique_lm: int

Number of unique (l,m) values.

index_map: dict[tuple[int, int, int], int]

Maps mode index to mode tuple.

special_index_map: dict[tuple[int, int, int], int]

Maps mode index to mode tuple with m > 0.

index_map_arr: xp_ndarray

Array mapping mode tuple to mode index - used for fast indexing. Returns -1 if mode does not exist.

special_index_map_arr: xp_ndarray

Array mapping mode tuple to mode index with m > 0 - used for fast indexing. Returns -1 if mode does not exist.

filename: str

Coefficient file name.

tck: list[xp_ndarray]

Arrays holding all spline coefficient information.

num_teuk_modes: int

Total number of mode amplitude grids this interpolant stores.

len_indiv_c: int

Total number of coefficients per mode amplitude grid.

property interp2D: callable

GPU or CPU interp2D

get_amplitudes(a, p, e, xI, specific_modes=None)

Generate Teukolsky amplitudes for a given set of parameters.

Parameters:

  • a – Dimensionless spin parameter of MBH (must be equal to zero).

  • p – Dimensionless semi-latus rectum.

  • e – Eccentricity.

  • xI – Cosine of orbital inclination. Only \(x_I = 1\) is currently supported.

  • specific_modes – Either indices or mode index tuples of modes to be generated (optional; defaults to all modes).

Returns:

If specific_modes is a list of tuples, returns a dictionary of complex mode amplitudes. Else, returns an array of complex mode amplitudes.

Return type:

dict | ndarray