gwsnr.core

Submodules

• gwsnr.core.gwsnr

Package Contents

Classes

GWSNR

Calculate SNR and detection probability for gravitational wave signals from compact binaries.

class gwsnr.core.GWSNR(npool=int(4), snr_method='interpolation_no_spins', snr_type='optimal_snr', gwsnr_verbose=True, multiprocessing_verbose=True, pdet_kwargs=None, mtot_min=2 * 4.98, mtot_max=2 * 112.5 + 10.0, ratio_min=0.1, ratio_max=1.0, spin_max=0.99, mtot_resolution=200, ratio_resolution=20, spin_resolution=10, batch_size_interpolation=1000000, interpolator_dir='./interpolator_pickle', create_new_interpolator=False, sampling_frequency=2048.0, waveform_approximant='IMRPhenomD', frequency_domain_source_model='lal_binary_black_hole', minimum_frequency=20.0, reference_frequency=None, duration_max=None, duration_min=None, fixed_duration=None, mtot_cut=False, psds=None, ifos=None, noise_realization=None, ann_path_dict=None, snr_recalculation=False, snr_recalculation_range=[6, 14], snr_recalculation_waveform_approximant='IMRPhenomXPHM')

Calculate SNR and detection probability for gravitational wave signals from compact binaries.

Provides multiple computational methods for optimal SNR calculation: - Interpolation: Fast calculation using precomputed coefficients - Inner product: Direct computation with LAL/Ripple waveforms - JAX/MLX: GPU-accelerated computation - ANN: Neural network-based estimation

Other features include: - observed SNR based Pdet calculation with various statistical models - Horizon distance estimation for detectors and detector networks

Parameters:

npoolint, default=4

Number of processors for parallel computation.

mtot_minfloat, default=9.96

Minimum total mass (solar masses) for interpolation grid.

mtot_maxfloat, default=235.0

Maximum total mass (solar masses). Auto-adjusted if mtot_cut=True.

ratio_minfloat, default=0.1

Minimum mass ratio (m2/m1) for interpolation.

ratio_maxfloat, default=1.0

Maximum mass ratio for interpolation.

spin_maxfloat, default=0.99

Maximum aligned spin magnitude.

mtot_resolutionint, default=200

Grid points for total mass interpolation.

ratio_resolutionint, default=20

Grid points for mass ratio interpolation.

spin_resolutionint, default=10

Grid points for spin interpolation (aligned-spin methods).

batch_size_interpolationint, default=1000000

Batch size for interpolation calculations.

sampling_frequencyfloat, default=2048.0

Detector sampling frequency (Hz).

waveform_approximantstr, default=’IMRPhenomD’

Waveform model: ‘IMRPhenomD’, ‘IMRPhenomXPHM’, ‘TaylorF2’, etc.

frequency_domain_source_modelstr, default=’lal_binary_black_hole’

LAL source model for waveform generation.

minimum_frequencyfloat, default=20.0

Minimum frequency (Hz) for waveform generation.

reference_frequencyfloat, optional

Reference frequency (Hz). Defaults to minimum_frequency.

duration_maxfloat, optional

Maximum waveform duration (seconds). Auto-set for some approximants.

duration_minfloat, optional

Minimum waveform duration (seconds).

fixed_durationfloat, optional

Fixed duration (seconds) for all waveforms.

mtot_cutbool, default=False

If True, limit mtot_max based on minimum_frequency.

snr_methodstr, default=’interpolation_no_spins’

SNR calculation method. Options: - ‘interpolation_no_spins[_numba/_jax/_mlx]’ - ‘interpolation_aligned_spins[_numba/_jax/_mlx]’ - ‘inner_product[_jax]’ - ‘ann’

snr_typestr, default=’optimal_snr’

SNR type: ‘optimal_snr’ or ‘observed_snr’ (not implemented).

noise_realizationarray_like, optional

Noise realization for observed SNR (not implemented).

psdsdict, optional

Detector power spectral densities: - None: Use bilby defaults - {‘H1’: ‘aLIGODesign’, ‘L1’: ‘aLIGODesign’}: PSD names - {‘H1’: ‘custom_psd.txt’}: Custom PSD files - {‘H1’: 1234567890}: GPS time for data-based PSD

ifoslist, optional

Custom interferometer objects. Defaults from psds if None.

interpolator_dirstr, default=’./interpolator_pickle’

Directory for storing interpolation coefficients.

create_new_interpolatorbool, default=False

If True, regenerate interpolation coefficients.

gwsnr_verbosebool, default=True

Print initialization parameters.

multiprocessing_verbosebool, default=True

Show progress bars during computation.

pdet_kwargsdict, optional

Detection probability parameters: - ‘snr_th’: Single detector threshold (default=10.0) - ‘snr_th_net’: Network threshold (default=10.0) - ‘pdet_type’: ‘boolean’ or ‘probability_distribution’ - ‘distribution_type’: ‘gaussian’ or ‘noncentral_chi2’

ann_path_dictdict or str, optional

Paths to ANN models. Uses built-in models if None.

snr_recalculationbool, default=False

Enable hybrid recalculation near detection threshold.

