integrate_likelihood_extrinsic_batchmode

The integrate_likelihood_extrinsic_batchmode executable integrates the extrinsic parameters of the prefactored likelihood function. It is used to compute the likelihood over a grid of extrinsic parameters (such as sky position and orientation) for a given set of intrinsic parameters.

Overview

This tool is a core component of the RIFT likelihood integration process. It evaluates the likelihood function efficiently by leveraging pre-computed data and, when available, GPU acceleration (via CuPy). It supports various waveform approximants, NR lookup tables, and ROM (Reduced Order Model) bases.

Usage

Basic Command Line

integrate_likelihood_extrinsic_batchmode [options]

Primary Options

Data and Event Configuration

  • -c, --cache-file: LIGO cache file containing all data needed.

  • -C, --channel-name: Instrument and channel name (e.g., H1=FAKE-STRAIN). Can be specified multiple times.

  • -p, --psd-file: Instrument and PSD file (e.g., H1=H1_PSD.xml.gz). Can be specified multiple times.

  • -k, --skymap-file: Use a skymap stored in a given FITS file.

  • -x, --coinc-xml: gstlal_inspiral XML file containing coincidence information.

  • -E, --event: Event number used for this run (default: 0).

  • --n-events-to-analyze: Number of events to analyze from the XML (default: 1).

  • --random-event: Pick a random event from the file.

Simulation and Grid

  • -I, --sim-xml: XML file containing the parameter grid to be evaluated.

  • --sim-grid: ASCII file with labels containing the parameter grid to be evaluated.

  • -a, --approximant: Waveform family to use for templates (e.g., TaylorT4).

  • --l-max: Include all (l,m) modes with l less than or equal to this value (default: 2).

  • -A, --amp-order: Include amplitude corrections up to this order (default: 0).

Frequency and Timing

  • -f, --reference-freq: Waveform reference frequency (default: 100 Hz).

  • --fmin-template: Waveform starting frequency (default: 40 Hz).

  • -s, --data-start-time: GPS start time of the data segment.

  • -e, --data-end-time: GPS end time of the data segment.

  • -F, --fmax: Upper frequency of signal integration.

Advanced/Internal Options

  • --nr-lookup: Look up parameters from an NR catalog instead of using the specified approximant.

  • --rom-use-basis: Use the ROM basis for inner products.

  • --rom-integrate-intrinsic: Integrate over intrinsic variables (requires --rom-use-basis).

  • --use-gwsignal: Use the gwsignal interface for waveforms.

  • --maximize-only: Find the single best fitting point after integrating.

  • --check-good-enough: Terminate with success if a file ile_good_enough exists and is non-empty.

Functional Logic

Functional Logic

  1. Data Loading: Loads strain data from the cache and PSDs for each detector.

  2. Precomputation: Calls factored_likelihood.PrecomputeLikelihoodTerms to compute terms that are independent of the extrinsic parameters.

  3. Likelihood Integration:

    • Defines a likelihood function that computes the factored log-likelihood for specific extrinsic parameters.

    • Evaluates this function over the provided parameter grid (or uses a Monte Carlo sampler for marginalization).

    • Supports adaptive sampling or batch evaluation to focus on regions of high likelihood.

  4. Marginalization (Optional): If configured to integrate, computes the integral of the likelihood over the extrinsic parameters:

    \[\mathcal{L}_{marg} = \int \mathcal{L}(\theta_{ext}) d\theta_{ext}\]

  5. Maximization (Optional): If --maximize-only is set, it uses scipy.optimize.fmin to find the maximum likelihood point (MLP) in the extrinsic space.

Output Details

The tool typically outputs the integrated likelihood values. If specific flags like --dump-lnL-time-series are used, it can provide detailed time-series information for the injected parameters.