Overall Waveform Models

The Fast EMRI Waveform (few) package provides multiple complete models/waveforms to generate waveforms from start to finish. These are detailed in this section. Please note there are other modules available in each subpackage that may not be listed as a part of a complete model here. We will also provide documentation in this section for the base classes that help standardize and build complete waveform models.

Generic Waveform Generator

class few.waveform.GenerateEMRIWaveform(waveform_class, *args, frame='detector', return_list=False, **kwargs)

Bases: object

Generic waveform generator for data analysis

This class allows the user interface to be the exact same between any waveform in the FEW package. For waveforms built in the source frame, like few.waveform.FastSchwarzschildEccentricFlux, the waveforms are transformed to the detector frame. Waveforms like :class:`few.waveform.Pn5AAKWaveform`that are built in the detector frame are left alone effectively.

For waveforms that are less than Kerr generic (i.e. certain parameters are unnecessary), this interface automatically removes the waveforms dependence on those parameters.

Parameters:

• waveform_class (str or obj) – String with the name of the waveform class to use. See the pre-built waveform models. If an object is provided, must be a waveform class.

• *args (list or tuple, optional) – Arguments for the instantiation of the waveform generation class.

• frame (str, optional) – Which frame to produce the output waveform in. Default is “detector.” Right now, the source frame is not implemented for waveforms that are built in the detector frame.

• return_list (bool, optional) – If True, return \(h_p\) and \(h_x\) as a list. If False, return \(hp - ihx\). Default is False.

• **kwargs (dict, optional) – Dictionary with kwargs for the instantiation of the waveform generator.

__call__(M, mu, a, p0, e0, x0, dist, qS, phiS, qK, phiK, Phi_phi0, Phi_theta0, Phi_r0, *add_args, **kwargs)

Generate the waveform with the given parameters.

Parameters:

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

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

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

• p0 (double) – Initial semilatus rectum (Must be greater than the separatrix at the the given e0 and x0). See documentation for more information on \(p_0<10\).

• e0 (double) – Initial eccentricity.

• x0 (double) – Initial cosine of the inclination angle. (\(x_I=\cos{I}\)). This differs from \(Y=\cos{\iota}\equiv L_z/\sqrt{L_z^2 + Q}\) used in the semi-relativistic formulation. When running kludge waveforms, \(x_{I,0}\) will be converted to \(Y_0\).

• dist (double) – Luminosity distance in Gpc.

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

• Phi_phi0 (double, optional) – Initial phase for \(\Phi_\phi\). Default is 0.0.

• Phi_theta0 (double, optional) – Initial phase for \(\Phi_\Theta\). Default is 0.0.

• Phi_r0 (double, optional) – Initial phase for \(\Phi_r\). Default is 0.0.

• *args (tuple, optional) – Tuple of any extra parameters that go into the model.

• **kwargs (dict, optional) – Dictionary with kwargs for online waveform generation.

Prebuilt Waveform Models

Fast Schwarzschild Eccentric Flux-based Waveform

class few.waveform.FastSchwarzschildEccentricFlux(inspiral_kwargs={}, amplitude_kwargs={}, sum_kwargs={}, Ylm_kwargs={}, use_gpu=False, *args, **kwargs)

Bases: SchwarzschildEccentricWaveformBase

Prebuilt model for fast Schwarzschild eccentric flux-based waveforms.

This model combines the most efficient modules to produce the fastest accurate EMRI waveforms. It leverages GPU hardware for maximal acceleration, but is also available on for CPUs. Please see few.utils.baseclasses.SchwarzschildEccentric for general information on this class of models.

The trajectory module used here is few.trajectory.flux for a flux-based, sparse trajectory. This returns approximately 100 points.

The amplitudes are then determined with few.amplitude.romannet.RomanAmplitude along these sparse trajectories. This gives complex amplitudes for all modes in this model at each point in the trajectory. These are then filtered with few.utils.modeselector.ModeSelector.

