Fast GB Waveforms and Likelihoods

class gbgpu.gbgpu.GBGPU(orbits: Orbits = None, force_backend=None)

Bases: GBGPUBase

Inherit this class to expand on GBGPU waveforms.

The required methods to be added are shown below.

property A

return A channel reshaped based on number of binaries

property A_out

A channel.

static CPU_ONLY() → list[str]

List of supported backend for CPU only class

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

property E

return E channel reshaped based on number of binaries

property E_out

E channel.

static GPU_ONLY() → list[str]

List of supported backends for GPU-only class

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

property T

return T channel reshaped based on number of binaries

property T_out

T channel.

property X

return X channel reshaped based on number of binaries

property X_out

X channel.

property Y

return Y channel reshaped based on number of binaries

property Y_out

Y channel.

property Z

return Z channel reshaped based on number of binaries

property Z_out

Z channel.

adapt_backend_kwargs(kwargs: dict | None = None) → dict

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

property backend: Backend

Access the underlying backend.

property backend_name: str

Return the name of current backend

build_with_same_backend(module_class: type[ParallelModuleDerivate], args: list | None = None, kwargs: dict | None = None) → ParallelModuleDerivate

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

Parameters:

  • module_class – 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)

property citation

Get citations for this class

property fill_global_func

fill_global c func.

fill_global_template(group_index, templates, A, E, start_inds, N=None, start_freq_ind=0)

Fill many global templates with waveforms

This method takes already generated waveforms (A, E, start_inds) and their associated grouping index (group_index) and fills buffer tempalte arrays (templates).

This method combines waveforms that have already been created. When a user does not have the waveforms in hand, they should use the generate_global_template() method.

Parameters:

  • group_index (1D double int32 xp.ndarray) – Index indicating to which template each individual binary belongs.

  • templates (3D complex128 xp.ndarray) – Buffer array for template output to filled in place. The shape is (number of templates, 2, data_length). The 2 is for the A and E TDI channels in that order.

  • A (1D or 2D complex128 xp.ndarray) – TDI A channel template values for each individual binary. The shape if 2D is (number of binaries, N)''. In 1D, the array should be arranged so that it resembles ``(number of binaries, N).transpose().flatten(). After running waveforms, this is how self.A_out is arranged.

  • E (1D 2D complex128 xp.ndarray) – TDI E channel template values for each individual binary. The shape if 2D is (number of binaries, N)''. In 1D, the array should be arranged so that it resembles ``(number of binaries, N).transpose().flatten(). After running waveforms, this is how self.E_out is arranged.

  • start_inds (1D int32 xp.ndarray) – The start indices of each binary waveform in the full Fourier transform: int(f0/T) - N/2.

  • N (int, optional) – The length of the A and E channels for each individual binary. When A and E are 1D, N must be given. Default is None.

  • start_freq_ind (int, optional) – Starting index into the frequency-domain data stream for the first entry of templates. This is used if a subset of a full data stream is presented for the computation.

Raises:

  • TypeError – If data arrays are NumPy/CuPy while tempalte arrays are CuPy/NumPy.

  • ValueError – Inputs are not correctly provided.

property freqs

Return frequencies associated with each signal

generate_global_template(params, group_index, templates, start_freq_ind=0, **kwargs)

Generate global templates from binary parameters

Generate waveforms in batches and then combine them into global fit templates. This method wraps fill_global_template() by building the waveforms first.

Parameters:

  • params (2D double np.ndarrays) – Parameters of all binaries to be calculated. The shape is (number of parameters, number of binaries).

  • group_index (1D double int32 xp.ndarray) – Index indicating to which template each individual binary belongs.

  • templates (3D complex128 xp.ndarray) – Buffer array for template output to filled in place. The shape is (number of templates, 2, data_length). The 2 is for the A and E TDI channels in that order.

  • start_freq_ind (int, optional) – Starting index into the frequency-domain data stream for the first entry of templates. This is used if a subset of a full data stream is presented for the computation.

  • **kwargs (dict, optional) – Passes keyword arguments to run_wave() function above.

