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.waveform.GenerateEMRIWaveform(waveform_class, *args, frame='detector', return_list=False, flip_output=False, **kwargs)

Bases: Generic[WaveformModule]

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 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 | type[WaveformModule]) – 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 | tuple | None) – Arguments for the instantiation of the waveform generation class.

• frame (str) – 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) – If True, return \(h_p\) and \(h_x\) as a list. If False, return \(hp - ihx\). Default is False.

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

• flip_output (bool)

• **kwargs

waveform_generator: WaveformModule

Instance of the waveform module

frame: str

Frame in which waveform is generated.

return_list: bool

Whether to return \(h_p\) and \(h_x\) as list, otherwise returned as \(h_p - i h_x\)

flip_output: bool

Whether \(h_p\) and \(h_x\) output time series (if time-domain) should be reversed

args_remove: list[int]

List of arguments to remove based on the specific waveform

phases_needed: dict[str, int]

Phases needed based on specific waveform

__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 (float) – Mass of larger black hole in solar masses.

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

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

• p0 (float) – 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 (float) – Initial eccentricity.

• x0 (float) – 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 (float) – Luminosity distance in Gpc.

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

• Phi_phi0 (float) – Initial phase for \(\Phi_\phi\). Default is 0.0.

• Phi_theta0 (float) – Initial phase for \(\Phi_\Theta\). Default is 0.0.

• Phi_r0 (float) – Initial phase for \(\Phi_r\). Default is 0.0.

• *args – Tuple of any extra parameters that go into the model.

• **kwargs (dict | None) – Dictionary with kwargs for online waveform generation.

• add_args (tuple | None)

• **kwargs

Return type:

ndarray | list

Prebuilt Waveform Models

Fast Kerr Eccentric Equatorial Flux-based Waveform

class few.waveform.waveform.FastKerrEccentricEquatorialFlux(inspiral_kwargs=None, amplitude_kwargs=None, sum_kwargs=None, Ylm_kwargs=None, mode_selector_kwargs=None, force_backend=None, **kwargs)

Bases: SphericalHarmonicWaveformBase, KerrEccentricEquatorial

Prebuilt model for fast Kerr eccentric equatorial 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.

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

The amplitudes are then determined with few.amplitude.ampinterp2d.AmpInterp2D 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.base.SphericalHarmonicWaveformBase for information on inputs. See examples as well.

Parameters:

• inspiral_kwargs (dict) – 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 | None) – Optional kwargs to pass to the amplitude generator during instantiation. Default is {}.

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

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

• *args – args for waveform model.

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

• mode_selector_kwargs (dict | None)

• force_backend (str | Backend | None)

• **kwargs

inspiral_kwargs: dict

Keyword arguments passed to the inspiral generator call function

classmethod supported_backends()

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

__call__(M, mu, a, p0, e0, xI, theta, phi, *args, **kwargs)

Generate the waveform.

Parameters:

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

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

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

• p0 (float) – Initial semilatus rectum of inspiral trajectory.

• e0 (float) – Initial eccentricity of inspiral trajectory.

• xI (float) – Initial cosine of the inclination angle.

• theta (float) – Polar angle of observer.

• phi (float) – Azimuthal angle of observer.

• *args (tuple | None) – Placeholder for additional arguments.

• **kwargs (dict | None) – Placeholder for additional keyword arguments.

Returns:

Complex array containing generated waveform.

Return type:

ndarray

static CPU_ONLY()

List of supported backend for CPU only class

Return type:

list[str]

static CPU_RECOMMENDED_WITH_GPU_SUPPORT()

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]

static GPU_RECOMMENDED()

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

background: str = 'Kerr'

The spacetime background for this model.

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

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

Parameters:

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

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

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

Return type:

ParallelModuleDerivate

classmethod citation()

Return the module references as a printable BibTeX string.

Return type:

str

descriptor: str = 'eccentric equatorial'

Description of the inspiral trajectory properties for this model.

frame: str = 'source'

Frame in which source is generated. Is source frame.

classmethod module_references()

Method implemented by each class to define its list of references

Return type:

List[REFERENCE | str]

needs_Y: bool = False

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

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