The modes that make it through the filter are then summed by few.summation.interpolatedmodesum.InterpolatedModeSum.

See few.waveform.SchwarzschildEccentricWaveformBase for information on inputs. See examples as well.

Parameters:

• inspiral_kwargs (dict, optional) – Optional kwargs to pass to the inspiral generator. Important Note: These kwargs are passed online, not during instantiation like other kwargs here. Default is {}.

• amplitude_kwargs (dict, optional) – Optional kwargs to pass to the amplitude generator during instantiation. Default is {}.

• sum_kwargs (dict, optional) – Optional kwargs to pass to the sum module during instantiation. Default is {}.

• Ylm_kwargs (dict, optional) – Optional kwargs to pass to the Ylm generator during instantiation. Default is {}.

• use_gpu (bool, optional) – If True, use GPU resources. Default is False.

• *args (list, placeholder) – args for waveform model.

• **kwargs (dict, placeholder) – kwargs for waveform model.

attributes_FastSchwarzschildEccentricFlux()

gpu_capability

If True, this wavefrom can leverage gpu resources. For this class it is True.

Type:

bool

allow_batching

If True, this waveform can use the batch_size kwarg. For this class it is False.

Type:

bool

property gpu_capability

Confirms GPU capability

__call__(M, mu, p0, e0, theta, phi, *args, dist=None, Phi_phi0=0.0, Phi_r0=0.0, dt=10.0, T=1.0, eps=1e-05, show_progress=False, batch_size=-1, mode_selection=None, include_minus_m=True, **kwargs)

Call function for SchwarzschildEccentric models.

This function will take input parameters and produce Schwarzschild eccentric waveforms. It will use all of the modules preloaded to compute desired outputs.

Parameters:

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

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

• p0 (double) – Initial semilatus rectum (\(10\leq p_0\leq16 + e_0\)). See documentation for more information on \(p_0<10\).

• e0 (double) – Initial eccentricity (\(0.0\leq e_0\leq0.7\)).

• theta (double) – Polar viewing angle (\(-\pi/2\leq\Theta\leq\pi/2\)).

• phi (double) – Azimuthal viewing angle.

• *args (list) – extra args for trajectory model.

• dist (double, optional) – Luminosity distance in Gpc. Default is None. If None, will return source frame.

• Phi_phi0 (double, optional) – Initial phase for \(\Phi_\phi\). Default is 0.0.

• Phi_r0 (double, optional) – Initial phase for \(\Phi_r\). Default is 0.0.

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

• T (double, optional) – Total observation time in years. Default is 1.0.

• eps (double, optional) – Controls the fractional accuracy during mode filtering. Raising this parameter will remove modes. Lowering this parameter will add modes. Default that gives a good overalp is 1e-5.

• show_progress (bool, optional) – If True, show progress through amplitude/waveform batches using tqdm. Default is False.

• batch_size (int, optional) – If less than 0, create the waveform without batching. If greater than zero, create the waveform batching in sizes of batch_size. Default is -1.

• mode_selection (str or list or None) – Determines the type of mode filtering to perform. If None, perform our base mode filtering with eps as the fractional accuracy on the total power. If ‘all’, it will run all modes without filtering. If a list of tuples (or lists) of mode indices (e.g. [(\(l_1,m_1,n_1\)), (\(l_2,m_2,n_2\))]) is provided, it will return those modes combined into a single waveform.

• include_minus_m (bool, optional) – If True, then include -m modes when computing a mode with m. This only effects modes if mode_selection is a list of specific modes. Default is True.

Returns:

The output waveform.

Return type:

1D complex128 xp.ndarray

Raises:

ValueError – user selections are not allowed.

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

inspiral_generator

instantiated trajectory module.

Type:

obj

amplitude_generator

instantiated amplitude module.

Type:

obj

ylm_gen

instantiated ylm module.

Type:

