Likelihood Methods

Direct Likelihood Computation

class bbhx.likelihood.Likelihood(template_gen, data_freqs, data_channels, psd, force_backend=None)

Bases: BBHxParallelModule

Fast Base Likelihood Class for MBHBs

This class computes the graitational wave Likelihood as a direct sum over frequecy bins. It only sums over the frequencies where the MBHB signal exists. Therefore, larger mass waveforms are faster because there are less frequencies. This class computes: \(\mathcal{L}\propto-1/2\langle d-h|d-h\rangle=-1/2\left(\langle d|d\rangle \langle h|h\rangle - 2\langle d|h\rangle\right)\).

This class has GPU capability.

Parameters:

  • template_gen (obj) – Waveform generation class that returns a tuple of (list of template arrays, start indices, lengths). See bbhx.waveform.BBHWaveformFD for more information on this return type.

  • data_freqs (double xp.ndarray) – Frequencies for the data stream. data_freqs should be a numpy (cupy) array if running on the CPU (GPU).

  • data_channels (complex128 xp.ndarray) – Data stream. 2D array of shape: (3, len(data_freqs)). It is assumed there are 3 channels. data_channels should be a numpy (cupy) array if running on the CPU (GPU).

  • psd (double xp.ndarray) – Power Spectral Density in the noise:math:S_n(f). 2D array of shape: (3, len(data_freqs)). It is assumed there are 3 channels. psd should be a numpy (cupy) array if running on the CPU (GPU).

  • force_backend (str, optional) – ``”cpu”’’, ``”gpu”’’, ``”cuda”’’, ``”cuda12x”’’, or ``”cuda11x”’’.

d_d

\(\langle d|d\rangle\) inner product value.

Type:

double

data_channels

Data stream. 1D flattened array of shape: (3, len(data_freqs)). Note data_channels should be multiplied by psd before input into this class.

Type:

complex128 np.ndarray

data_freqs

Frequencies for the data stream (1D).

Type:

double np.ndarray

data_stream_length

Length of data.

Type:

int

noise_factors

\(\sqrt{\frac{\Delta f}{S_n(f)}}\). 1D flattened array of shape: (3, len(data_freqs)).

Type:

double xp.ndarray

psd

Power Spectral Density in the noise:math:S_n(f). 1D flattened array of shape: (3, len(data_freqs)).

Type:

double xp.ndarray

template_gen

Waveform generation class that returns a tuple of (list of template arrays, start indices, lengths). See bbhx.waveform.BBHWaveformFD for more information on this return type.

Type:

obj

phase_marginalize

If True, compute the phase-marginalized log-Likelihood (and snr if return_extracted_snr==True).

Type:

bool

return_extracted_snr

Return the snr in addition to the Likeilihood.

Type:

bool

classmethod supported_backends() → list

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

property like_gen

Likelihood for either GPU or CPU.

property xp

Cupy or Numpy

get_ll(params, return_extracted_snr=False, phase_marginalize=False, **waveform_kwargs)

Compute the log-Likelihood

params (double np.ndarray): Parameters for evaluating log-Likelihood.

params.shape=(num_params,) if 1D or params.shape=(num_params, num_bin_all) if 2D for more than one binary.

return_extracted_snr (bool, optional): If True, return

\(\langle d|h\rangle\ / \sqrt{\langle h|h\rangle}\) as a second entry of the return array. This produces a return array of xp.array([log likelihood, snr]).T. If False, just return the log-Likelihood array.

phase_marginalize (bool, optional): If True, compute the phase-marginalized

log-Likelihood (and snr if return_extracted_snr==True).

**waveform_kwargs (dict, optional): Keyword arguments for waveform

generator.

Returns:

log-Likelihoods or np.array([log-Likelihoods, snr]).T

Return type:

np.ndarray

static CPU_ONLY() → list[str]

List of supported backend for CPU only class

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

static GPU_ONLY() → list[str]

List of supported backends for GPU-only class

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

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)

Heterodyned Likelihood Computation

class bbhx.likelihood.HeterodynedLikelihood(template_gen, data_freqs, data_channels, reference_template_params, length_f_het, template_gen_kwargs: dict = None, reference_gen_kwargs: dict = None, sens_mat=None, force_backend=None)

Bases: BBHxParallelModule

Compute the Heterodyned log-Likelihood

Heterdyning involves separating the fast and slow evolutions when comparing signals. This involves comparing a reference template to the data stream and determining various quantities at the full frequency resolution of the data stream. Then, during online computation, the log-Likelihood is determined by computing a new waveform on a sparse frequency grid and comparing it to the reference waveform on the same sparse grid. The practical aspect is the computation of a smaller number of frequency points which lowers the required memory and increases the speed of the computation. More information on the general method can be found in arXiv:2109.02728. We implement the method as described in arXiv:1806.08792.

This class also works with higher order harmonic modes, but it has not been tested extensivally. It only does a direct summation over the modes rather than heterodyning per mode. So, it is less reliable, but in practice it produces a solid posterior distribution.