Sanity check initial parameters.

Make sure parameters are within allowable ranges.

Parameters:

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

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

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

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

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

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

Returns:

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

Return type:

(a_fix, xI_fix)

Raises:

ValueError – If any of the parameters are not allowed.

sanity_check_traj(a, p, e, xI)

Sanity check on parameters output from the trajectory module.

Make sure parameters are within allowable ranges.

Parameters:

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

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

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

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

Raises:

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

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

sanity_check_viewing_angles(theta, phi)

Sanity check on viewing angles.

Make sure parameters are within allowable ranges.

Parameters:

• theta (double) – Polar viewing angle.

• phi (double) – Azimuthal viewing angle.

Returns:

(theta, phi). Phi is wrapped.

Return type:

tuple

Raises:

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

property xp: ModuleType

Return the module providing ndarray capabilities

normalize_amps: bool

Whether to normalize amplitudes to flux at each step from trajectory

inspiral_generator: InspiralModule

Instance of the trajectory module

amplitude_generator: AmplitudeModule

Instance of the amplitude module

create_waveform: SumModule

Instance of the summation module

ylm_gen: GetYlms

Instance of the Ylm module

mode_selector: ModeSelectorModule

Instance of the mode selector module

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.

Fast Schwarzschild Eccentric Flux-based Waveform

class few.waveform.waveform.FastSchwarzschildEccentricFlux(inspiral_kwargs=None, amplitude_kwargs=None, sum_kwargs=None, Ylm_kwargs=None, mode_selector_kwargs=None, force_backend=None, **kwargs)

Bases: SphericalHarmonicWaveformBase, SchwarzschildEccentric

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.

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

The amplitudes are then determined with few.amplitude.romannet 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.base.SphericalHarmonicWaveformBase for information on inputs. See examples as well.

Parameters:

• inspiral_kwargs (dict) – 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 | None) – Optional kwargs to pass to the amplitude generator during instantiation. Default is {}.

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

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

• *args – args for waveform model.

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

• mode_selector_kwargs (dict | None)

• force_backend (str | Backend | None)

• **kwargs

inspiral_kwargs: dict

Keyword arguments passed to the inspiral generator call function

classmethod supported_backends()

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

__call__(M, mu, p0, e0, theta, phi, *args, **kwargs)

Generate the waveform.

Parameters:

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

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

• p0 (float) – Initial semilatus rectum of inspiral trajectory.

• e0 (float) – Initial eccentricity of inspiral trajectory.

• theta (float) – Polar angle of observer.

• phi (float) – Azimuthal angle of observer.

• *args (tuple | None) – Placeholder for additional arguments.

• **kwargs (dict | None) – Placeholder for additional keyword arguments.

Returns:

Complex array containing generated waveform.

Return type:

ndarray

static CPU_ONLY()

List of supported backend for CPU only class

Return type:

list[str]

static CPU_RECOMMENDED_WITH_GPU_SUPPORT()

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]

static GPU_RECOMMENDED()

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

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

normalize_amps: bool

Whether to normalize amplitudes to flux at each step from trajectory

inspiral_generator: InspiralModule

Instance of the trajectory module

amplitude_generator: AmplitudeModule

Instance of the amplitude module

create_waveform: SumModule

Instance of the summation module

ylm_gen: GetYlms

Instance of the Ylm module

mode_selector: ModeSelectorModule

Instance of the mode selector module

ndim: int

Number of phases in the model.

lmax: int

Maximum l value for the model.

nmax: int

Maximum n value for the model.

num_modes: int

Total number of modes in the model

num_teuk_modes: int

Number of Teukolsky modes in the model.

m0sort: xp_ndarray

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

l_arr_no_mask: xp_ndarray

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

m_arr_no_mask: xp_ndarray

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

n_arr_no_mask: xp_ndarray

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

lmn_indices: dict[int, int]

Dictionary of mode indices to mode number.

m0mask: xp_ndarray

1D Array Mask for m != 0.

num_m_zero_up: int

Number of modes with m >= 0.

num_m0: int

Number of modes with m == 0.

num_m_1_up: int

Number of modes with m > 0.