obj

create_waveform

instantiated summation module.

Type:

obj

ylm_gen

instantiated Ylm module.

Type:

obj

mode_selector

instantiated mode selection module.

Type:

obj

num_teuk_modes

number of Teukolsky modes in the model.

Type:

int

ls, ms, ns

Arrays of mode indices \((l,m,n)\) after filtering operation. If no filtering, these are equivalent to l_arr, m_arr, n_arr.

Type:

1D int xp.ndarray

xp

numpy or cupy based on gpu usage.

Type:

obj

num_modes_kept

Number of modes for final waveform after mode selection.

Type:

int

property citation

Return citations related to this module

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.

Slow Schwarzschild Eccentric Flux-based Waveform

class few.waveform.SlowSchwarzschildEccentricFlux(inspiral_kwargs={}, amplitude_kwargs={}, sum_kwargs={}, Ylm_kwargs={}, use_gpu=False, *args, **kwargs)

Bases: SchwarzschildEccentricWaveformBase

Prebuilt model for slow Schwarzschild eccentric flux-based waveforms.

This model combines the various modules to produce the a reference waveform against which we test our fast models. Please see few.utils.baseclasses.SchwarzschildEccentric for general information on this class of models.

The trajectory module used here is few.trajectory.flux for a flux-based trajectory. For this slow waveform, the DENSE_SAMPLING parameter from few.utils.baseclasses.TrajectoryBase is fixed to 1 to create a densely sampled trajectory.

The amplitudes are then determined with few.amplitude.interp2dcubicspline.Interp2DAmplitude along a densely sampled trajectory. This gives complex amplitudes for all modes in this model at each point in the trajectory. These, can be chosent to be filtered, but for reference waveforms, they should not be.

The modes that make it through the filter are then summed by few.summation.directmodesum.DirectModeSum.

See few.waveform.SchwarzschildEccentricWaveformBase for information on inputs. See examples as well.

Parameters:

• inspiral_kwargs (dict, optional) – Optional kwargs to pass to the inspiral generator. Important Note: These kwargs are passed online, not during instantiation like other kwargs here. Default is {}.

• amplitude_kwargs (dict, optional) – Optional kwargs to pass to the amplitude generator during instantiation. Default is {}.

• sum_kwargs (dict, optional) – Optional kwargs to pass to the sum module during instantiation. Default is {}.

• Ylm_kwargs (dict, optional) – Optional kwargs to pass to the Ylm generator during instantiation. Default is {}.

• use_gpu (bool, optional) – If True, use GPU resources. Default is False.

• *args (list, placeholder) – args for waveform model.

• **kwargs (dict, placeholder) – kwargs for waveform model.

property gpu_capability

Confirms GPU capability

attributes_SlowSchwarzschildEccentricFlux()

gpu_capability

If True, this wavefrom can leverage gpu resources. For this class it is False.

Type:

bool

allow_batching

If True, this waveform can use the batch_size kwarg. For this class it is True.

Type:

bool

__call__(M, mu, p0, e0, theta, phi, *args, dist=None, Phi_phi0=0.0, Phi_r0=0.0, dt=10.0, T=1.0, eps=1e-05, show_progress=False, batch_size=-1, mode_selection=None, include_minus_m=True, **kwargs)

Call function for SchwarzschildEccentric models.

This function will take input parameters and produce Schwarzschild eccentric waveforms. It will use all of the modules preloaded to compute desired outputs.

Parameters:

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

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

• p0 (double) – Initial semilatus rectum (\(10\leq p_0\leq16 + e_0\)). See documentation for more information on \(p_0<10\).

• e0 (double) – Initial eccentricity (\(0.0\leq e_0\leq0.7\)).

• theta (double) – Polar viewing angle (\(-\pi/2\leq\Theta\leq\pi/2\)).

• phi (double) – Azimuthal viewing angle.

• *args (list) – extra args for trajectory model.