snr_recalculation_rangelist, default=[6,14]

SNR range [min, max] for triggering recalculation.

snr_recalculation_waveform_approximantstr, default=’IMRPhenomXPHM’

Waveform approximant for recalculation.

Notes

• Interpolation methods: fastest for population studies

• Inner product methods: most accurate for individual events

• JAX/MLX methods: leverage GPU acceleration

• ANN methods: fast detection probability, lower SNR accuracy

P_det value: {pdet}”)

npool = 'None'

int

Number of processors for parallel processing.

mtot_min = 'None'

float

Minimum total mass (Mo) for interpolation grid.

mtot_max = 'None'

float

Maximum total mass (Mo) for interpolation grid.

ratio_min = 'None'

float

Minimum mass ratio (q = m2/m1) for interpolation grid.

ratio_max = 'None'

float

Maximum mass ratio for interpolation grid.

spin_max = 'None'

float

Maximum aligned spin magnitude for interpolation.

mtot_resolution = 'None'

int

Grid resolution for total mass interpolation.

ratio_resolution = 'None'

int

Grid resolution for mass ratio interpolation.

spin_resolution = 'None'

int

Grid resolution for aligned spin interpolation.

ratio_arr = 'None'

numpy.ndarray

Mass ratio interpolation grid points.

mtot_arr = 'None'

numpy.ndarray

Total mass interpolation grid points.

a_1_arr = 'None'

numpy.ndarray

Primary aligned spin interpolation grid.

a_2_arr = 'None'

numpy.ndarray

Secondary aligned spin interpolation grid.

sampling_frequency = 'None'

float

Detector sampling frequency (Hz).

waveform_approximant = 'None'

str

LAL waveform approximant (e.g., ‘IMRPhenomD’, ‘IMRPhenomXPHM’).

frequency_domain_source_model = 'None'

str

LAL frequency domain source model.

f_min = 'None'

float

Minimum waveform frequency (Hz).

f_ref = 'None'

float

Reference frequency (Hz) for waveform generation.

duration_max = 'None'

float or None

Maximum waveform duration (s). Auto-set if None.

duration_min = 'None'

float or None

Minimum waveform duration (s). Auto-set if None.

snr_method = 'None'

str

SNR calculation method. Options: interpolation variants, inner_product variants, ann.

snr_type = 'None'

str

SNR type: ‘optimal_snr’ or ‘observed_snr’ (not implemented).

noise_realization = 'None'

numpy.ndarray or None

Noise realization for observed SNR (not implemented).

psds_list = 'None'

list of PowerSpectralDensity

Detector power spectral densities.

detector_tensor_list = 'None'

list of numpy.ndarray

Detector tensors for antenna response calculations.

detector_list = 'None'

list of str

Detector names (e.g., [‘H1’, ‘L1’, ‘V1’]).

ifos = 'None'

list of Interferometer

Bilby interferometer objects.

interpolator_dir = 'None'

str

Directory for interpolation coefficient storage.

path_interpolator = 'None'

list of str

Paths to interpolation coefficient files.

snr_partialsacaled_list = 'None'

list of numpy.ndarray

Partial-scaled SNR interpolation coefficients.

multiprocessing_verbose = 'None'

bool

Show progress bars for multiprocessing computations.

param_dict_given = 'None'

dict

Interpolator parameter dictionary for caching.

snr_th = 'None'

float

Individual detector SNR threshold (default: 8.0).

snr_th_net = 'None'

float

Network SNR threshold (default: 8.0).

model_dict = 'None'

dict

ANN models for each detector (when snr_method=’ann’).

scaler_dict = 'None'

dict

ANN feature scalers for each detector (when snr_method=’ann’).

error_adjustment = 'None'

dict

ANN error correction parameters (when snr_method=’ann’).

ann_catalogue = 'None'

dict

ANN model configuration and paths (when snr_method=’ann’).

snr_recalculation = 'None'

bool

Enable hybrid SNR recalculation near detection threshold.

snr_recalculation_range = 'None'

list

SNR range [min, max] triggering recalculation.

snr_recalculation_waveform_approximant = 'None'

str

Waveform approximant for SNR recalculation.

get_interpolated_snr = 'None'

function

Interpolated SNR calculation function (backend-specific).

noise_weighted_inner_product_jax = 'None'

function

JAX-accelerated inner product function (when snr_method=’inner_product_jax’).

pdet_kwargs = 'None'

fixed_duration = 'None'

batch_size_interpolation = '1000000'

mtot_cut = 'False'

interpolator_setup(interpolator_dir, create_new_interpolator, psds_list, detector_tensor_list, detector_list)

Set up interpolator files for fast SNR calculation using precomputed coefficients.

This method manages the creation and loading of partialscaled SNR interpolation data. It checks for existing interpolators, generates missing ones, and loads coefficients for runtime use.

Parameters:

interpolator_dirstr

Directory path for storing interpolator pickle files.

create_new_interpolatorbool

If True, generates new interpolators regardless of existing files.

psds_listlist

Power spectral density objects for each detector.

detector_tensor_listlist

Detector tensor arrays for antenna response calculations.

detector_listlist