l_arr: xp_ndarray

1D Array of l values for each mode.

m_arr: xp_ndarray

1D Array of m values for each mode.

n_arr: xp_ndarray

1D Array of n values for each mode.

m_zero_up_mask: xp_ndarray

1D Mask for m >= 0.

unique_l: xp_ndarray

1D Array of unique l values.

unique_m: xp_ndarray

1D Array of unique m values.

num_unique_lm: int

Number of unique (l,m) values.

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

Maps mode index to mode tuple.

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

Maps mode index to mode tuple with m > 0.

index_map_arr: xp_ndarray

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

special_index_map_arr: xp_ndarray

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

class few.waveform.waveform.FastSchwarzschildEccentricFluxBicubic(inspiral_kwargs=None, amplitude_kwargs=None, sum_kwargs=None, Ylm_kwargs=None, mode_selector_kwargs=None, force_backend=None, **kwargs)

Bases: SphericalHarmonicWaveformBase, SchwarzschildEccentric

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.

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

The amplitudes are then determined with few.amplitude.interp2dcubicspline.AmpInterp2D 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.base.SphericalHarmonicWaveformBase for information on inputs. See examples as well.

Parameters:

• inspiral_kwargs (dict) – 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 | None) – Optional kwargs to pass to the amplitude generator during instantiation. Default is {}.

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

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

• *args – args for waveform model.

• **kwargs (dict | None) – kwargs for waveform model.

• mode_selector_kwargs (dict | None)

• force_backend (str | Backend | None)

• **kwargs

static CPU_ONLY()

List of supported backend for CPU only class

Return type:

list[str]

static CPU_RECOMMENDED_WITH_GPU_SUPPORT()

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]

static GPU_RECOMMENDED()

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

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

normalize_amps: bool

Whether to normalize amplitudes to flux at each step from trajectory

inspiral_generator: InspiralModule

Instance of the trajectory module

amplitude_generator: AmplitudeModule

Instance of the amplitude module

create_waveform: SumModule

Instance of the summation module

ylm_gen: GetYlms

Instance of the Ylm module

mode_selector: ModeSelectorModule

Instance of the mode selector module

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.

inspiral_kwargs: dict

Keyword arguments passed to the inspiral generator call function

classmethod supported_backends()

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

__call__(M, mu, p0, e0, theta, phi, *args, **kwargs)

Generate the waveform.

Parameters:

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

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

• p0 (float) – Initial semilatus rectum of inspiral trajectory.

• e0 (float) – Initial eccentricity of inspiral trajectory.

• theta (float) – Polar angle of observer.

• phi (float) – Azimuthal angle of observer.

• *args (tuple | None) – Placeholder for additional arguments.

• **kwargs (dict | None) – Placeholder for additional keyword arguments.

Returns:

Complex array containing generated waveform.

Return type:

ndarray

Slow Schwarzschild Eccentric Flux-based Waveform

class few.waveform.waveform.SlowSchwarzschildEccentricFlux(inspiral_kwargs=None, amplitude_kwargs=None, sum_kwargs=None, Ylm_kwargs=None, force_backend=None, **kwargs)

Bases: SphericalHarmonicWaveformBase, SchwarzschildEccentric

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.inspiral for a flux-based trajectory. For this slow waveform, the DENSE_STEPPING parameter from few.trajectory.base.TrajectoryBase is fixed to 1 to create a densely sampled trajectory.

The amplitudes are then determined with few.amplitude.interp2dcubicspline.AmpInterp2D along a densely sampled trajectory. This gives complex amplitudes for all modes in this model at each point in the trajectory.

As this class is meant to be a reference waveform class, all waveform mode amplitudes are used. The modes are summed by few.summation.directmodesum.DirectModeSum.

See few.waveform.base.SphericalHarmonicWaveformBase for information on inputs. See examples as well.

Parameters:

• inspiral_kwargs (dict) – 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 | None) – Optional kwargs to pass to the amplitude generator during instantiation. Default is {}.

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

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

• *args – args for waveform model.

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

• force_backend (str | Backend | None)

• **kwargs

static CPU_ONLY()

List of supported backend for CPU only class

Return type:

list[str]

static CPU_RECOMMENDED_WITH_GPU_SUPPORT()

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]

static GPU_RECOMMENDED()

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

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

normalize_amps: bool

Whether to normalize amplitudes to flux at each step from trajectory

inspiral_generator: InspiralModule

Instance of the trajectory module

amplitude_generator: AmplitudeModule

Instance of the amplitude module

create_waveform: SumModule

Instance of the summation module

ylm_gen: GetYlms

Instance of the Ylm module

mode_selector: ModeSelectorModule

Instance of the mode selector module

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.

classmethod supported_backends()

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

inspiral_kwargs: dict

Keyword arguments passed to the inspiral generator call function

__call__(M, mu, p0, e0, theta, phi, *args, **kwargs)

Generate the waveform.

Parameters:

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

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

• p0 (float) – Initial semilatus rectum of inspiral trajectory.

• e0 (float) – Initial eccentricity of inspiral trajectory.

• theta (float) – Polar angle of observer.

• phi (float) – Azimuthal angle of observer.

• *args (tuple | None) – Placeholder for additional arguments.

• **kwargs (dict | None) – Placeholder for additional keyword arguments.

Returns:

Complex array containing generated waveform.

Return type:

ndarray

Generic Kerr AAK with 5PN Trajectory

class few.waveform.waveform.Pn5AAKWaveform(inspiral_kwargs=None, sum_kwargs=None, force_backend=None)

Bases: AAKWaveformBase

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.base.SphericalHarmonicWaveformBase 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 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 | None) – Optional kwargs to pass to the sum module during instantiation. Default is {}.

• force_backend (str | Backend | None)

static CPU_ONLY()

List of supported backend for CPU only class

Return type:

list[str]

static CPU_RECOMMENDED_WITH_GPU_SUPPORT()

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]

static GPU_RECOMMENDED()

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

Return type:

list[str]

__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, nmodes=None)

Call function for AAK + 5PN model.

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

Parameters:

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

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

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

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

• e0 (float) – Initial eccentricity.

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

• dist (float) – Luminosity distance in Gpc.

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

• *args (tuple | None) – Any additional arguments required for the trajectory.

• Phi_phi0 (float) – Initial phase for \(\Phi_\phi\). Default is 0.0.

• Phi_theta0 (float) – Initial phase for \(\Phi_\Theta\). Default is 0.0.

• Phi_r0 (float) – Initial phase for \(\Phi_r\). Default is 0.0.

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

• T (float) – Total observation time in years. Default is 1.0.

• nmodes (int | None)

Returns:

The output waveform.

Raises:

ValueError – user selections are not allowed.

Return type:

ndarray

adapt_backend_kwargs(kwargs=None)

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

Parameters:

kwargs (dict | None)

Return type:

dict

property backend: Backend

Access the underlying backend.

property backend_name: str

Return the name of current backend

background: str = 'Kerr'

The spacetime background for this model.

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

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

Parameters:

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

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

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

Return type:

ParallelModuleDerivate

classmethod citation()

Return the module references as a printable BibTeX string.

Return type:

str

descriptor: str = 'eccentric 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

inspiral_kwargs: dict

Keyword arguments passed to the inspiral generator call function

inspiral_generator: InspiralModule

Instance of the trajectory module

create_waveform: SumModule

Instance of the summation module

num_modes_kept: int

Number of modes for final waveform (unset before call). For this model, it is solely determined from the eccentricity.

classmethod supported_backends()

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

Base Classes

Spherical Harmonic (Flux-based) Waveforms

class few.utils.baseclasses.SphericalHarmonic(lmax=10, nmax=30, force_backend=None)

Bases: ParallelModuleBase

Base class for waveforms constructed in a spherical harmonic basis.

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.

Currently, Eq. (1) is reduced to the equatorial plane. Therefore, we only concerned with \((l,m,n)\) indices and the parameters \((a, p,e)\) because \(k=|\iota|=0\). Therefore, in this model we calculate \(A_{lmn}\) and \(\Phi_{mn}=m\Phi_\phi+n\Phi_r\). As we assume the amplitudes have been remapped to a spherical harmonic basis, we use -2 spin-weighted spherical harmonics (\((s=-2)Y_{l,m}\)) in place of the more generic angular function from Eq. (1).