• dist (double, optional) – Luminosity distance in Gpc. Default is None. If None, will return source frame.

• Phi_phi0 (double, optional) – Initial phase for \(\Phi_\phi\). Default is 0.0.

• Phi_r0 (double, optional) – Initial phase for \(\Phi_r\). Default is 0.0.

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

• T (double, optional) – Total observation time in years. Default is 1.0.

• eps (double, optional) – Controls the fractional accuracy during mode filtering. Raising this parameter will remove modes. Lowering this parameter will add modes. Default that gives a good overalp is 1e-5.

• show_progress (bool, optional) –

  If True, show progress through amplitude/waveform batches using tqdm. Default is False.

• batch_size (int, optional) – If less than 0, create the waveform without batching. If greater than zero, create the waveform batching in sizes of batch_size. Default is -1.

• mode_selection (str or list or None) – Determines the type of mode filtering to perform. If None, perform our base mode filtering with eps as the fractional accuracy on the total power. If ‘all’, it will run all modes without filtering. If a list of tuples (or lists) of mode indices (e.g. [(\(l_1,m_1,n_1\)), (\(l_2,m_2,n_2\))]) is provided, it will return those modes combined into a single waveform.

• include_minus_m (bool, optional) – If True, then include -m modes when computing a mode with m. This only effects modes if mode_selection is a list of specific modes. Default is True.

Returns:

The output waveform.

Return type:

1D complex128 xp.ndarray

Raises:

ValueError – user selections are not allowed.

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

inspiral_generator

instantiated trajectory module.

Type:

obj

amplitude_generator

instantiated amplitude module.

Type:

obj

ylm_gen

instantiated ylm module.

Type:

obj

create_waveform

instantiated summation module.

Type:

obj

ylm_gen

instantiated Ylm module.

Type:

obj

mode_selector

instantiated mode selection module.

Type:

obj

num_teuk_modes

number of Teukolsky modes in the model.

Type:

int

ls, ms, ns

Arrays of mode indices \((l,m,n)\) after filtering operation. If no filtering, these are equivalent to l_arr, m_arr, n_arr.

Type:

1D int xp.ndarray

xp

numpy or cupy based on gpu usage.

Type:

obj

num_modes_kept

Number of modes for final waveform after mode selection.

Type:

int

property citation

Return citations related to this module

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.

Generic Kerr AAK with 5PN Trajectory

class few.waveform.Pn5AAKWaveform(inspiral_kwargs={}, sum_kwargs={}, use_gpu=False, num_threads=None)

Bases: AAKWaveformBase, Pn5AAK, ParallelModuleBase, ABC

Waveform generation class for AAK with 5PN trajectory.

This class generates waveforms based on the Augmented Analytic Kludge given in the EMRI Kludge Suite. However, here the trajectory is vastly improved by employing the 5PN fluxes for generic Kerr orbits from Fujita & Shibata 2020.

The 5PN trajectory produces orbital and phase trajectories. The trajectory is calculated until the orbit reaches within 0.2 of the separatrix, determined from arXiv:1912.07609. The fundamental frequencies along the trajectory at each point are then calculated from the orbital parameters and the spin value given by (Schmidt 2002).

These frequencies along the trajectory are then used to map to the frequency basis of the Analytic Kludge. This mapping takes the form of time evolving large mass and spin parameters, as well as the use of phases and frequencies in \((alpha, \Phi, \gamma)\):

\[\Phi = \Phi_\phi,\]

\[\gamma = \Phi_\phi + \Phi_\Theta,\]

\[alpha = \Phi_\phi + \Phi_\Theta + \Phi_r.\]

The frequencies in that basis are found by taking the time derivatives of each equation above.

This class has GPU capabilities and works from the sparse trajectory methodoligy with cubic spine interpolation of the smoothly varying waveform quantities. This waveform does not have the freedom in terms of user-chosen quantitites that few.waveform.SchwarzschildEccentricWaveformBase contains. This is mainly due to the specific waveform constructions particular to the AAK/AK.

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:

