gwBOB.gen_utils module

gwBOB.gen_utils.Omega_0_fit_news(mf, chif_with_sign)[source]

Omega_0 for news using the fit from Kankani and McWilliams (2025)

Parameters:

  • mf (float) – Remnant mass.

  • chif_with_sign (float) – Remnant spin. (negative values indicate a final spin pointing opposite to the initial orbital angular momentum)

Returns:

Omega_0 fit.

Return type:

float

gwBOB.gen_utils.Omega_0_fit_psi4(mf, chif_with_sign)[source]

Omega_0 for psi4 using the fit from Kankani and McWilliams (2025)

Parameters:

  • mf (float) – Remnant mass.

  • chif_with_sign (float) – Remnant spin. (negative values indicate a final spin pointing opposite to the initial orbital angular momentum)

Returns:

Omega_0 fit.

Return type:

float

gwBOB.gen_utils.Omega_0_fit_strain(mf, chif_with_sign)[source]

Omega_0 for strain using the fit from Kankani and McWilliams (2025)

Parameters:

  • mf (float) – Remnant mass.

  • chif_with_sign (float) – Remnant spin. (negative values indicate a final spin pointing opposite to the initial orbital angular momentum)

Returns:

Omega_0 fit.

Return type:

float

gwBOB.gen_utils.compute_one_more_term(nth_derivative, t, freq)[source]

Compute an additional correction term using spline differentiation and 1/(i omega).

Parameters:

  • nth_derivative (numpy.ndarray) – Values of the nth derivative.

  • t (numpy.ndarray) – Time samples corresponding to nth_derivative.

  • freq (numpy.ndarray) – Angular frequency samples at t.

Returns:

Correction term values evaluated on t.

Return type:

numpy.ndarray

gwBOB.gen_utils.create_QNM_comparison(t, y, NR_data, mov_time, tf, mf, chif, n_qnms=7)[source]

Compare a model against NR by fitting QNM sums over a moving end-time window.

Parameters:

  • t (numpy.ndarray) – Sampling times of the model.

  • y (numpy.ndarray) – Complex model values at t.

  • NR_data (scri.WaveformModes) – Reference waveform mode data (scri object).

  • mov_time (array-like) – Start times for the moving-window comparison (relative to peak after alignment).

  • tf (float) – End time for the mismatch calculation window.

  • mf (float) – Remnant mass.

  • chif (float) – Signed dimensionless remnant spin.

  • n_qnms (int, optional) – Maximum number of overtones to include in fits, by default 7.

Returns:

(master_mismatch_arr, A220_dict, A221_dict, A222_dict, qnm_wm_master_arr).

Return type:

tuple

gwBOB.gen_utils.create_scri_news_waveform_mode(times, y_22_data, ell_min=2, ell_max=None)[source]

Create a scri.WaveformModes object (news) from time samples and a single mode.

Parameters:

  • times (numpy.ndarray) – Sampling times.

  • y_22_data (numpy.ndarray) – Complex data for the (2, 2) mode.

  • ell_min (int, optional) – Minimum ell included in the WaveformModes, by default 2.

  • ell_max (int, optional) – Maximum ell included. If None, inferred from provided data, by default None.

Returns:

Constructed news WaveformModes object.

Return type:

scri.WaveformModes

gwBOB.gen_utils.create_scri_psi4_waveform_mode(times, y_22_data, ell_min=2, ell_max=None)[source]

Create a scri.WaveformModes object (psi4) from time samples and a single mode.

Parameters:

  • times (numpy.ndarray) – Sampling times.

  • y_22_data (numpy.ndarray) – Complex data for the (2, 2) mode.

  • ell_min (int, optional) – Minimum ell included in the WaveformModes, by default 2.

  • ell_max (int, optional) – Maximum ell included. If None, inferred from provided data, by default None.

Returns:

Constructed psi4 WaveformModes object.

Return type:

scri.WaveformModes

gwBOB.gen_utils.estimate_parameters(BOB, mf_guess=0.95, chif_guess=0.5, Omega0_guess=0.155, t0=0, tf=75, force_Omega0_optimization=False, NR_data=None, make_current_naturally=False, make_mass_naturally=False, include_Omega0_as_parameter=False, include_2Omega0_as_parameters=False, perform_phase_alignment_first=False, start_with_wide_search=False, t_shift_range=None)[source]

Estimate BOB parameters by minimizing mismatch against NR data.

