Summation Package

The summation package houses codes used for combining amplitude and phase information over the course of an inspiral. It does contain GPU accelerated options. It deals with the overall summation of quantities seen in (1).

class few.utils.baseclasses.SummationBase(*args, output_type='td', pad_output=False, odd_len=False, **kwargs)

Bases: ABC

Base class used for summation modules.

This class provides a common flexible interface to various summation implementations. Specific arguments to each summation 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.

  • output_type (str, optional) – Type of domain in which to calculate the waveform. Default is ‘td’ for time domain. Options are ‘td’ (time domain) or ‘fd’ (Fourier domain). In the future we hope to add ‘tf’ (time-frequency) and ‘wd’ (wavelet domain).

  • odd_len (bool, optional) – The waveform output will be padded to be an odd number if True. If output_type == "fd", odd_len will be set to True. Default is False.

attributes_SummationBase()
waveform

Complex waveform given by \(h_+ + i*h_x\).

Type:

1D complex128 np.ndarray

property citation

Return citation for this class

classmethod sum(*args, **kwargs)

Sum Generator

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

Raises:

NotImplementedError – The child class does not have this method.

__call__(t, *args, T=1.0, dt=10.0, t_window=None, **kwargs)

Common call function for summation modules.

Provides a common interface for summation modules. It can adjust for more dimensions in a model.

Parameters:

  • t (1D double xp.ndarray) – Array of t values.

  • *args (list) – Added for flexibility with summation modules. args tranfers directly into sum function.

  • dt (double, optional) – Time spacing between observations in seconds (inverse of sampling rate). Default is 10.0.

  • T (double, optional) – Maximum observing time in years. Default is 1.0.

  • **kwargs (dict, placeholder) – Added for future flexibility.

Interpolated Summation

class few.summation.interpolatedmodesum.CubicSplineInterpolant(t, y_all, **kwargs)

Bases: ParallelModuleBase

GPU-accelerated Multiple Cubic Splines

This class produces multiple cubic splines on a GPU. It has a CPU option as well. The cubic splines are produced with “not-a-knot” boundary conditions.

This class can be run out of Python similar to scipy.interpolate.CubicSpline. However, the most efficient way to use this method is in a customized cuda kernel. See the `source code for the interpolated summation<https://github.com/BlackHolePerturbationToolkit/FastEMRIWaveforms/blob/master/src/interpolate.cu>`_ in cuda for an example of this.

This class can be run on GPUs and CPUs.

Parameters:

  • t (1D or 2D double xp.ndarray) – t values as input for the spline. If 2D, must have shape (ninterps, length).

  • y_all (1D or 2D double xp.ndarray) – y values for the spline. Shape: (length,) or (ninterps, length).

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

attributes_CubicSplineInterpolate()
interpolate_arrays

CPU or GPU function for mode interpolation.

Type:

func

interp_array

Array containing all spline coefficients. It is flattened after fitting from shape (4, length, ninterps). The 4 is the 4 spline coefficients.

Type:

1D double xp.ndarray

property gpu_capability

Confirms GPU capability

property citation

Return the citation for this class

property y

y values associated with the spline

property c1

constants for the linear term

property c2

constants for the quadratic term

property c3

constants for the cubic term

__call__(tnew, deriv_order=0)

Evaluation function for the spline

Put in an array of new t values at which all interpolants will be evaluated. If t values are outside of the original t values, edge values are used to fill the new array at these points.

Parameters:

  • tnew (1D or 2D double xp.ndarray) – Array of new t values. All of these new t values must be within the bounds of the input t values, including the beginning t and excluding the ending t. If tnew is 1D and self.t is 2D, tnew will be cast to 2D.

  • deriv_order (int, optional) – Order of the derivative to evaluate. Default is 0 meaning the basic spline is evaluated. deriv_order of 1, 2, and 3 correspond to their respective derivatives of the spline. Unlike scipy, this is purely an evaluation of the derivative values, not a new class to evaluate for the derivative.

Raises:

ValueError – a new t value is not in the bounds of the input t array.

Returns:

1D or 2D array of evaluated spline values (or derivatives).

Return type:

xp.ndarray

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

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.

class few.summation.interpolatedmodesum.InterpolatedModeSum(*args, **kwargs)

Bases: SummationBase, SchwarzschildEccentric, ParallelModuleBase

Create waveform by interpolating sparse trajectory.

It interpolates all of the modes of interest and phases at sparse trajectories. Within the summation phase, the values are calculated using the interpolants and summed.