• inspiral_kwargs (dict, optional) – Optional kwargs to pass to the inspiral generator. Important Note: These kwargs are passed online, not during instantiation like other kwargs here. Default is {}. This is stored as an attribute.

• sum_kwargs (dict, optional) – Optional kwargs to pass to the sum module during instantiation. Default is {}.

• use_gpu (bool, optional) – If True, use GPU resources. Default is False.

• num_threads (int, optional) – Number of parallel threads to use in OpenMP. If None, will not set the global variable OMP_NUM_THREADS. Default is None.

__call__(M, mu, a, p0, e0, Y0, dist, qS, phiS, qK, phiK, *args, Phi_phi0=0.0, Phi_theta0=0.0, Phi_r0=0.0, mich=False, dt=10.0, T=1.0)

Call function for AAK + 5PN model.

This function will take input parameters and produce AAK waveforms with 5PN trajectories in generic Kerr.

Parameters:

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

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

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

• p0 (double) – Initial semilatus rectum (Must be greater than the separatrix at the the given e0 and Y0). See documentation for more information.

• e0 (double) – Initial eccentricity.

• Y0 (double) – Initial cosine of \(\iota\). \(Y=\cos{\iota}\equiv L_z/\sqrt{L_z^2 + Q}\) in the semi-relativistic formulation.

• dist (double) – Luminosity distance in Gpc.

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

• *args (tuple, optional) – Any additional arguments required for the trajectory.

• Phi_phi0 (double, optional) – Initial phase for \(\Phi_\phi\). Default is 0.0.

• Phi_theta0 (double, optional) – Initial phase for \(\Phi_\Theta\). Default is 0.0.

• Phi_r0 (double, optional) – Initial phase for \(\Phi_r\). Default is 0.0.

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

• T (double, optional) – Total observation time in years. Default is 1.0.

Returns:

The output waveform.

Return type:

1D complex128 xp.ndarray

Raises:

ValueError – user selections are not allowed.

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

inspiral_generator

instantiated trajectory module.

Type:

obj

create_waveform

instantiated summation module.

Type:

obj

inspiral_kwargs

Kwargs related to the inspiral.

Type:

dict

xp

numpy or cupy based on gpu usage.

Type:

obj

num_modes_kept/nmodes

Number of modes for final waveform. For this model, it is solely determined from the eccentricity.

Type:

int

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

property gpu_capability

Indicator if the module has gpu capability

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.

attributes_Pn5AAKWaveform()

inspiral_generator

instantiated trajectory module.

Type:

obj

create_waveform

instantiated summation module.

Type:

obj

inspiral_kwargs

Kwargs related to the inspiral class: few.trajectory.pn5.RunKerrGenericPn5Inspiral.

Type:

dict

xp

numpy or cupy based on gpu usage.

Type:

obj

num_modes_kept/nmodes

Number of modes for final waveform. For this model, it is solely determined from the eccentricity.

Type:

int

property citation

Return citations related to this module

Base Classes

Schwarzschild Eccentric

class few.utils.baseclasses.SchwarzschildEccentric(*args, use_gpu=False, **kwargs)

Bases: ParallelModuleBase, ABC

Base class for Schwarzschild eccentric waveforms.

This class creates shared traits between different implementations of the same model. Particularly, this class includes descriptive traits as well as the sanity check class method that should be used in all implementations of this model. This method can be overwritten if necessary. Here we describe the overall qualities of this base class.

In this limit, Eq. (1) is reduced to the equatortial plane with no spin. Therefore, we only concerned with \((l,m,n)\) indices and the parameters \((p,e)\) because \(k=a=\iota=0\). Therefore, in this model we calculate \(A_{lmn}\) and \(\Phi_{mn}=m\Phi_\phi+n\Phi_r\). This also allows us to use -2 spin-weighted spherical harmonics (\((s=-2)Y_{l,m}\)) in place of the more generic angular function from Eq. (1).

