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.summation.base.SummationBase(output_type='td', pad_output=False, odd_len=False, force_backend=None)

Bases: ParallelModuleBase

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) – Add zero padding to the waveform for time between plunge and observation time. Default is False.

  • output_type (str) – 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) – 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.

  • force_backend (str | Backend | None)

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, **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 (float) – Array of t values.

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

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

  • T (float) – Maximum observing time in years. Default is 1.0.

  • **kwargs – Added for future flexibility.

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 module_references()

Method implemented by each class to define its list of references

Return type:

List[REFERENCE | str]

classmethod supported_backends()

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

Return type:

Sequence[str]

property xp: ModuleType

Return the module providing ndarray capabilities

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 in cuda for an example of this.

This class can be run on GPUs and CPUs.

Parameters:

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

  • y_all (ndarray) – y values for the spline; shape is (length,) or (ninterps, length).

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

degree

Degree of the spline. Only cubic splines are available.

Type:

int

ninterps

Number of interpolants.

Type:

int

length

Length of the input t array.

Type:

int

reshape_shape

Shape of the spline coefficients array.

Type:

tuple

property interpolate_arrays: callable

GPU or CPU waveform generation.

classmethod supported_backends()

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

property y: ndarray

y values associated with the spline

property c1: ndarray

constants for the linear term

property c2: ndarray

constants for the quadratic term

property c3: ndarray

constants for the cubic term

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 module_references()

Method implemented by each class to define its list of references

Return type:

List[REFERENCE | str]

property xp: ModuleType

Return the module providing ndarray capabilities

__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 (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) – 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:

ndarray

class few.summation.interpolatedmodesum.InterpolatedModeSum(force_backend=None, **kwargs)

Bases: SummationBase

Create waveform by interpolating a 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.

Parameters:

force_backend (str | Backend | None)

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__(t, *args, T=1.0, dt=10.0, **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 (float) – Array of t values.

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

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

  • T (float) – Maximum observing time in years. Default is 1.0.

  • **kwargs – Added for future flexibility.

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 module_references()

Method implemented by each class to define its list of references

Return type:

List[REFERENCE | str]

property xp: ModuleType

Return the module providing ndarray capabilities

property get_waveform: callable

GPU or CPU waveform generation.

classmethod supported_backends()

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

sum(t, teuk_modes, ylms, phase_interp_t, phase_interp_coeffs, m_arr, n_arr, *args, dt=10.0, integrate_backwards=False, **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 (ndarray) – Array of t values.

  • teuk_modes (ndarray) – Array of complex amplitudes; shape is (len(t), num_teuk_modes).

  • ylms (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 – Array of azimuthal phase values (\(\Phi_\phi\)).

  • Phi_r – Array of radial phase values (\(\Phi_r\)).

  • m_arr (ndarray) – \(m\) values associated with each mode.

  • n_arr (ndarray) – \(n\) values associated with each mode.

  • *args – Added for future flexibility.

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

  • **kwargs – Added for future flexibility.

  • phase_interp_t (ndarray)

  • phase_interp_coeffs (ndarray)

  • integrate_backwards (bool)

class few.summation.fdinterp.FDInterpolatedModeSum(force_backend=None, **kwargs)

Bases: SummationBase, SchwarzschildEccentric

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.

Parameters:

force_backend (str | Backend | None)

property get_waveform_fd: callable

GPU or CPU waveform generation.

classmethod supported_backends()

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

classmethod module_references()

Return citations related to this module

Return type:

list[REFERENCE]

sum(t, teuk_modes, ylms, phase_interp_t, phase_interp_coeffs, m_arr, n_arr, M, a, p, e, xI, *args, include_minus_m=True, separate_modes=False, dt=10.0, f_arr=None, mask_positive=False, integrate_backwards=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 self.xp.ndarray) – Array of t values.

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

  • ylms (1D complex128 self.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 self.xp.ndarray) – Array of azimuthal phase values (\(\Phi_\phi\)).

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

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

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

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

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

  • e (1D int self.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 self.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.

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__(t, *args, T=1.0, dt=10.0, **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 (float) – Array of t values.

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

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

  • T (float) – Maximum observing time in years. Default is 1.0.

  • **kwargs – Added for future flexibility.

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

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.

Direct Summation

class few.summation.directmodesum.DirectModeSum(*args, **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.

classmethod supported_backends()

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

sum(t, teuk_modes, ylms, phase_interp_t, phases_in, m_arr, n_arr, *args, dt=10.0, integrate_backwards=False, **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 self.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.

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__(t, *args, T=1.0, dt=10.0, **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 (float) – Array of t values.

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

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

  • T (float) – Maximum observing time in years. Default is 1.0.

  • **kwargs – Added for future flexibility.

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.

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.

AAK Summation / Waveform Generator

class few.summation.aakwave.AAKSummation(force_backend=None, **kwargs)

Bases: Pn5AAK, SummationBase

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 for more information.

Parameters:

  • **kwargs – Optional keyword arguments for the base classes: few.utils.baseclasses.Pn5AAK. few.utils.baseclasses.SummationBase.

  • force_backend (str | Backend | None)

property waveform_generator

Compiled CPU/GPU that performs the AAK waveform generation.

Type:

obj

classmethod supported_backends()

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

sum(tvec, M, a, dist, mu, qS, phiS, qK, phiK, nmodes, interp_t, interp_coeffs, *args, mich=False, dt=10.0, integrate_backwards=False, **kwargs)

Compute an AAK waveform from an input trajectory.

This function performs the AAK waveform summation and fills the waveform array in-place.

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 (ndarray) – Array containing the time values associated with the sparse trajectory.

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

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

  • p – Array containing the trajectory for values of the semi-latus rectum.

  • e – Array containing the trajectory for values of the eccentricity.

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

  • dist (float) – Luminosity distance in Gpc.

  • Phi_phi – Array containing the trajectory for \(\Phi_\phi\).

  • Phi_theta – Array containing the trajectory for \(\Phi_\theta\).

  • Phi_r – Array containing the trajectory for \(\Phi_r\).

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

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

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

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

  • phiK (float) – 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) – 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 (float) – Time between samples in seconds (inverse of sampling frequency). Default is 10.0.

  • **kwargs – Added to create flexibility when calling different amplitude modules. It is not used.

  • interp_t (ndarray)

  • interp_coeffs (ndarray)

  • integrate_backwards (bool)

Return type:

None

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__(t, *args, T=1.0, dt=10.0, **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 (float) – Array of t values.

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

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

  • T (float) – Maximum observing time in years. Default is 1.0.

  • **kwargs – Added for future flexibility.

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 inclined'

Description of the inspiral trajectory properties for this model.

frame: str = 'detector'

Frame in which source is generated. Is detector frame.

classmethod module_references()

Return citations related to this module

Return type:

list[REFERENCE]

needs_Y: bool = True

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

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_init(M, mu, a, p0, e0, Y0)

Sanity check initial parameters.

Make sure parameters are within allowable ranges.

Parameters:

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

  • m – compact object mass in solar masses.

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

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

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

  • mu (float)

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.

property xp: ModuleType

Return the module providing ndarray capabilities