`gwsnr`

GWSNR: Gravitational Wave Signal-to-Noise Ratio

Package Contents

Classes

GWSNR

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

class gwsnr.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')[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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()[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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})")

gwsnr

Subpackages

Package Contents

Classes

`gwsnr`