Detector names (e.g., [‘L1’, ‘H1’, ‘V1’]).

Returns:

path_interpolator_alllist

File paths to interpolator pickle files for all detectors.

Notes

• Uses interpolator_check() to identify missing interpolators

• Calls init_partialscaled() to generate new coefficients

• Loads coefficients into snr_partialsacaled_list for runtime use

ann_initilization(ann_path_dict, detector_list, sampling_frequency, minimum_frequency, waveform_approximant)

Initialize ANN models and feature scalers for detection probability estimation.

Loads pre-trained neural network models, feature scalers, and error correction parameters for each detector. Validates that model parameters match current GWSNR configuration.

Parameters:

ann_path_dictdict, str, or None

Dictionary or JSON file path containing ANN model paths for each detector. If None, uses default models from gwsnr/ann/data/ann_path_dict.json. Expected structure: {detector_name: {‘model_path’: str, ‘scaler_path’: str, ‘error_adjustment_path’: str, ‘sampling_frequency’: float, ‘minimum_frequency’: float, ‘waveform_approximant’: str, ‘snr_th’: float}}.

detector_listlist of str

Detector names requiring ANN models (e.g., [‘L1’, ‘H1’, ‘V1’]).

sampling_frequencyfloat

Sampling frequency in Hz. Must match ANN training configuration.

minimum_frequencyfloat

Minimum frequency in Hz. Must match ANN training configuration.

waveform_approximantstr

Waveform model. Must match ANN training configuration.

snr_thfloat

Detection threshold. Must match ANN training configuration.

Returns:

model_dictdict

Loaded TensorFlow/Keras models {detector_name: model}.

scaler_dictdict

Feature preprocessing scalers {detector_name: scaler}.

error_adjustmentdict

Post-prediction correction parameters {detector_name: {‘slope’: float, ‘intercept’: float}}.

ann_cataloguedict

Complete ANN configuration and paths for all detectors.

Raises:

ValueError

If model not available for detector, or if model parameters don’t match current GWSNR configuration.

Notes

• Loads models from gwsnr/ann/data if file paths don’t exist locally

• Validates parameter compatibility before loading

• Error adjustment improves prediction accuracy via linear correction

calculate_mtot_max(mtot_max, minimum_frequency)

Calculate maximum total mass cutoff based on minimum frequency to ensure positive chirp time.

This method finds the maximum total mass where the chirp time becomes zero at the given minimum frequency. Systems with higher masses would have negative chirp times, causing waveform generation failures. A safety factor of 1.1 is applied.

Parameters:

mtot_maxfloat

User-specified maximum total mass in solar masses.

minimum_frequencyfloat

Minimum frequency in Hz for waveform generation.

Returns:

float

Adjusted maximum total mass (≤ input mtot_max) ensuring positive chirp time.

Notes

Uses equal mass ratio (q=1.0) as conservative estimate since it maximizes chirp time for given total mass. Particularly important for TaylorF2 approximant.

print_all_params(verbose=True)

Print all parameters and configuration of the GWSNR class instance.

Displays computational settings, waveform configuration, detector setup, mass parameter ranges, and interpolation parameters for verification and debugging.

Parameters:

verbosebool, default=True

If True, print all parameters to stdout. If False, suppress output.

Notes

Printed information includes: - Computational: processors, SNR method - Waveform: approximant, frequencies, sampling rate - Detectors: names and PSDs - Mass ranges: total mass bounds with frequency cutoffs - Interpolation: grid resolutions and bounds (when applicable)

Called automatically during initialization when gwsnr_verbose=True.

optimal_snr(mass_1=np.array([10.0]), mass_2=np.array([10.0]), luminosity_distance=100.0, theta_jn=0.0, psi=0.0, phase=0.0, geocent_time=1246527224.169434, ra=0.0, dec=0.0, a_1=0.0, a_2=0.0, tilt_1=0.0, tilt_2=0.0, phi_12=0.0, phi_jl=0.0, lambda_1=0.0, lambda_2=0.0, eccentricity=0.0, gw_param_dict=False, output_jsonfile=False)

Calculate optimal SNR for gravitational wave signals from compact binary coalescences.

This is the primary interface for SNR calculation, routing to the appropriate computational method based on the configured snr_method. Supports interpolation, inner product, JAX-accelerated, and neural network methods.

Parameters:

mass_1array_like or float, default=np.array([10.0])

Primary mass in solar masses.

mass_2array_like or float, default=np.array([10.0])

Secondary mass in solar masses.

luminosity_distancearray_like or float, default=100.0

Luminosity distance in Mpc.

theta_jnarray_like or float, default=0.0

Inclination angle (total angular momentum to line of sight) in radians.

psiarray_like or float, default=0.0

Polarization angle in radians.

phasearray_like or float, default=0.0

Coalescence phase in radians.

geocent_timearray_like or float, default=1246527224.169434

GPS coalescence time at geocenter in seconds.

raarray_like or float, default=0.0

Right ascension in radians.

decarray_like or float, default=0.0

Declination in radians.

a_1array_like or float, default=0.0

Primary spin magnitude (dimensionless).