This class can be run on GPUs and CPUs.

__call__(t, *args, T=1.0, dt=10.0, t_window=None, **kwargs)

Common call function for summation modules.

Provides a common interface for summation modules. It can adjust for more dimensions in a model.

Parameters:

  • t (1D double xp.ndarray) – Array of t values.

  • *args (list) – Added for flexibility with summation modules. args tranfers directly into sum function.

  • dt (double, optional) – Time spacing between observations in seconds (inverse of sampling rate). Default is 10.0.

  • T (double, optional) – Maximum observing time in years. Default is 1.0.

  • **kwargs (dict, placeholder) – Added for future flexibility.

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

attributes_SummationBase()
waveform

Complex waveform given by \(h_+ + i*h_x\).

Type:

1D complex128 np.ndarray

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.

attributes_InterpolatedModeSum()
get_waveform

CPU or GPU function for waveform creation.

Type:

func

property gpu_capability

Confirms GPU capability

property citation

Return citation for this class

sum(t, teuk_modes, ylms, Phi_phi, Phi_r, m_arr, n_arr, *args, dt=10.0, **kwargs)

Interpolated summation function.

This function interpolates the amplitude and phase information, and creates the final waveform with the combination of ylm values for each mode.

Parameters:

  • t (1D double xp.ndarray) – Array of t values.

  • teuk_modes (2D double xp.array) – Array of complex amplitudes. Shape: (len(t), num_teuk_modes).

  • ylms (1D complex128 xp.ndarray) – Array of ylm values for each mode, including m<0. Shape is (num of m==0,) + (num of m>0,) + (num of m<0). Number of m<0 and m>0 is the same, but they are ordered as (m==0 first then) m>0 then m<0.

  • Phi_phi (1D double xp.ndarray) – Array of azimuthal phase values (\(\Phi_\phi\)).

  • Phi_r (1D double xp.ndarray) – Array of radial phase values (\(\Phi_r\)).

  • m_arr (1D int xp.ndarray) – \(m\) values associated with each mode.

  • n_arr (1D int xp.ndarray) – \(n\) values associated with each mode.

  • *args (list, placeholder) – Added for future flexibility.

  • dt (double, optional) – Time spacing between observations (inverse of sampling rate). Default is 10.0.

  • **kwargs (dict, placeholder) – Added for future flexibility.

class few.summation.fdinterp.FDInterpolatedModeSum(*args, **kwargs)

Bases: SummationBase, SchwarzschildEccentric, ParallelModuleBase

Create waveform by interpolating sparse trajectory in the frequency domain.

It interpolates all of the modes of interest and phases at sparse trajectories. Within the summation phase, the values are calculated using the interpolants and summed.

This class can be run on GPUs and CPUs.

attributes_FDInterpolatedModeSum()
get_waveform

CPU or GPU function for waveform creation.

Type:

func

property gpu_capability

Confirms GPU capability

__call__(t, *args, T=1.0, dt=10.0, t_window=None, **kwargs)

Common call function for summation modules.

Provides a common interface for summation modules. It can adjust for more dimensions in a model.

Parameters:

  • t (1D double xp.ndarray) – Array of t values.

  • *args (list) – Added for flexibility with summation modules. args tranfers directly into sum function.

  • dt (double, optional) – Time spacing between observations in seconds (inverse of sampling rate). Default is 10.0.

  • T (double, optional) – Maximum observing time in years. Default is 1.0.

  • **kwargs (dict, placeholder) – Added for future flexibility.

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

attributes_SummationBase()
waveform

Complex waveform given by \(h_+ + i*h_x\).

Type:

1D complex128 np.ndarray

property citation

Return citation for this class

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.

sum(t, teuk_modes, ylms, Phi_phi, Phi_r, m_arr, n_arr, M, p, e, *args, include_minus_m=True, separate_modes=False, dt=10.0, f_arr=None, mask_positive=False, **kwargs)

Interpolated summation function in Frequency Domain.

This function interpolates the amplitude and phase information, and creates the final waveform with the combination of ylm values for each mode in the Frequency Domain.

This turns the waveform array into a 2D array with shape (2, number of points). The 2 represents h+ and hx in that order.