get_ll(params, data, psd, phase_marginalize=False, start_freq_ind=0, data_index=None, noise_index=None, **kwargs)

Get batched log likelihood

Generate the individual log likelihood for a batched set of Galactic binaries. This is also GPU/CPU agnostic.

Parameters:

  • params (2D double np.ndarrays) – Parameters of all binaries to be calculated. The shape is (number of parameters, number of binaries).

  • data (length 2 list of 1D or 2D complex128 xp.ndarrays) – List of arrays representing the data stream. These should be CuPy arrays if running on the GPU, NumPy arrays if running on a CPU. The list should be [A channel, E channel]. Should be 1D if only one data stream is analyzed. If 2D, shape is (number of data streams, data_length). If 2D, user must also provide data_index kwarg.

  • psd (length 2 list of 1D or 2D double xp.ndarrays) – List of arrays representing the power spectral density (PSD) in the noise. These should be CuPy arrays if running on the GPU, NumPy arrays if running on a CPU. The list should be [A channel, E channel]. Should be 1D if only one PSD is analyzed. If 2D, shape is (number of PSDs, data_length). If 2D, user must also provide noise_index kwarg.

  • phase_marginalize (bool, optional) – If True, marginalize over the initial phase. Default is False.

  • start_freq_ind (int, optional) – Starting index into the frequency-domain data stream for the first entry of data/psd. This is used if a subset of a full data stream is presented for the computation. If providing mutliple data streams in data, this single start index value will apply to all of them.

  • data_index (1D xp.int32 array, optional) – If providing 2D data, need to provide data_index to indicate the data stream associated with each waveform for which the log-Likelihood is being computed. For example, if you have 100 binaries with 5 different data streams, data_index will be a length-100 xp.int32 array with values 0 to 4, indicating the specific data stream to use for each source. If None, this will be filled with zeros and only analyzed with the first data stream given. Default is None.

  • noise_index (1D xp.int32 array, optional) – If providing 2D psd, need to provide noise_index to indicate the PSD associated with each waveform for which the log-Likelihood is being computed. For example, if you have 100 binaries with 5 different PSDs, noise_index will be a length-100 xp.int32 array with values 0 to 4, indicating the specific PSD to use for each source. If None, this will be filled with zeros and only analyzed with the first PSD given. Default is None.

  • **kwargs (dict, optional) – Passes keyword arguments to the run_wave() method.

Raises:

TypeError – If data arrays are NumPy/CuPy while template arrays are CuPy/NumPy.

Returns:

Log likelihood values associated with each binary.

Return type:

1D double np.ndarray

property get_ll_func

get_ll c func.

information_matrix(params, eps=1e-09, parameter_transforms={}, inds=None, N=1024, psd_func=None, psd_kwargs={}, easy_central_difference=False, return_gpu=False, **kwargs)

Get the information matrix for a batch.

This function computes the Information matrix for a batch of Galactic binaries. It uses a 2nd order calculation for the derivative if easy_central_difference is False:

..math:: frac{dh}{dlambda_i} = frac{-h(lambda_i + 2epsilon) + h(lambda_i - 2epsilon) + 8(h(lambda_i + epsilon) - h(lambda_i - epsilon))}{12epsilson}

Otherwise, it will just calculate the derivate with a first-order central difference.

This function maps all parameter values to 1. For example, if the square root of the diagonal of the associated covariance matrix is 1e-7 for the frequency parameter, then the standard deviation in the frequency is 1e-7 * f0. To properly use with covariance values not on the diagonal, they will have to be multipled by the parameters: \(C_{ij} \vec{\theta}_j\).

