Fast GB Waveforms and Likelihoods

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

Bases: object

Generate Galactic Binary Waveforms

This class generates galactic binary waveforms in the frequency domain, in the form of LISA TDI channels X, A, and E. It generates waveforms in batches. It can also provide injection signals and calculate likelihoods in batches. These batches are run on GPUs or CPUs. When CPUs are used, all available threads are leveraged with OpenMP. To adjust the available threads, use OMP_NUM_THREADS environmental variable or gbgpu.utils.set_omp_num_threads().

This class can generate waveforms for two different types of GB sources:

• Circular Galactic binaries

• Circular Galactic binaries with an eccentric third body (inherited)

Parameters:

use_gpu (bool, optional) – If True, run on GPUs. Default is False.

use_gpu

Use GPU if True.

Type:

bool

get_basis_tensors

Cython function.

Type:

obj

GenWave

Cython function.

Type:

obj

GenWaveThird

Cython function.

Type:

obj

unpack_data_1

Cython function.

Type:

obj

XYZ

Cython function.

Type:

obj

num_bin

Number of binaries in the current calculation.

Type:

int

N_max

Maximum points in a waveform based on maximum harmonic mode considered.

Type:

int

start_inds

Start indices into data stream array. q - N/2.

Type:

list of 1D int xp.ndarray

df

Fourier bin spacing.

Type:

double

X_out, A_out, E_out

X, A, or E channel TDI templates. Each array is a 2D complex array of shape (number of points, number of binaries) that is flattened. These can be accessed in python with the properties X, A, E.

Type:

1D complex xp.ndarrays

N

Last N value used.

Type:

int

d_d

<d|d> term in the likelihood.

Type:

double

property xp

CuPy or NumPy

property get_ll_func

get_ll c func.

property fill_global_func

fill_global c func.

property global_get_ll_func

global_get_ll_func c func.

property orbits: Orbits

Orbits class.

property citation

Get citations for this class

run_wave(amp, f0, fdot, fddot, phi0, iota, psi, lam, beta, *args, N=None, T=125829120.0, 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 * YEAR.

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

property X_out

X channel.

property Y_out

Y channel.

property Z_out

Z channel.

property A_out

A channel.

property E_out

E channel.

property T_out

T channel.

property A

return A channel reshaped based on number of binaries

property E

return E channel reshaped based on number of binaries

property T

return T channel reshaped based on number of binaries

property X

return X channel reshaped based on number of binaries

property Y

return Y channel reshaped based on number of binaries

property Z

return Z channel reshaped based on number of binaries

property freqs

Return frequencies associated with each signal

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

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.

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.

inject_signal(*args, fmax=None, T=125829120.0, 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 * YEAR.

• 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

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 self.use_gpu is True, 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.