Parameters:

• lmax (int)

• nmax (int)

• force_backend (BackendLike)

m0sort: xp_ndarray

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

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.

static CPU_ONLY()

List of supported backend for CPU only class

Return type:

list[str]

static CPU_RECOMMENDED_WITH_GPU_SUPPORT()

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]

static GPU_RECOMMENDED()

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

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.

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

class few.waveform.base.SphericalHarmonicWaveformBase(inspiral_module, amplitude_module, sum_module, mode_selector_module, inspiral_kwargs=None, amplitude_kwargs=None, sum_kwargs=None, Ylm_kwargs=None, mode_selector_kwargs=None, normalize_amps=False, force_backend=None)

Bases: ParallelModuleBase, Generic[InspiralModule, AmplitudeModule, SumModule, ModeSelectorModule]

Base class for waveforms built with amplitudes expressed in a spherical harmonic basis.

This class contains the methods required to build the core waveform for Kerr equatorial eccentric (to be upgraded to Kerr generic once that is available). Stock waveform classes constructed in this basis can subclass this class and implement their own “__call__” method to fill in the relevant data.

Parameters:

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

• amplitude_module (type[AmplitudeModule]) – Class object representing the module for creating the amplitudes. This returns the complex amplitudes of the modes. See Amplitude Package.

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

• mode_selector_module (type[ModeSelectorModule]) – Class object representing the module for selecting modes that contribute to the waveform. See Utilities.

• inspiral_kwargs (dict) – Optional kwargs to pass to the inspiral generator. Default is {}.

• amplitude_kwargs (dict | None) – Optional kwargs to pass to the amplitude generator. Default is {}.

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

• Ylm_kwargs (dict | None) – Optional kwargs to pass to the Ylm generator. Default is {}.

• mode_selector_kwargs (dict | None) – Optional kwargs to pass to the mode selector module. Default is {}.

• normalize_amps (bool) – If True, normalize the amplitudes at each step of the trajectory. This option should be used alongside ROMAN networks that have been trained with normalized amplitudes. Default is False.

• force_backend (str | Backend | None)

normalize_amps: bool

Whether to normalize amplitudes to flux at each step from trajectory

inspiral_kwargs: dict

Keyword arguments passed to the inspiral generator call function

inspiral_generator: InspiralModule

Instance of the trajectory module

amplitude_generator: AmplitudeModule

Instance of the amplitude module

create_waveform: SumModule

Instance of the summation module

ylm_gen: GetYlms

Instance of the Ylm module

mode_selector: ModeSelectorModule

Instance of the mode selector module

static CPU_ONLY()

List of supported backend for CPU only class

Return type:

list[str]

static CPU_RECOMMENDED_WITH_GPU_SUPPORT()

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]

static GPU_RECOMMENDED()

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

Schwarzschild Eccentric

class few.utils.baseclasses.SchwarzschildEccentric(lmax=10, nmax=30, ndim=2, force_backend=None)

Bases: SphericalHarmonic

Schwarzschild eccentric base class.

Parameters:

• lmax (int) – Maximum l value for the model. Default is 10.

• nmax (int) – Maximum n value for the model. Default is 30.

• ndim (int) – Number of phases in the model. Default is 2.

• force_backend (BackendLike)

static CPU_ONLY()

List of supported backend for CPU only class

Return type:

list[str]

static CPU_RECOMMENDED_WITH_GPU_SUPPORT()

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]

static GPU_RECOMMENDED()

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]

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

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.

background: str = 'Schwarzschild'

The spacetime background for this model.

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

ndim: int

Number of phases in the model.

classmethod supported_backends()

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

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.

Kerr Eccentric Equatorial

class few.utils.baseclasses.KerrEccentricEquatorial(lmax=10, nmax=55, ndim=2, force_backend=None)

Bases: SphericalHarmonic

Kerr eccentric equatorial base class.

Parameters:

• lmax (int) – Maximum l value for the model. Default is 10.

• nmax (int) – Maximum n value for the model. Default is 55.