Parameters:

  • params (2D double np.ndarrays) – Parameters of all binaries to be calculated. The shape is (number of parameters, number of binaries). See run_wave() for more information on the adjustable number of parameters when calculating for a third body.

  • eps (double, optional) – Step to take when calculating the derivative. The step is relative difference. Default is 1e-9.

  • parameter_transforms (dict, optional) – Dictionary containing the parameter transform functions. The keys in the dict should be the index associated with the parameter. The items should be the actual transform function. Default is no transforms ({}).

  • inds (1D int np.ndarray, optional) – Numpy array with the indexes of the parameters to test in the Information matrix. Default is None. When it is not given, it defaults to all parameters.

  • N (int, optional) – Number of points for the waveform. Same as the N parameter in run_wave(). We recommend using higher N in the Information Matrix computation because of the numerical derivatives. Default is 1024.

  • psd_func (object, optional) – Function to compute the PSD for the A and E channels. Must take on argument: the frequencies as an xp.ndarray. When None, it attemps to use the sensitivity functions from LISA Analysis Tools.

  • psd_kwargs (dict, optional) – Keyword arguments for the TDI noise generator. Default is None.

  • easy_central_difference (bool, optional) – If True, compute the derivatives with a first-order central difference computation. If False, use the higher order derivative that computes two more waveforms during the derivative calculation. Default is False.

  • return_gpu (False, optional) – If True and backend is GPU-based, return Information matrices in cupy array. Default is False.

Returns:

Information Matrices for all binaries with shape: (number of binaries, number of parameters, number of parameters).

Return type:

3D xp.ndarray

Raises:

  • ValueError – Step size issues.

  • ModuleNotFoundError – LISA Analysis Tools package not available. Occurs when NOT providing psd_func kwarg.

inject_signal(*args, fmax=None, T=126232599.05418241, dt=10.0, **kwargs)

Inject a single signal

Provides the injection of a single signal into a data stream with frequencies spanning from 0.0 to fmax with 1/T spacing (from Fourier transform).

Parameters:

  • *args (list, tuple, or 1D double np.array) – Arguments to provide to run_wave() to build the TDI templates for injection.

  • fmax (double, optional) – Maximum frequency to use in data stream. If None, will use 1/(2 * dt). Default is None.

  • T (double, optional) – Observation time in seconds. Default is 4 * YRSID_SI.

  • dt (double, optional) – Observation cadence in seconds. Default is 10.0 seconds.

  • **kwargs (dict, optional) – Passes kwargs to run_wave().

Returns:

NumPy arrays for the A channel and

E channel: (A channel, E channel). Need to convert to CuPy if working on GPU.

Return type:

Tuple of 1D np.ndarrays

property orbits: Orbits

Orbits class.

prepare_additional_args(*args)

Prepare the arguments special to this class

This function must take in the extra args input into GBGPU.run_wave() and transform them as needed to input into the rest of the code. If using GPUs, this is where the parameters are copied to GPUs.

Parameters:

*args (tuple) – Any additional args to be dealt with.

Returns:

New args. In the rest of the code this is add_args.

Return type:

Tuple

run_wave(amp, f0, fdot, fddot, phi0, iota, psi, lam, beta, *args, N=None, T=126232599.05418241, dt=10.0, oversample=1, tdi2=False)

Create waveforms in batches.

This call creates the TDI templates in batches.

The parameters and code below are based on an implementation of Fast GB in the LISA Data Challenges’ ldc package.

This class can be inherited to build fast waveforms for systems with additional astrophysical effects.