a_2array_like or float, default=0.0

Secondary spin magnitude (dimensionless).

tilt_1array_like or float, default=0.0

Primary spin tilt angle in radians.

tilt_2array_like or float, default=0.0

Secondary spin tilt angle in radians.

phi_12array_like or float, default=0.0

Azimuthal angle between spins in radians.

phi_jlarray_like or float, default=0.0

Azimuthal angle between total and orbital angular momentum in radians.

lambda_1array_like or float, default=0.0

Primary tidal deformability (dimensionless).

lambda_2array_like or float, default=0.0

Secondary tidal deformability (dimensionless).

eccentricityarray_like or float, default=0.0

Orbital eccentricity at reference frequency.

gw_param_dictdict or bool, default=False

Parameter dictionary. If provided, overrides individual arguments.

output_jsonfilestr or bool, default=False

Save results to JSON file. If True, saves as ‘snr.json’.

Returns:

dict

SNR values for each detector and network SNR. Keys are detector names (‘H1’, ‘L1’, ‘V1’, etc.) and ‘snr_net’. Values are arrays matching input size.

Notes

• For interpolation methods, tilt angles are converted to aligned spins: a_i * cos(tilt_i)

• Total mass must be within [mtot_min, mtot_max] for non-zero SNR

• Hybrid recalculation uses higher-order waveforms near detection threshold if enabled

• Compatible with all configured detector networks and waveform approximants

Examples

>>> snr = GWSNR(snr_method='interpolation_no_spins')
>>> result = snr.optimal_snr(mass_1=30.0, mass_2=25.0, luminosity_distance=100.0)
>>> print(f"Network SNR: {result['snr_net'][0]:.2f}")

>>> # Multiple systems with parameter dictionary
>>> params = {'mass_1': [20, 30], 'mass_2': [20, 25], 'luminosity_distance': [100, 200]}
>>> result = snr.optimal_snr(gw_param_dict=params)

optimal_snr_with_ann(mass_1=30.0, mass_2=29.0, luminosity_distance=100.0, theta_jn=0.0, psi=0.0, phase=0.0, geocent_time=1246527224.169434, ra=0.0, dec=0.0, a_1=0.0, a_2=0.0, tilt_1=0.0, tilt_2=0.0, phi_12=0.0, phi_jl=0.0, gw_param_dict=False, output_jsonfile=False)

Calculate SNR using artificial neural network (ANN) prediction.

Uses pre-trained neural networks to rapidly estimate optimal SNR for gravitational wave signals with arbitrary spin configurations. The method first computes partial-scaled SNR via interpolation, then feeds this along with other intrinsic parameters to detector-specific ANN models for fast SNR prediction.

Parameters:

mass_1array_like or float, default=30.0

Primary mass in solar masses.

mass_2array_like or float, default=29.0

Secondary mass in solar masses.

luminosity_distancearray_like or float, default=100.0

Luminosity distance in Mpc.

theta_jnarray_like or float, default=0.0

Inclination angle in radians.

psiarray_like or float, default=0.0

Polarization angle in radians.

phasearray_like or float, default=0.0

Coalescence phase in radians.

geocent_timearray_like or float, default=1246527224.169434

GPS coalescence time at geocenter in seconds.

raarray_like or float, default=0.0

Right ascension in radians.

decarray_like or float, default=0.0

Declination in radians.

a_1array_like or float, default=0.0

Primary spin magnitude (dimensionless).

a_2array_like or float, default=0.0

Secondary spin magnitude (dimensionless).

tilt_1array_like or float, default=0.0

Primary tilt angle in radians.

tilt_2array_like or float, default=0.0

Secondary tilt angle in radians.

phi_12array_like or float, default=0.0

Azimuthal angle between spins in radians.

phi_jlarray_like or float, default=0.0

Azimuthal angle between total and orbital angular momentum in radians.

gw_param_dictdict or bool, default=False

Parameter dictionary. If provided, overrides individual arguments.

output_jsonfilestr or bool, default=False

Save results to JSON file. If True, saves as ‘snr.json’.

Returns:

dict

SNR estimates for each detector and network. Keys are detector names (‘H1’, ‘L1’, ‘V1’, etc.) and ‘snr_net’.

Notes

• Requires pre-trained ANN models loaded during initialization

• Uses aligned spin components: a_i * cos(tilt_i) for effective spin calculation

• ANN inputs: partial-scaled SNR, amplitude factor, mass ratio, effective spin, inclination

• Applies error correction to improve prediction accuracy

• Total mass must be within [mtot_min, mtot_max] for valid results

Examples

>>> snr = GWSNR(snr_method='ann')
>>> result = snr.optimal_snr_with_ann(mass_1=30, mass_2=25, a_1=0.5, tilt_1=0.2)
>>> print(f"Network SNR: {result['snr_net'][0]:.2f}")

output_ann(idx, params)

Prepare ANN input features from gravitational wave parameters.

Transforms gravitational wave parameters into feature vectors for neural network prediction. Calculates partial-scaled SNR via interpolation and combines with intrinsic parameters to create standardized input features.

Parameters:

idxnumpy.ndarray of bool