\(l\) ranges from 2 to 10; \(m\) from \(-l\) to \(l\); and \(n\) from -30 to 30. This is for Schwarzschild eccentric. The model validity ranges from \(0.1 \leq e_0 \leq 0.7\) and \(10 \leq p_0 \leq 16 + 2*e_0\). The user can start at any \(p\) and \(e\) combination that exists under the \(p_0=10, e_0=0.7\) trajectory within those bounds (and is outside of the separatrix). Important Note: if the trajectory is within the bounds listed, but it is above \(p_0=10, e_0=0.7\) trajectory., the user may not receive an error. See the documentation introduction for more information on this.

Parameters:

use_gpu (bool, optional) – If True, will allocate arrays on the GPU. Default is False.

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

property citation

Return citations of this class

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.

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

classmethod __call__(*args, **kwargs)

Method to call waveform model

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.waveform.SchwarzschildEccentricWaveformBase(inspiral_module, amplitude_module, sum_module, inspiral_kwargs={}, amplitude_kwargs={}, sum_kwargs={}, Ylm_kwargs={}, mode_selector_kwargs={}, use_gpu=False, num_threads=None, normalize_amps=True)

Bases: SchwarzschildEccentric, ParallelModuleBase, ABC

Base class for the actual Schwarzschild eccentric waveforms.

This class carries information and methods that are common to any implementation of Schwarzschild eccentric waveforms. These include initialization and the actual base code for building a waveform. This base code calls the various modules chosen by the user or according to the predefined waveform classes available. See few.utils.baseclasses.SchwarzschildEccentric for information high level information on these waveform models.

Parameters:

• inspiral_module (obj) – Class object representing the module for creating the inspiral. This returns the phases and orbital parameters. See Trajectory Package.

• amplitude_module (obj) – Class object representing the module for generating amplitudes. See Amplitude Package for more information.

• sum_module (obj) – Class object representing the module for summing the final waveform from the amplitude and phase information. See Summation Package.

• inspiral_kwargs (dict, optional) – Optional kwargs to pass to the inspiral generator. Important Note: These kwargs are passed online, not during instantiation like other kwargs here. Default is {}. This is stored as an attribute.

• amplitude_kwargs (dict, optional) – Optional kwargs to pass to the amplitude generator during instantiation. Default is {}.

• sum_kwargs (dict, optional) – Optional kwargs to pass to the sum module during instantiation. Default is {}.

• Ylm_kwargs (dict, optional) – Optional kwargs to pass to the Ylm generator during instantiation. Default is {}.

• mode_selector_kwargs (dict, optional) – Optional kwargs to pass to the mode selector during instantiation. Default is {}.

• use_gpu (bool, optional) – If True, use GPU resources. Default is False.

• num_threads (int, optional) – Number of parallel threads to use in OpenMP. If None, will not set the global variable OMP_NUM_THREADS. Default is None.

• normalize_amps (bool, optional) – If True, it will normalize amplitudes to flux information output from the trajectory modules. Default is True. This is stored as an attribute.

attributes_SchwarzschildEccentricWaveformBase()

inspiral_generator

instantiated trajectory module.

Type:

obj

amplitude_generator

instantiated amplitude module.

Type:

obj

ylm_gen

instantiated ylm module.

Type:

obj

create_waveform

instantiated summation module.

Type:

obj

ylm_gen

instantiated Ylm module.

Type:

obj

mode_selector

instantiated mode selection module.

Type:

obj

num_teuk_modes

number of Teukolsky modes in the model.

Type:

int

ls, ms, ns

Arrays of mode indices \((l,m,n)\) after filtering operation. If no filtering, these are equivalent to l_arr, m_arr, n_arr.

Type:

1D int xp.ndarray

xp