Parameters:

  • amp (double or 1D double np.ndarray) – Amplitude parameter.

  • f0 (double or 1D double np.ndarray) – Initial frequency of gravitational wave in Hz.

  • fdot (double or 1D double np.ndarray) – Initial time derivative of the frequency given as Hz/s.

  • fddot (double or 1D double np.ndarray) – Initial second derivative with respect to time of the frequency given in Hz/s^2.

  • phi0 (double or 1D double np.ndarray) – Initial phase angle of gravitational wave given in radians.

  • iota (double or 1D double np.ndarray) – Inclination of the Galactic binary orbit given in radians.

  • psi (double or 1D double np.ndarray) – Polarization angle of the Galactic binary orbit in radians.

  • lam (double or 1D double np.ndarray) – Ecliptic longitutude of the source given in radians.

  • beta (double or 1D double np.ndarray) – Ecliptic Latitude of the source given in radians. This is converted to the spherical polar angle.

  • *args (tuple, optional) – Flexible parameter to allow for a flexible number of argmuments when inherited by other classes. If running a circular Galactic binarys, args = (). If len(args) != 0, then the inheriting class must have a prepare_additional_args method.

  • N (int, optional) – Number of points in waveform. This should be determined by the initial frequency, f0. Default is None. If None, will use gbgpu.utils.utility.get_N() function to determine proper N.

  • T (double, optional) – Observation time in seconds. Default is 4 * YRSID_SI.

  • dt (double, optional) – Observation cadence in seconds. Default is 10.0 seconds.

  • oversample (int, optional) – Oversampling factor compared to the determined N value. Final N will be oversample * N. This is only used if N is not provided. Default is 1.

  • tdi2 (bool, optional) – If True, produce the TDI channels for TDI 2nd-generation. If False, produce TDI 1st-generation. Technically, the current TDI computation is not valid for generic LISA orbits, which are dealth with with 2nd-generation TDI, only those with an “equal-arm length” condition. Default is False.

  • Raises – ValueError: Length of *args is not 0 or 5.

classmethod supported_backends()

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

property xp: ModuleType

Return the module providing ndarray capabilities

special_get_N(amp, f0, T, *args, oversample=1)

Determine proper sampling rate in time domain for slow-part.

Parameters:

  • amp (double or 1D double np.ndarray) – Amplitude parameter.

  • f0 (double or 1D double np.ndarray) – Initial frequency of gravitational wave in Hz.

  • T (double) – Observation time in seconds.

  • *args (tuple) – Args input for beyond-GBGPU functionality.

  • oversample (int, optional) – Oversampling factor compared to the determined N value. Final N will be oversample * N. This is only used if N is not provided. Default is 1.

Returns:

Number of time-domain points recommended for each binary.

Return type:

1D int32 xp.ndarray

shift_frequency(fi, xi, *args)

Shift the evolution of the frequency in the slow part

Parameters:

  • fi (3D double xp.ndarray) – Instantaneous frequencies of the wave before applying third-body effect at each spacecraft as a function of time. The shape is (num binaries, 3 spacecraft, N).

  • xi (3D double xp.ndarray) – Time at each spacecraft. The shape is (num binaries, 3 spacecraft, N).

  • *args (tuple) – Args returned from prepare_additional_args().

Returns:

Updated frequencies with third-body effect.

Return type:

3D double xp.ndarray

add_to_argS(argS, f0, fdot, fddot, xi, *args)

Update argS in FastGB formalism for third-body effect

argS is an effective phase that goes into kdotP in the construction of the slow part of the waveform. kdotP is then included directly in the transfer function. See gbgpu.gbgpu.GBGPU._construct_slow_part() for the use of argS in the larger code.

Parameters:

  • argS (3D double xp.ndarray) – Special phase evaluation that goes into kdotP. Shape is (num binaries, 3 spacecraft, N).

  • f0 (1D double np.ndarray) – Initial frequency of gravitational wave in Hz.

  • fdot (1D double np.ndarray) – Initial time derivative of the frequency given as Hz/s.

  • fddot (1D double np.ndarray) – Initial second derivative with respect to time of the frequency given in Hz/s^2.

  • xi (3D double xp.ndarray) – Time at each spacecraft. The shape is (num binaries, 3 spacecraft, N).

  • T (double) – Observation time in seconds.

  • *args (tuple) – Args returned from prepare_additional_args().

Returns:

Updated argS with third-body effect

Return type:

3D double xp.ndarray