Boolean mask for valid mass ranges (mtot_min <= mtot <= mtot_max).

paramsdict

GW parameter dictionary with keys: mass_1, mass_2, luminosity_distance, theta_jn, a_1, a_2, tilt_1, tilt_2, psi, geocent_time, ra, dec.

Returns:

list of numpy.ndarray

Feature arrays for each detector, shape (N, 5) with columns: [partial_scaled_snr, amplitude_factor, eta, chi_eff, theta_jn].

Notes

• Uses aligned spin components: a_i * cos(tilt_i)

• Amplitude factor: A1 = Mc^(5/6) / d_eff

• Effective spin: chi_eff = (m1*a1z + m2*a2z) / (m1+m2)

optimal_snr_with_interpolation(mass_1=30.0, mass_2=29.0, luminosity_distance=100.0, theta_jn=0.0, psi=0.0, phase=0.0, geocent_time=1246527224.169434, ra=0.0, dec=0.0, a_1=0.0, a_2=0.0, output_jsonfile=False, gw_param_dict=False)

Calculate SNR (for non-spinning or aligned-spin) using bicubic interpolation of precomputed coefficients.

Fast SNR calculation method using interpolated partial-scaled SNR values across intrinsic parameter grids. Supports no-spin and aligned-spin configurations with Numba or JAX acceleration for population studies.

Parameters:

mass_1array_like or float, default=30.0

Primary mass in solar masses.

mass_2array_like or float, default=29.0

Secondary mass in solar masses.

luminosity_distancearray_like or float, default=100.0

Luminosity distance in Mpc.

theta_jnarray_like or float, default=0.0

Inclination angle in radians.

psiarray_like or float, default=0.0

Polarization angle in radians.

phasearray_like or float, default=0.0

Coalescence phase in radians.

geocent_timearray_like or float, default=1246527224.169434

GPS coalescence time at geocenter in seconds.

raarray_like or float, default=0.0

Right ascension in radians.

decarray_like or float, default=0.0

Declination in radians.

a_1array_like or float, default=0.0

Primary aligned spin component (for aligned-spin methods only).

a_2array_like or float, default=0.0

Secondary aligned spin component (for aligned-spin methods only).

gw_param_dictdict or bool, default=False

Parameter dictionary. If provided, overrides individual arguments.

output_jsonfilestr or bool, default=False

Save results to JSON file. If True, saves as ‘snr.json’.

Returns:

dict

SNR values for each detector and network SNR. Keys are detector names (‘H1’, ‘L1’, ‘V1’, etc.) and ‘snr_net’. Systems outside mass bounds have zero SNR.

Notes

• Requires precomputed interpolation coefficients from class initialization

• self.get_interpolated_snr is set based on snr_method (Numba or JAX or MLX) and whether the system is non-spinning or aligned-spin

• Total mass must be within [mtot_min, mtot_max] for valid results

• Uses aligned spin: a_i * cos(tilt_i) for spin-enabled methods

• Backend acceleration available via JAX or Numba depending on snr_method

Examples

>>> snr_calc = GWSNR(snr_method='interpolation_no_spins')
>>> result = snr_calc.optimal_snr_with_interpolation(mass_1=30, mass_2=25)
>>> print(f"Network SNR: {result['snr_net'][0]:.2f}")

init_partialscaled()

Generate partial-scaled SNR interpolation coefficients for fast bicubic interpolation.

Computes and saves distance-independent SNR coefficients across intrinsic parameter grids for each detector. These coefficients enable fast runtime SNR calculation via interpolation without requiring waveform generation.

Creates parameter grids based on interpolation method: - No-spin: 2D grid (mass_ratio, total_mass) - Aligned-spin: 4D grid (mass_ratio, total_mass, a_1, a_2)

For each grid point, computes optimal SNR with fixed extrinsic parameters (d_L=100 Mpc, θ_jn=0, overhead sky location), then scales by effective distance and chirp mass: partial_SNR = (optimal_SNR × d_eff) / Mc^(5/6).

Coefficients are saved as pickle files for runtime interpolation.

Raises:

ValueError

If mtot_min < 1.0 or snr_method not supported for interpolation.

Notes

Grid dimensions set by ratio_resolution, mtot_resolution, spin_resolution. Automatically called during initialization when coefficients missing.

optimal_snr_with_inner_product(mass_1=10, mass_2=10, luminosity_distance=100.0, theta_jn=0.0, psi=0.0, phase=0.0, geocent_time=1246527224.169434, ra=0.0, dec=0.0, a_1=0.0, a_2=0.0, tilt_1=0.0, tilt_2=0.0, phi_12=0.0, phi_jl=0.0, lambda_1=0.0, lambda_2=0.0, eccentricity=0.0, gw_param_dict=False, output_jsonfile=False)

Calculate optimal SNR using LAL waveform generation and noise-weighted inner products.

This method computes SNR by generating gravitational wave signals with LAL and calculating matched filtering inner products against detector noise PSDs. Supports all LAL waveform approximants including aligned and precessing spin systems.

Parameters:

mass_1array_like or float, default=10

Primary mass in solar masses.

mass_2array_like or float, default=10