numpy or cupy based on gpu usage.

Type:

obj

num_modes_kept

Number of modes for final waveform after mode selection.

Type:

int

property citation

Return citations related to this module

__call__(M, mu, p0, e0, theta, phi, *args, dist=None, Phi_phi0=0.0, Phi_r0=0.0, dt=10.0, T=1.0, eps=1e-05, show_progress=False, batch_size=-1, mode_selection=None, include_minus_m=True, **kwargs)

Call function for SchwarzschildEccentric models.

This function will take input parameters and produce Schwarzschild eccentric waveforms. It will use all of the modules preloaded to compute desired outputs.

Parameters:

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

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

• p0 (double) – Initial semilatus rectum (\(10\leq p_0\leq16 + e_0\)). See documentation for more information on \(p_0<10\).

• e0 (double) – Initial eccentricity (\(0.0\leq e_0\leq0.7\)).

• theta (double) – Polar viewing angle (\(-\pi/2\leq\Theta\leq\pi/2\)).

• phi (double) – Azimuthal viewing angle.

• *args (list) – extra args for trajectory model.

• dist (double, optional) – Luminosity distance in Gpc. Default is None. If None, will return source frame.

• Phi_phi0 (double, optional) – Initial phase for \(\Phi_\phi\). Default is 0.0.

• Phi_r0 (double, optional) – Initial phase for \(\Phi_r\). Default is 0.0.

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

• T (double, optional) – Total observation time in years. Default is 1.0.

• eps (double, optional) – Controls the fractional accuracy during mode filtering. Raising this parameter will remove modes. Lowering this parameter will add modes. Default that gives a good overalp is 1e-5.

• show_progress (bool, optional) –

  If True, show progress through amplitude/waveform batches using tqdm. Default is False.

• batch_size (int, optional) – If less than 0, create the waveform without batching. If greater than zero, create the waveform batching in sizes of batch_size. Default is -1.

• mode_selection (str or list or None) – Determines the type of mode filtering to perform. If None, perform our base mode filtering with eps as the fractional accuracy on the total power. If ‘all’, it will run all modes without filtering. If a list of tuples (or lists) of mode indices (e.g. [(\(l_1,m_1,n_1\)), (\(l_2,m_2,n_2\))]) is provided, it will return those modes combined into a single waveform.

• include_minus_m (bool, optional) – If True, then include -m modes when computing a mode with m. This only effects modes if mode_selection is a list of specific modes. Default is True.

Returns:

The output waveform.

Return type:

1D complex128 xp.ndarray

Raises:

ValueError – user selections are not allowed.

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.

5PN + AAK Waveform for Generic Kerr

class few.utils.baseclasses.Pn5AAK(use_gpu=False, **kwargs)

Bases: ABC

Base class for Pn5AAK waveforms.

This class contains some basic checks and information for AAK waveforms with a 5PN trajectory model. Please see few.waveform.Pn5AAKWaveform for more details.

Parameters:

use_gpu (bool, optional) – If True, will allocate arrays on the GPU. Default is False.

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

property citation

Return citations of 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_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.

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.

class few.waveform.AAKWaveformBase(inspiral_module, sum_module, inspiral_kwargs={}, sum_kwargs={}, use_gpu=False, num_threads=None)

Bases: Pn5AAK, ParallelModuleBase, ABC

Waveform generation class for AAK with arbitrary trajectory.

This class generates waveforms based on the Augmented Analytic Kludge given in the EMRI Kludge Suite. The trajectory is chosen by user or by default in child classes.

The trajectory is calculated until the orbit reaches within 0.1 of the separatrix, determined from arXiv:1912.07609. The fundamental frequencies along the trajectory at each point are then calculated from the orbital parameters and the spin value given by (Schmidt 2002).

These frequencies along the trajectory are then used to map to the frequency basis of the Analytic Kludge. This mapping takes the form of time evolving large mass and spin parameters, as well as the use of phases and frequencies in \((alpha, \Phi, \gamma)\):