This class has GPU capabilities.

Parameters:

  • template_gen (obj) – Waveform generation class that returns a tuple of (list of template arrays, start indices, lengths). See bbhx.waveform.BBHWaveformFD for more information on this return type.

  • data_freqs (double xp.ndarray) – Frequencies for the data stream. data_freqs should be a numpy (cupy) array if running on the CPU (GPU).

  • data_channels (complex128 xp.ndarray) – Data stream. 2D array of shape: (3, len(data_freqs)). It is assumed there are 3 channels. data_channels should be a numpy (cupy) array if running on the CPU (GPU).

  • reference_template_params (np.ndarray) – Parameters for the reference template for template_gen.

  • template_gen_kwargs (dict, optional) – Keywords arguments for generating the template with template_gen. It will automatically add/change direct and compress keyword arguments to True. The keyword argument squeeze is automatically set to True for the initial setup and then automatically set to False for online computations. If you so choose (not recomended), you can change these kwargs for online running using the **waveform_kwargs setup in the self.get_ll method. However, if you include in this adjustment direct, compress, or squeeze will still automatically be overwritten. (Default: {})

  • reference_gen_kwargs (dict, optional) – Keywords arguments for generating the reference template with template_gen. It will automatically add/change fill, compress, and squeeze keyword arguments to True. These waveforms can be produced without interpolation with direct = True. If length keyword argument is given and direct=False, the waveform will be interpolated. If length and direct are not given, it will interpolate the signal with length=8096. (Default: {})

  • sens_mat (SensitivityMatrix, optional) – SensitivityMatrix object representing the AET channels. If None, defaults to class:AET1SensitivityMatrix. (default: None)

  • force_backend (str, optional) – ``”cpu”’’, ``”gpu”’’, ``”cuda”’’, ``”cuda12x”’’, or ``”cuda11x”’’.

reference_d_d

\(\langle d|d\rangle\) inner product value.

Type:

double

reference_h_h

\(\langle h|h\rangle\) inner product value for the reference template.

Type:

double

reference_d_h

\(\langle d|h\rangle\) inner product value for the reference template.

Type:

double

reference_ll

log-Likelihood value for the reference template.

Type:

double

hdyn_d_h

Heterodyned \(\langle d|h\rangle\) inner product values for the test templates.

Type:

complex128 xp.ndarray

hdyn_h_h

Heterodyned \(\langle d|h\rangle\) inner product values for the test templates.

Type:

complex128 xp.ndarray

h0_sparse

Array with sparse waveform for reference parameters.

Type:

xp.ndarray

h_sparse

Array with sparse waveform for test parameters.

Type:

xp.ndarray

d

Data stream. 1D flattened array of shape: (3, len(data_freqs)).

Type:

complex128 xp.ndarray

data_stream_length

Length of data.

Type:

int

data_constants

Flattened array container holding all heterodyning constants needed: A0, A1, B0, B1.

Type:

xp.ndarray

f_dense

Frequencies for the data stream (1D).

Type:

xp.ndarray

freqs

Frequencies for sparse arrays.

Type:

xp.ndarray

f_m

Frequency of mid-point in each sparse bin.

Type:

xp.ndarray

length_f_het

Length of sparse array.

Type:

int

psd

\(\sqrt{\frac{\Delta f}{S_n(f)}}\). 1D flattened array of shape: (3, len(data_freqs)).

Type:

double xp.ndarray

return_extracted_snr

Return the snr in addition to the Likeilihood.

Type:

bool

phase_marginalize

If True, compute the phase-marginalized log-Likelihood (and snr if return_extracted_snr==True).

Type:

bool

classmethod supported_backends() → list

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

property sens_mat

Sensitivity Matrix

property like_gen

C function on GPU/CPU

property xp

Numpy or Cupy

property citation

Citations for this class

static CPU_ONLY() → list[str]

List of supported backend for CPU only class

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

static GPU_ONLY() → list[str]

List of supported backends for GPU-only class

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

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)

get_ll(params, return_extracted_snr=False, phase_marginalize=False, **waveform_kwargs)

Compute the log-Likelihood

params (double np.ndarray): Parameters for evaluating log-Likelihood.

params.shape=(num_params,) if 1D or params.shape=(num_params, num_bin_all) if 2D for more than one binary.

return_extracted_snr (bool, optional): If True, return

\(\langle d|h\rangle\ / \sqrt{\langle h|h\rangle}\) as a second entry of the return array. This produces a return array of xp.array([log likelihood, snr]).T. If False, just return the log-Likelihood array.

phase_marginalize (bool, optional): If True, compute the phase-marginalized

log-Likelihood (and snr if return_extracted_snr==True).

**waveform_kwargs (dict, optional): Keyword arguments for waveform

generator. Some may be overwritten. See the main class docstring.

Returns:

log-Likelihoods or np.array([log-Likelihoods, snr]).T

Return type:

np.ndarray