Secondary mass in solar masses.

luminosity_distancearray_like or float, default=100.0

Luminosity distance in Mpc.

theta_jnarray_like or float, default=0.0

Inclination angle in radians.

psiarray_like or float, default=0.0

Polarization angle in radians.

phasearray_like or float, default=0.0

Coalescence phase in radians.

geocent_timearray_like or float, default=1246527224.169434

GPS coalescence time at geocenter in seconds.

raarray_like or float, default=0.0

Right ascension in radians.

decarray_like or float, default=0.0

Declination in radians.

a_1array_like or float, default=0.0

Primary spin magnitude (dimensionless).

a_2array_like or float, default=0.0

Secondary spin magnitude (dimensionless).

tilt_1array_like or float, default=0.0

Primary spin tilt angle in radians.

tilt_2array_like or float, default=0.0

Secondary spin tilt angle in radians.

phi_12array_like or float, default=0.0

Azimuthal angle between spins in radians.

phi_jlarray_like or float, default=0.0

Azimuthal angle between total and orbital angular momentum in radians.

lambda_1array_like or float, default=0.0

Primary tidal deformability (dimensionless).

lambda_2array_like or float, default=0.0

Secondary tidal deformability (dimensionless).

eccentricityarray_like or float, default=0.0

Orbital eccentricity at reference frequency.

gw_param_dictdict or bool, default=False

Parameter dictionary. If provided, overrides individual arguments.

output_jsonfilestr or bool, default=False

Save results to JSON file. If True, saves as ‘snr.json’.

Returns:

dict

SNR values for each detector and network SNR. Keys are detector names (‘H1’, ‘L1’, ‘V1’, etc.) and ‘snr_net’. Systems outside mass bounds have zero SNR.

Notes

• Waveform duration auto-estimated from chirp time with 1.1x safety factor

• Uses multiprocessing for parallel computation across npool processors

• Requires ‘if __name__ == “__main__”:’ guard when using multiprocessing

• Most accurate method but slower than interpolation for population studies

Examples

>>> snr = GWSNR(snr_method='inner_product')
>>> result = snr.optimal_snr_with_inner_product(mass_1=30, mass_2=25)
>>> print(f"Network SNR: {result['snr_net'][0]:.2f}")

optimal_snr_with_inner_product_ripple(mass_1=10, mass_2=10, luminosity_distance=100.0, theta_jn=0.0, psi=0.0, phase=0.0, geocent_time=1246527224.169434, ra=0.0, dec=0.0, a_1=0.0, a_2=0.0, tilt_1=0.0, tilt_2=0.0, phi_12=0.0, phi_jl=0.0, lambda_1=0.0, lambda_2=0.0, eccentricity=0.0, gw_param_dict=False, output_jsonfile=False)

Calculate optimal SNR using JAX-accelerated Ripple waveforms and noise-weighted inner products.

Uses the Ripple waveform generator with JAX backend for fast SNR computation via vectorized inner products. Supports arbitrary spin configurations and provides significant speedup over LAL-based methods for population studies.

Parameters:

mass_1array_like or float, default=10

Primary mass in solar masses.

mass_2array_like or float, default=10

Secondary mass in solar masses.

luminosity_distancearray_like or float, default=100.0

Luminosity distance in Mpc.

theta_jnarray_like or float, default=0.0

Inclination angle in radians.

psiarray_like or float, default=0.0

Polarization angle in radians.

phasearray_like or float, default=0.0

Coalescence phase in radians.

geocent_timearray_like or float, default=1246527224.169434

GPS coalescence time at geocenter in seconds.

raarray_like or float, default=0.0

Right ascension in radians.

decarray_like or float, default=0.0

Declination in radians.

a_1array_like or float, default=0.0

Primary spin magnitude (dimensionless).

a_2array_like or float, default=0.0

Secondary spin magnitude (dimensionless).

tilt_1array_like or float, default=0.0

Primary spin tilt angle in radians.

tilt_2array_like or float, default=0.0

Secondary spin tilt angle in radians.

phi_12array_like or float, default=0.0

Azimuthal angle between spins in radians.

phi_jlarray_like or float, default=0.0

Azimuthal angle between total and orbital angular momentum in radians.

lambda_1array_like or float, default=0.0

Primary tidal deformability (dimensionless).

lambda_2array_like or float, default=0.0

Secondary tidal deformability (dimensionless).

eccentricityarray_like or float, default=0.0

Orbital eccentricity at reference frequency.

gw_param_dictdict or bool, default=False

Parameter dictionary. If provided, overrides individual arguments.

output_jsonfilestr or bool, default=False

Save results to JSON file. If True, saves as ‘snr.json’.

Returns:

dict

SNR values for each detector and network SNR. Keys are detector names (‘H1’, ‘L1’, ‘V1’, etc.) and ‘snr_net’. Systems outside mass bounds have zero SNR.

Notes

• Requires snr_method=’inner_product_jax’ during initialization

• Uses JAX JIT compilation and vectorization for GPU acceleration

• Duration auto-estimated with safety bounds from duration_min/max

• Compatible with Ripple-supported approximants (IMRPhenomD, IMRPhenomXPHM)