Parameters:

  • t (1D double xp.ndarray) – Array of t values.

  • teuk_modes (2D double xp.array) – Array of complex amplitudes. Shape: (len(t), num_teuk_modes).

  • ylms (1D complex128 xp.ndarray) – Array of ylm values for each mode, including m<0. Shape is (num of m==0,) + (num of m>0,) + (num of m<0). Number of m<0 and m>0 is the same, but they are ordered as (m==0 first then) m>0 then m<0.

  • Phi_phi (1D double xp.ndarray) – Array of azimuthal phase values (\(\Phi_\phi\)).

  • Phi_r (1D double xp.ndarray) – Array of radial phase values (\(\Phi_r\)).

  • m_arr (1D int xp.ndarray) – \(m\) values associated with each mode.

  • n_arr (1D int xp.ndarray) – \(n\) values associated with each mode.

  • M (double) – Total mass in solar masses.

  • p (1D int xp.ndarray) – Semi-latus rectum in units of M along trajectory.

  • e (1D int xp.ndarray) – Eccentricity value along trajectory.

  • *args (list, placeholder) – Added for flexibility.

  • include_minus_m (bool, optional) – Include the values for \(-m\). This is useful when looking at specific modes. Default is True.

  • separate_modes (bool, optional) – Return each harmonic mode separated from each other. Default is False.

  • dt (double, optional) – Time spacing between observations (inverse of sampling rate). Default is 10.0.

  • f_arr (1D double xp.ndarray, optional) – User-provided frequency array. For now, it must be evenly spaced and include both positive and negative frequencies. If None, the frequency array is built from observation time and time step. Default is None.

  • mask_positive (bool, optional) – Only return h+ and hx along positive frequencies. Default is False.

  • **kwargs (dict, placeholder) – Added for future flexibility.

Direct Summation

class few.summation.directmodesum.DirectModeSum(*args, use_gpu=False, **kwargs)

Bases: SummationBase, SchwarzschildEccentric, ParallelModuleBase

Create waveform by direct summation.

This class sums the amplitude and phase information as received.

Parameters:

  • *args (list, placeholder) – Added for flexibility.

  • **kwargs (dict, placeholder) – Added for flexibility.

property citation

Return citations for this class

property gpu_capability

Confirms GPU capability

sum(t, teuk_modes, ylms, Phi_phi, Phi_r, m_arr, n_arr, *args, **kwargs)

Direct summation function.

This function directly sums the amplitude and phase information, as well as the spin-weighted spherical harmonic values.

Parameters:

  • t (1D double np.ndarray) – Array of t values.

  • teuk_modes (2D double np.array) – Array of complex amplitudes. Shape: (len(t), num_teuk_modes).

  • ylms (1D complex128 xp.ndarray) – Array of ylm values for each mode, including m<0. Shape is (num of m==0,) + (num of m>0,) + (num of m<0). Number of m<0 and m>0 is the same, but they are ordered as (m==0 first then) m>0 then m<0.

  • Phi_phi (1D double np.ndarray) – Array of azimuthal phase values (\(\Phi_\phi\)).

  • Phi_r (1D double np.ndarray) – Array of radial phase values (\(\Phi_r\)).

  • m_arr (1D int np.ndarray) – \(m\) values associated with each mode.

  • n_arr (1D int np.ndarray) – \(n\) values associated with each mode.

  • *args (list, placeholder) – Added for future flexibility.

  • **kwargs (dict, placeholder) – Added for future flexibility.

__call__(t, *args, T=1.0, dt=10.0, t_window=None, **kwargs)

Common call function for summation modules.

Provides a common interface for summation modules. It can adjust for more dimensions in a model.

Parameters:

  • t (1D double xp.ndarray) – Array of t values.

  • *args (list) – Added for flexibility with summation modules. args tranfers directly into sum function.

  • dt (double, optional) – Time spacing between observations in seconds (inverse of sampling rate). Default is 10.0.

  • T (double, optional) – Maximum observing time in years. Default is 1.0.

  • **kwargs (dict, placeholder) – Added for future flexibility.

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

attributes_SummationBase()
waveform

Complex waveform given by \(h_+ + i*h_x\).

Type:

1D complex128 np.ndarray

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.

AAK Summation / Waveform Generator

class few.summation.aakwave.AAKSummation(**kwargs)

Bases: SummationBase, Pn5AAK, ParallelModuleBase

Calculate an AAK waveform from an input trajectory.

Please see the documentations for few.waveform.Pn5AAKWaveform for overall aspects of this model.

Given an input trajectory and other parameters, this module maps that trajectory to the Analytic Kludge basis as performed for the Augmented Analytic Kludge model. Please see `the AAK paper <https://arxiv.org/abs/1510.06245`_ for more information.