Parameters:

  • BOB (object) – A configured BOB instance.

  • mf_guess (float, optional) – Initial guess for remnant mass, by default 0.95.

  • chif_guess (float, optional) – Initial guess for signed dimensionless spin, by default 0.5.

  • Omega0_guess (float, optional) – Initial guess for initial condition frequency, by default 0.155.

  • t0 (float, optional) – Start time after peak for mismatch window, by default 0.

  • tf (float, optional) – End time after peak for mismatch window, by default 75.

  • force_Omega0_optimization (bool, optional) – If True, enforce Omega_0 optimization during construction, by default False.

  • NR_data (kuibit_ts, optional) – Reference data to compare against. If None, inferred from BOB selection.

  • make_current_naturally (bool, optional) – If True, construct current quadrupole via natural method, by default False.

  • make_mass_naturally (bool, optional) – If True, construct mass quadrupole via natural method, by default False.

  • include_Omega0_as_parameter (bool, optional) – Include Omega_0 as an optimization parameter, by default False.

  • include_2Omega0_as_parameters (bool, optional) – Include both lm and lmm Omega_0 as parameters (quadrupole builds), by default False.

  • perform_phase_alignment_first (bool, optional) – If True, perform phase alignment before quadrupole combination, by default False.

  • start_with_wide_search (bool, optional) – If True, run a global search before local refinement, by default False.

  • t_shift_range (numpy.ndarray, optional) – Range of time shifts to search in mismatch, by default np.arange(-10, 10, 0.1).

Returns:

Optimizer result containing best-fit parameters.

Return type:

scipy.optimize.OptimizeResult

gwBOB.gen_utils.find_nearest_index(array, value)[source]

Return the index of the element in array closest to value.

Parameters:

  • array (numpy.ndarray) – 1D array to search.

  • value (float) – Target value to find the nearest element to.

Returns:

Index of the nearest value in array.

Return type:

int

gwBOB.gen_utils.get_Omega_isco(mf, chif_with_sign)[source]

Compute the orbital angular velocity at the ISCO for a Kerr black hole. For negative chif_with_sign values, we return the retrograde value

Parameters:

  • mf (float) – Mass of the remnant (in geometric units).

  • chif_with_sign (float) – Dimensionless spin of the remnant. Negative value indicates a spin pointed opposite the direction of the initial anular momentum of the binary.

Returns:

ISCO angular velocity.

Return type:

float

gwBOB.gen_utils.get_frequency(ts)[source]

Compute the instantaneous angular frequency of a complex TimeSeries.

Parameters:

ts (Kuibit TimeSeries) – Complex-valued time series.

Returns:

TimeSeries of angular frequency. Sign is chosen positive near peak amplitude.

Return type:

Kuibit TimeSeries

gwBOB.gen_utils.get_kuibit_frequency_lm(w, l, m)[source]

Compute the instantaneous angular frequency of the (l, m) mode as a kuibit TimeSeries.

The phase of the mode is unwrapped and differentiated to obtain angular frequency. The sign is flipped to ensure positive frequencies near merger.

Parameters:

  • w (scri.WaveformModes) – Waveform containing spherical-harmonic modes (psi4 recommended).

  • l (int) – Spherical-harmonic index l.

  • m (int) – Spherical-harmonic index m.

Returns:

TimeSeries of angular frequency for the selected mode.

Return type:

kuibit_ts

gwBOB.gen_utils.get_kuibit_lm(w, l, m)[source]

Extract the (l, m) mode from a sxs.WaveformModes and return a kuibit TimeSeries.

Parameters:

  • w (sxs.WaveformModes) – Waveform containing spherical-harmonic modes.

  • l (int) – Spherical-harmonic index l.

  • m (int) – Spherical-harmonic index m.

Returns:

TimeSeries of the selected mode values over time.

Return type:

kuibit_ts

gwBOB.gen_utils.get_kuibit_lm_psi4(w, l, m)[source]

Extract the (l, m) mode from a sxs.WaveformModes psi4 object into a kuibit TimeSeries.

Notes

This accessor expects a psi4-like object where mode data is accessed as w[:, index].ndarray.

Parameters:

  • w (sxs.WaveformModes) – Psi4 waveform containing spherical-harmonic modes.

  • l (int) – Spherical-harmonic index l.

  • m (int) – Spherical-harmonic index m.

Returns:

TimeSeries of the selected psi4 mode values over time.

Return type:

kuibit_ts

gwBOB.gen_utils.get_phase(ts)[source]

Return the unwrapped phase of a complex TimeSeries.

Parameters:

ts (Kuibit TimeSeries) – Complex-valued time series.

Returns:

TimeSeries of unwrapped phase. Sign may be flipped to be positive near merger.

Return type:

Kuibit TimeSeries

gwBOB.gen_utils.get_qnm(mf, chif, l, m, n=0, sign=1)[source]

Get the fundamental quasinormal mode frequency components for a Kerr black hole.