• Supports precessing spins through full parameter space

Examples

>>> snr = GWSNR(snr_method='inner_product_jax')
>>> result = snr.optimal_snr_with_inner_product_ripple(mass_1=30, mass_2=25)
>>> print(f"Network SNR: {result['snr_net'][0]:.2f}")

pdet(mass_1=np.array([10.0]), mass_2=np.array([10.0]), luminosity_distance=100.0, theta_jn=0.0, psi=0.0, phase=0.0, geocent_time=1246527224.169434, ra=0.0, dec=0.0, a_1=0.0, a_2=0.0, tilt_1=0.0, tilt_2=0.0, phi_12=0.0, phi_jl=0.0, lambda_1=0.0, lambda_2=0.0, eccentricity=0.0, gw_param_dict=False, output_jsonfile=False, snr_th=None, snr_th_net=None, pdet_type=None, distribution_type=None, include_optimal_snr=False, include_observed_snr=False)

Calculate probability of detection for gravitational wave signals.

Computes detection probability based on SNR thresholds for individual detectors and detector networks. Accounts for noise fluctuations by modeling observed SNR as statistical distributions around optimal SNR values.

Parameters:

mass_1array_like or float, default=np.array([10.0])

Primary mass in solar masses.

mass_2array_like or float, default=np.array([10.0])

Secondary mass in solar masses.

luminosity_distancearray_like or float, default=100.0

Luminosity distance in Mpc.

theta_jnarray_like or float, default=0.0

Inclination angle in radians.

psiarray_like or float, default=0.0

Polarization angle in radians.

phasearray_like or float, default=0.0

Coalescence phase in radians.

geocent_timearray_like or float, default=1246527224.169434

GPS coalescence time at geocenter in seconds.

raarray_like or float, default=0.0

Right ascension in radians.

decarray_like or float, default=0.0

Declination in radians.

a_1array_like or float, default=0.0

Primary spin magnitude (dimensionless).

a_2array_like or float, default=0.0

Secondary spin magnitude (dimensionless).

tilt_1array_like or float, default=0.0

Primary spin tilt angle in radians.

tilt_2array_like or float, default=0.0

Secondary spin tilt angle in radians.

phi_12array_like or float, default=0.0

Azimuthal angle between spins in radians.

phi_jlarray_like or float, default=0.0

Azimuthal angle between total and orbital angular momentum in radians.

lambda_1array_like or float, default=0.0

Primary tidal deformability (dimensionless).

lambda_2array_like or float, default=0.0

Secondary tidal deformability (dimensionless).

eccentricityarray_like or float, default=0.0

Orbital eccentricity at reference frequency.

gw_param_dictdict or bool, default=False

Parameter dictionary. If provided, overrides individual arguments.

output_jsonfilestr or bool, default=False

Save results to JSON file. If True, saves as ‘pdet.json’.

snr_thfloat, array_like, or None, default=None

SNR threshold for individual detectors. If None, uses pdet_kwargs[‘snr_th’]. If array, must match number of detectors.

snr_th_netfloat or None, default=None

Network SNR threshold. If None, uses pdet_kwargs[‘snr_th_net’].

pdet_typestr or None, default=None

Detection probability method: - ‘boolean’: Binary detection (0 or 1) based on noise realizations - ‘probability_distribution’: Analytical probability using noise statistics If None, uses pdet_kwargs[‘pdet_type’].

distribution_typestr or None, default=None

Noise model for observed SNR: - ‘gaussian’: Gaussian noise (sigma=1) - ‘noncentral_chi2’: Non-central chi-squared (2 DOF per detector) If None, uses pdet_kwargs[‘distribution_type’]. - ‘fixed_snr’: Deterministic detection based on optimal SNR (only for ‘boolean’ pdet_type)

Returns:

dict

Detection probabilities for each detector and network. Keys are detector names (‘H1’, ‘L1’, ‘V1’, etc.) and ‘pdet_net’. Values depend on pdet_type: - ‘boolean’: Binary arrays (0/1) indicating detection - ‘probability_distribution’: Probability arrays (0-1)

Notes

• First computes optimal SNR using configured snr_method

• Models observed SNR as noisy version of optimal SNR

• Non-central chi-squared uses 2 DOF per detector, network uses 2×N_det DOF

• Boolean method generates random noise realizations for each system

• Probability method uses analytical CDFs for faster computation

Examples

>>> pdet_calc = GWSNR(pdet_kwargs={'snr_th': 8, 'pdet_type': 'boolean'})
>>> result = pdet_calc.pdet(mass_1=30, mass_2=25, luminosity_distance=200)
>>> print(f"Network detection: {result['pdet_net'][0]}")

>>> # Analytical probability calculation
>>> pdet_calc = GWSNR(pdet_kwargs={'pdet_type': 'probability_distribution'})
>>> probs = pdet_calc.pdet(mass_1=[20,30], mass_2=[20,25], luminosity_distance=150)

horizon_distance_analytical(mass_1=1.4, mass_2=1.4, snr_th=None)

Calculate detector horizon distance for compact binary coalescences. Follows analytical formula from arXiv:gr-qc/0509116 .