\[\Phi = \Phi_\phi,\]

\[\gamma = \Phi_\phi + \Phi_\Theta,\]

\[alpha = \Phi_\phi + \Phi_\Theta + \Phi_r.\]

The frequencies in that basis are found by taking the time derivatives of each equation above.

This class has GPU capabilities and works from the sparse trajectory methodoligy with cubic spine interpolation of the smoothly varying waveform quantities.

Please note: the AAK waveform takes 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:

• inspiral_module (obj) – Class object representing the module for creating the inspiral. This returns the phases and orbital parameters. See Trajectory Package.

• sum_module (obj) – Class object representing the module for summing the final waveform from the amplitude and phase information. See Summation Package.

• inspiral_kwargs (dict, optional) – Optional kwargs to pass to the inspiral generator. Important Note: These kwargs are passed online, not during instantiation like other kwargs here. Default is {}. This is stored as an attribute.

• sum_kwargs (dict, optional) – Optional kwargs to pass to the sum module during instantiation. Default is {}.

• use_gpu (bool, optional) – If True, use GPU resources. Default is False.

• num_threads (int, optional) – Number of parallel threads to use in OpenMP. If None, will not set the global variable OMP_NUM_THREADS. Default is None.

attributes_AAKWaveform()

inspiral_generator

instantiated trajectory module.

Type:

obj

create_waveform

instantiated summation module.

Type:

obj

inspiral_kwargs

Kwargs related to the inspiral.

Type:

dict

xp

numpy or cupy based on gpu usage.

Type:

obj

num_modes_kept/nmodes

Number of modes for final waveform. For this model, it is solely determined from the eccentricity.

Type:

int

property citation

Return citations related to this module

property gpu_capability

Indicator if the module has gpu capability

__call__(M, mu, a, p0, e0, Y0, dist, qS, phiS, qK, phiK, *args, Phi_phi0=0.0, Phi_theta0=0.0, Phi_r0=0.0, mich=False, dt=10.0, T=1.0)

Call function for AAK + 5PN model.

This function will take input parameters and produce AAK waveforms with 5PN trajectories in generic Kerr.

Parameters:

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

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

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

• p0 (double) – Initial semilatus rectum (Must be greater than the separatrix at the the given e0 and Y0). See documentation for more information.

• e0 (double) – Initial eccentricity.

• Y0 (double) – Initial cosine of \(\iota\). \(Y=\cos{\iota}\equiv L_z/\sqrt{L_z^2 + Q}\) in the semi-relativistic formulation.

• dist (double) – Luminosity distance in Gpc.

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

• *args (tuple, optional) – Any additional arguments required for the trajectory.

• Phi_phi0 (double, optional) – Initial phase for \(\Phi_\phi\). Default is 0.0.

• Phi_theta0 (double, optional) – Initial phase for \(\Phi_\Theta\). Default is 0.0.

• Phi_r0 (double, optional) – Initial phase for \(\Phi_r\). Default is 0.0.

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

• T (double, optional) – Total observation time in years. Default is 1.0.

Returns:

The output waveform.

Return type:

1D complex128 xp.ndarray

Raises:

ValueError – user selections are not allowed.

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

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.

GPU Module Base Class

class few.utils.baseclasses.ParallelModuleBase(*args, use_gpu=False, **kwargs)

Bases: ABC

Base class for modules that can use GPUs.

This class mainly handles setting GPU usage.

Parameters:

use_gpu (bool, optional) – If True, use GPU resources. Default is False.

attributes_ParallelModuleBase()

use_gpu

If True, use GPU.

Type:

bool

xp

Either numpy or CuPy based on gpu preference.

Type:

obj

class property gpu_capability

Indicator if the module has gpu capability

property citation

Return citations related to this module

classmethod __call__(*args, **kwargs)

Method to call waveform model

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.

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.