Parameters:

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

property gpu_capability

Indicator if the module has gpu capability

attributes_AmplitudeAAK()
waveform_generator

C++ class that performs the AAK calculation to create the waveform.

Type:

obj

spline

Cubic spline class that holds the coefficients for all splines of the arrays necessary for the AAK calculation.

Type:

obj

__call__(t, *args, T=1.0, dt=10.0, t_window=None, **kwargs)

Common call function for summation modules.

Provides a common interface for summation modules. It can adjust for more dimensions in a model.

Parameters:

  • t (1D double xp.ndarray) – Array of t values.

  • *args (list) – Added for flexibility with summation modules. args tranfers directly into sum function.

  • dt (double, optional) – Time spacing between observations in seconds (inverse of sampling rate). Default is 10.0.

  • T (double, optional) – Maximum observing time in years. Default is 1.0.

  • **kwargs (dict, placeholder) – Added for future flexibility.

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_Pn5AAK()
xp

numpy or cupy based on hardware chosen.

Type:

module

background

Spacetime background for this model.

Type:

str

descriptor

Short description for model validity.

Type:

str

needs_Y

If True, indicates modules that inherit this class requires the inclination definition of \(Y\equiv\cos{\iota}=L/\sqrt{L^2 + Q}\) rather than \(x_I\).

Type:

bool

attributes_SummationBase()
waveform

Complex waveform given by \(h_+ + i*h_x\).

Type:

1D complex128 np.ndarray

property citation

Return citations for this class

sanity_check_angles(qS, phiS, qK, phiK)

Sanity check on viewing angles.

Make sure parameters are within allowable ranges.

Parameters:

  • qS (double) – Sky location polar angle in ecliptic coordinates.

  • phiS (double) – Sky location azimuthal angle in ecliptic coordinates.

  • qK (double) – Initial BH spin polar angle in ecliptic coordinates.

  • phiK (double) – Initial BH spin azimuthal angle in ecliptic coordinates.

Returns:

(qS, phiS, qK, phiK). phiS and phiK are wrapped.

Return type:

tuple

Raises:

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

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, a, p0, e0, Y0)

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.

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

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

  • Y0 (double) – Initial cos:math:iota \((-1.0\leq Y_0\leq1.0)\).

Raises:

ValueError – If any of the parameters are not allowed.

sanity_check_traj(p, e, Y)

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.

  • Y (1D np.ndarray) – Array of cos:math:iota 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.

sum(tvec, M, a, p, e, Y, dist, Phi_phi, Phi_theta, Phi_r, mu, qS, phiS, qK, phiK, nmodes, *args, mich=False, dt=10.0, **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.

Please note: the 5PN trajectory and AAK waveform take the parameter \(Y\equiv\cos{\iota}=L/\sqrt{L^2 + Q}\) rather than \(x_I\) as is accepted for relativistic waveforms and in the generic waveform interface discussed above. The generic waveform interface directly converts \(x_I\) to \(Y\).

Parameters:

  • tvec (1D double numpy.ndarray) – Array containing the time values associated with the sparse trajectory.

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

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

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

  • Y (1D double numpy.ndarray) – Array containing the trajectory for values of \(\cos{\iota}\). Note: This value is different from \(x_I\) used in the relativistic waveforms.

  • dist (double) – Luminosity distance in Gpc.

  • Phi_phi (1D double numpy.ndarray) – Array containing the trajectory for \(\Phi_\phi\).

  • Phi_theta (1D double numpy.ndarray) – Array containing the trajectory for \(\Phi_ heta\).

  • Phi_r (1D double numpy.ndarray) – Array containing the trajectory for \(\Phi_r\).

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

  • qS (double) – Sky location polar angle in ecliptic coordinates.

  • phiS (double) – Sky location azimuthal angle in ecliptic coordinates.

  • qK (double) – Initial BH spin polar angle in ecliptic coordinates.

  • phiK (double) – Initial BH spin azimuthal angle in ecliptic coordinates.

  • nmodes (int) – Number of modes to analyze. This is determined by the eccentricity.

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

  • mich (bool, optional) – If True, produce waveform with long-wavelength response approximation (hI, hII). Please note this is not TDI. If False, return hplus and hcross. Default is False.

  • dt (double, optional) – Time between samples in seconds (inverse of sampling frequency). Default is 10.0.

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