This method doesn’t calculate horizon distance for the detector network, but for individual detectors only. Use horizon_distance_numerical for network horizon.

Computes the maximum range at which a source can be detected with optimal orientation (face-on, overhead). Uses reference SNR at 100 Mpc scaled by effective distance and detection threshold.

Parameters:

mass_1array_like or float, default=1.4

Primary mass in solar masses.

mass_2array_like or float, default=1.4

Secondary mass in solar masses.

snr_thfloat, optional

Individual detector SNR threshold. Uses class default if None.

snr_th_netfloat, optional

Network SNR threshold. Uses class default if None.

Returns:

horizon_distance_dictdict

Horizon distances in Mpc for each detector and network. Keys: detector names (‘H1’, ‘L1’, etc.) and ‘snr_net’. Values: array of horizon distances in Mpc.

Notes

• Assumes optimal orientation: θ_jn=0, overhead sky location

• Formula: d_horizon = (d_eff/SNR_th) x SNR_100Mpc

• Network horizon uses quadrature sum of detector responses

• Compatible with all waveform approximants

Examples

>>> snr = GWSNR(snr_method='inner_product')
>>> horizon = snr.horizon_distance_analytical(mass_1=1.4, mass_2=1.4)
>>> print(f"H1 horizon: {horizon['H1']:.1f} Mpc")

horizon_distance_numerical(mass_1=1.4, mass_2=1.4, luminosity_distance=100.0, theta_jn=0.0, psi=0.0, phase=0.0, geocent_time=1246527224.169434, ra=0.0, dec=0.0, a_1=0.0, a_2=0.0, tilt_1=0.0, tilt_2=0.0, phi_12=0.0, phi_jl=0.0, lambda_1=0.0, lambda_2=0.0, eccentricity=0.0, snr_th=None, snr_th_net=None, detector_location_as_optimal_sky=False, minimize_function_dict=None, root_scalar_dict=None, maximization_check=False)

Calculate detector horizon distance with optimal sky positioning and arbitrary spin parameters.

Finds the maximum luminosity distance at which a gravitational wave signal can be detected above threshold SNR. For each detector, determines optimal sky location that maximizes antenna response, then solves for distance where SNR equals threshold.

Parameters:

mass_1float, default=1.4

Primary mass in solar masses.

mass_2float, default=1.4

Secondary mass in solar masses.

psifloat, default=0.0

Polarization angle in radians.

phasefloat, default=0.0

Coalescence phase in radians.

geocent_timefloat, default=1246527224.169434

GPS coalescence time at geocenter in seconds.

a_1float, default=0.0

Primary spin magnitude (dimensionless).

a_2float, default=0.0

Secondary spin magnitude (dimensionless).

tilt_1float, default=0.0

Primary spin tilt angle in radians.

tilt_2float, default=0.0

Secondary spin tilt angle in radians.

phi_12float, default=0.0

Azimuthal angle between spins in radians.

phi_jlfloat, default=0.0

Azimuthal angle between total and orbital angular momentum in radians.

lambda_1float, default=0.0

Primary tidal deformability (dimensionless).

lambda_2float, default=0.0

Secondary tidal deformability (dimensionless).

eccentricityfloat, default=0.0

Orbital eccentricity at reference frequency.

gw_param_dictdict or bool, default=False

Parameter dictionary. If provided, overrides individual arguments.

snr_thfloat, optional

Individual detector SNR threshold. Uses class default if None.

snr_th_netfloat, optional

Network SNR threshold. Uses class default if None.

detector_location_as_optimal_skybool, default=False

If True, uses detector zenith as optimal sky location instead of optimization.

minimize_function_dictdict, optional

Parameters for sky location optimization. It contains input for scipy’s differential_evolution. Default: dict(

bounds=[(0, 2*np.pi), (-np.pi/2, np.pi/2)], # ra, dec bounds tol=1e-7, polish=True, maxiter=10000

)

root_scalar_dictdict, optional

Parameters for horizon distance root finding. It contains input for scipy’s root_scalar. Default: dict(

bracket=[1, 100000], # redshift range method=’bisect’, xtol=1e-5

)

maximization_checkbool, default=False

Verify that antenna response maximization achieved ~1.0.

Returns:

horizondict

Horizon distances in Mpc for each detector and network (‘snr_net’).

optimal_sky_locationdict

Optimal sky coordinates (ra, dec) in radians for maximum SNR at given geocent_time.

Notes

• Uses differential evolution to find optimal sky location maximizing antenna response

• Network horizon maximizes quadrature sum of detector SNRs

• Individual detector horizons maximize (F_plus² + F_cross²)

• Root finding determines distance where SNR equals threshold

• Computation time depends on optimization tolerances and system complexity

Examples

>>> snr = GWSNR(snr_method='inner_product')
>>> horizon, sky = snr.horizon_distance_numerical(mass_1=1.4, mass_2=1.4)
>>> print(f"Network horizon: {horizon['snr_net']:.1f} Mpc at (RA={sky['snr_net'][0]:.2f}, Dec={sky['snr_net'][1]:.2f})")