Parameters:

  • mf (float) – Final black-hole mass (geometric units).

  • chif (float) – Dimensionless final spin magnitude (chi).

  • l (int) – Spherical-harmonic index l.

  • m (int) – Spherical-harmonic index m (sign handled via sign).

  • n (int, optional) – Overtone number, by default 0.

  • sign (int, optional) – Mode sign (+1 for m, -1 for -m), by default 1.

Returns:

(w_r, tau) where w_r is the real angular frequency and tau is the damping time.

Return type:

tuple[float, float]

gwBOB.gen_utils.get_r_isco(mf, chif_with_sign)[source]

Compute the prograde ISCO radius for a Kerr black hole. For negative chif_with_sign values, we return the retrograde value

Parameters:

  • mf (float) – Mass of the remnant (in geometric units).

  • chif_with_sign (float) – Dimensionless spin of the remnant. Negative value indicates a spin pointed opposite the direction of the initial anular momentum of the binary.

Returns:

ISCO radius.

Return type:

float

gwBOB.gen_utils.get_tp_Ap_from_spline(amp)[source]

Find the peak time and amplitude using a cubic-spline interpolation.

Parameters:

amp (Kuibit TimeSeries) – TimeSeries of amplitude (e.g., |h| or |psi4|).

Returns:

(tp, Ap) where tp is the peak time and Ap is the peak amplitude.

Return type:

tuple[float, float]

gwBOB.gen_utils.load_lower_lev_SXS(sim)[source]

Load the next-lower available resolution for an SXS simulation.

Parameters:

sim (sxs.Simulation) – The loaded SXS Simulation at some refinement level.

Returns:

The lower-resolution Simulation, if available.

Return type:

sxs.Simulation

Raises:

ValueError – If only one level exists or the lower level cannot be found.

gwBOB.gen_utils.mismatch(model_data, NR_data, t0, tf, use_trapz=False, resample_NR_to_model=True, return_best_phi0=False)[source]

Compute the normalized mismatch between a model and reference time series.

Parameters:

  • model_data (Kuibit TimeSeries) – Model complex time series.

  • NR_data (Kuibit TimeSeries) – Reference complex time series.

  • t0 (float) – Start time relative to the reference peak time.

  • tf (float) – End time relative to the reference peak time.

  • use_trapz (bool, optional) – If True, use trapezoidal integration; otherwise use spline definite integral, by default False.

  • resample_NR_to_model (bool, optional) – If True, resample NR data onto the model time grid when they differ, by default True.

  • return_best_phi0 (bool, optional) – If True, also return the phase shift that maximizes the overlap, by default False.

Returns:

Mismatch in [0, 1]. If return_best_phi0 is True, also returns best_phi0.

Return type:

float or tuple[float, float]

gwBOB.gen_utils.time_grid_mismatch(model, NR_data, t0, tf, resample_NR_to_model=True, t_shift_range=None, return_best_t_and_phi0=False)[source]

Search over time shifts to minimize mismatch between model and reference.

Parameters:

  • model (Kuibit TimeSeries) – Model complex time series.

  • NR_data (Kuibit TimeSeries) – Reference complex time series.

  • t0 (float) – Start time relative to reference peak.

  • tf (float) – End time relative to reference peak.

  • resample_NR_to_model (bool, optional) – If True, resample NR data onto model time grid, by default True.

  • t_shift_range (numpy.ndarray, optional) – Range of time shifts to search, by default np.arange(-10, 10, 0.1).

  • return_best_t_and_phi0 (bool, optional) – If True, also return the best time shift and phase shift, by default False.

Returns:

Minimum mismatch, and optionally best t_shift and phi0.

Return type:

float or tuple

gwBOB.gen_utils.time_integral(ts, order=2, f=0.1, dt=0.1, remove_drift=False)[source]

Integrate a complex time series with high-pass filtering to control low-frequency drift.

The signal is optionally resampled to fixed timestep, high-pass filtered, and cumulatively integrated. An optional weighted-detrend step can remove residual linear drift.

Parameters:

  • ts (kuibit_ts) – Complex time series to integrate.

  • order (int, optional) – Butterworth filter order, by default 2.

  • f (float, optional) – High-pass cutoff as a fraction of peak frequency, by default 0.1.

  • dt (float, optional) – Desired timestep for resampling and integration, by default 0.1.

  • remove_drift (bool, optional) – If True, apply weighted detrending to integral, by default False.

Returns:

Integrated complex time series.

Return type:

kuibit_ts

gwBOB.gen_utils.weighted_detrend(signal, weight_power=2)[source]

Perform weighted linear detrending with heavier weight on later samples.

Parameters:

  • signal (numpy.ndarray) – Real-valued signal to detrend.

  • weight_power (float, optional) – Exponent controlling the late-time weighting, by default 2.

Returns:

Detrended signal.

Return type:

numpy.ndarray