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).

Schwarzschild Eccentric Amplitudes

ROMAN Network

class few.amplitude.romannet.RomanAmplitude(max_init_len=1000, **kwargs)

Bases: AmplitudeBase, SchwarzschildEccentric, ParallelModuleBase

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:

• max_init_len (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 max_init_len 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 {}.

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

use_gpu

If True, use the GPU.

Type:

bool

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

max_init_len

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

property citation

Return citations for this module

property gpu_capability

Confirms GPU capability

__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 (tuple, placeholder) – Added to create future flexibility when calling different amplitude modules. Transfers directly into get_amplitudes function.

• specific_modes (list, optional) – List of tuples for (l, m, n) values desired modes. Default is None. 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 None, Teukolsky modes in shape (number of trajectory points, number of modes) dict: Dictionary with requested modes.

Return type:

2D array (double)

adjust_gpu_usage(use_gpu, kwargs)

Adjust all inputs for gpu usage

If user wants to use gpu, it will change all kwargs in so that use_gpu=True.

Parameters:

• use_gpu (bool) – If True, use gpu resources.

• kwargs (list of dicts or dict) – List of kwargs dictionaries or single dictionary for each constituent class in the waveform generator.

attributes_ParallelModuleBase()

use_gpu

If True, use GPU.

Type:

bool

xp

Either numpy or CuPy based on gpu preference.

Type:

obj

attributes_SchwarzschildEccentric()

background

Spacetime background for this model.

Type:

str

descriptor

Short description for model validity.

Type:

str

num_modes, num_teuk_modes

Total number of Teukolsky modes in the model.

Type:

int

lmax, nmax

Maximum \(l\), \(n\) values

Type:

int

ndim

Dimensionality in terms of orbital parameters and phases.

Type:

int

m0sort

array of indices to sort accoring to \((m=0)\) parts first and then \(m>0\) parts.

Type:

1D int xp.ndarray

m0mask

Masks values with \(m==0\).

Type:

1D bool xp.ndarray

m_zero_up_mask

Masks values with \(m<1\).

Type:

1D bool xp.ndarray

l_arr, m_arr, n_arr

\((l,m,n)\) arrays containing indices for each mode.

Type:

1D int xp.ndarray

lmn_indices

Dictionary mapping a tuple of \((l,m,n)\) to the respective index in l_arr, m_arr, and n_arr.

Type:

dict

num_m_zero_up

Number of modes with \(m\geq0\).

Type:

int

num_m0

Number of modes with \(m=0\).

Type:

int

num_m_1_up

Number of modes with \(m\geq1\).

Type:

int

unique_l, unique_m

Arrays of unique \(l\) and \(m\) values.

Type:

1D int xp.ndarray

inverse_lm

Array of indices that expands unique \((l, m)\) values to the full array of \((l,m,n)\) values.

Type:

1D int xp.ndarray

index_map

Dictionary mapping the location of the (l,m,n) indices back to there spot in l_arr, m_arr, n_arr.

Type:

dict

special_index_map

Dictionary mapping the location of the (l,m,n) indices back to there spot in l_arr, m_arr, n_arr. However, this maps locations of -m values to +m values.

Type:

dict

sanity_check_gpu(use_gpu)

Check if this class has GPU capability

If the user is requesting GPU usage, this will confirm the class has GPU capabilites.

Parameters:

use_gpu (bool) – If True, the user is requesting GPU usage.

Raises:

ValueError – The user is requesting GPU usage, but this class does not have that capability.

sanity_check_init(M, mu, p0, e0)

Sanity check initial parameters.

Make sure parameters are within allowable ranges.

Parameters:

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

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

• p0 (double) – 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 (double) – Initial eccentricity \((0\leq e_0\leq0.7)\).

Raises:

ValueError – If any of the parameters are not allowed.

sanity_check_traj(p, e)

Sanity check on parameters output from thte trajectory module.

Make sure parameters are within allowable ranges.

Parameters:

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

• e (1D np.ndarray) – Array of eccentricity 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.

get_amplitudes(p, e, *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)

2D Cubic Spline Interpolation

class few.amplitude.interp2dcubicspline.Interp2DAmplitude(**kwargs)

Bases: AmplitudeBase, SchwarzschildEccentric

Calculate Teukolsky amplitudes by 2D Cubic Spline interpolation.

Please see the documentations for few.utils.baseclasses.SchwarzschildEccentric for overall aspects of these models.

Each mode is setup with a 2D cubic spline interpolant. When the user inputs \((p,e)\), the interpolatant determines the corresponding amplitudes for each mode in the model.

Parameters:

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

attributes_Interp2DAmplitude()

amplitude_generator

C++ class that performs the bicubic interpolation. It stores all of the splines during initialization steps.

Type:

obj

property citation

Return citations for this class

get_amplitudes(p, e, *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.

• l_arr (1D int numpy.ndarray) – \(l\) values to evaluate.

• m_arr (1D int numpy.ndarray) – \(m\) values to evaluate.

• n_arr (1D int numpy.ndarray) – \(ns\) values to evaluate.

• *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)

__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 (tuple, placeholder) – Added to create future flexibility when calling different amplitude modules. Transfers directly into get_amplitudes function.

• specific_modes (list, optional) – List of tuples for (l, m, n) values desired modes. Default is None. 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 None, Teukolsky modes in shape (number of trajectory points, number of modes) dict: Dictionary with requested modes.

Return type:

2D array (double)

adjust_gpu_usage(use_gpu, kwargs)

Adjust all inputs for gpu usage

If user wants to use gpu, it will change all kwargs in so that use_gpu=True.

Parameters:

• use_gpu (bool) – If True, use gpu resources.

• kwargs (list of dicts or dict) – List of kwargs dictionaries or single dictionary for each constituent class in the waveform generator.

attributes_ParallelModuleBase()

use_gpu

If True, use GPU.

Type:

bool

xp

Either numpy or CuPy based on gpu preference.

Type:

obj

attributes_SchwarzschildEccentric()

background

Spacetime background for this model.

Type:

str

descriptor

Short description for model validity.

Type:

str

num_modes, num_teuk_modes

Total number of Teukolsky modes in the model.

Type:

int

lmax, nmax

Maximum \(l\), \(n\) values

Type:

int

ndim

Dimensionality in terms of orbital parameters and phases.

Type:

int

m0sort

array of indices to sort accoring to \((m=0)\) parts first and then \(m>0\) parts.

Type:

1D int xp.ndarray

m0mask

Masks values with \(m==0\).

Type:

1D bool xp.ndarray

m_zero_up_mask

Masks values with \(m<1\).

Type:

1D bool xp.ndarray

l_arr, m_arr, n_arr

\((l,m,n)\) arrays containing indices for each mode.

Type:

1D int xp.ndarray

lmn_indices

Dictionary mapping a tuple of \((l,m,n)\) to the respective index in l_arr, m_arr, and n_arr.

Type:

dict

num_m_zero_up

Number of modes with \(m\geq0\).

Type:

int

num_m0

Number of modes with \(m=0\).

Type:

int

num_m_1_up

Number of modes with \(m\geq1\).

Type:

int

unique_l, unique_m

Arrays of unique \(l\) and \(m\) values.

Type:

1D int xp.ndarray

inverse_lm

Array of indices that expands unique \((l, m)\) values to the full array of \((l,m,n)\) values.

Type:

1D int xp.ndarray

index_map

Dictionary mapping the location of the (l,m,n) indices back to there spot in l_arr, m_arr, n_arr.

Type:

dict

special_index_map

Dictionary mapping the location of the (l,m,n) indices back to there spot in l_arr, m_arr, n_arr. However, this maps locations of -m values to +m values.

Type:

dict

property gpu_capability

Confirms GPU capability

sanity_check_gpu(use_gpu)

Check if this class has GPU capability

If the user is requesting GPU usage, this will confirm the class has GPU capabilites.

Parameters:

use_gpu (bool) – If True, the user is requesting GPU usage.

Raises:

ValueError – The user is requesting GPU usage, but this class does not have that capability.

sanity_check_init(M, mu, p0, e0)

Sanity check initial parameters.

Make sure parameters are within allowable ranges.

Parameters:

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

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

• p0 (double) – 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 (double) – Initial eccentricity \((0\leq e_0\leq0.7)\).

Raises:

ValueError – If any of the parameters are not allowed.

sanity_check_traj(p, e)

Sanity check on parameters output from thte trajectory module.

Make sure parameters are within allowable ranges.

Parameters:

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

• e (1D np.ndarray) – Array of eccentricity 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.