• ndim (int) – Number of phases in the model. Default is 2.

• force_backend (BackendLike)

static CPU_ONLY()

List of supported backend for CPU only class

Return type:

list[str]

static CPU_RECOMMENDED_WITH_GPU_SUPPORT()

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]

static GPU_RECOMMENDED()

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]

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

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.

background: str = 'Kerr'

The spacetime background for this model.

descriptor: str = 'eccentric equatorial'

Description of the inspiral trajectory properties for this model.

frame: str = 'source'

Frame in which source is generated. Is source frame.

needs_Y: bool = False

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

ndim: int

Number of phases in the model.

classmethod supported_backends()

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

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

Sanity check initial parameters.

Make sure parameters are within allowable ranges.

Parameters:

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

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

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

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

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

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

Returns:

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

Return type:

(a_fix, xI_fix)

Raises:

ValueError – If any of the parameters are not allowed.

5PN + AAK Waveform for Generic Kerr

class few.utils.baseclasses.Pn5AAK

Bases: Citable

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.

classmethod citation()

Return the module references as a printable BibTeX string.

Return type:

str

background: str = 'Kerr'

The spacetime background for this model.

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.

needs_Y: bool = True

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

classmethod module_references()

Return citations related to this module

Return type:

list[REFERENCE]

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

class few.waveform.waveform.AAKWaveformBase(inspiral_module, sum_module, inspiral_kwargs=None, sum_kwargs=None, force_backend=None)

Bases: Pn5AAK, ParallelModuleBase, Generic[InspiralModule, SumModule]

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 (type[InspiralModule]) – Class object representing the module for creating the inspiral. This returns the phases and orbital parameters. See Trajectory Package.

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

• inspiral_kwargs (dict) – 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 | None) – Optional kwargs to pass to the sum module during instantiation. Default is {}.

• force_backend (str | Backend | None)

static CPU_ONLY()

List of supported backend for CPU only class

Return type:

list[str]

static CPU_RECOMMENDED_WITH_GPU_SUPPORT()

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]

static GPU_RECOMMENDED()

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

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.

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

inspiral_kwargs: dict

Keyword arguments passed to the inspiral generator call function

inspiral_generator: InspiralModule

Instance of the trajectory module

create_waveform: SumModule

Instance of the summation module

num_modes_kept: int

Number of modes for final waveform (unset before call). For this model, it is solely determined from the eccentricity.

classmethod module_references()

Return citations related to this module

Return type:

list[REFERENCE]

classmethod supported_backends()

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

__call__(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, nmodes=None)

Call function for AAK + 5PN model.

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

Parameters:

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

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

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

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

• e0 (float) – Initial eccentricity.

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

• dist (float) – Luminosity distance in Gpc.

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

• *args (tuple | None) – Any additional arguments required for the trajectory.

• Phi_phi0 (float) – Initial phase for \(\Phi_\phi\). Default is 0.0.

• Phi_theta0 (float) – Initial phase for \(\Phi_\Theta\). Default is 0.0.

• Phi_r0 (float) – Initial phase for \(\Phi_r\). Default is 0.0.

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

• T (float) – Total observation time in years. Default is 1.0.

• nmodes (int | None)

Returns:

The output waveform.

Raises:

ValueError – user selections are not allowed.

Return type:

ndarray

GPU Module Base Class

class few.utils.baseclasses.ParallelModuleBase(force_backend=None)

Bases: Citable

Base class for modules that can use a GPU (or revert back to CPU).

This class mainly handles backend selection. Each backend offers accelerated computations on a specific device (cpu, CUDA 11.x enabled GPU, CUDA 12.x enabled GPU).

Parameters:

force_backend (str, optional) – Name of the backend to use

property backend: Backend

Access the underlying backend.

classmethod supported_backends()

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

Return type:

Sequence[str]

static CPU_ONLY()

List of supported backend for CPU only class

Return type:

list[str]

static GPU_RECOMMENDED()

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

Return type:

list[str]

static CPU_RECOMMENDED_WITH_GPU_SUPPORT()

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]

property xp: ModuleType

Return the module providing ndarray capabilities

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

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

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]