Remnants

Non-precessing kick (Islam & Wadekar 2025)

gwModels.remnants.IW2025_kick_nonprecessing.gwModel_kick_q200(q, chi1z, chi2z, return_std=False)[source]

Kick velocity for aligned-spin binaries. From Islam & Wadekar (2025), https://arxiv.org/abs/2511.11536

Trained on NR (SXS + RIT, q <= 32) and BHPT data (q <= 200). Valid for 1 <= q <= 1000.

Parameters:

q – Mass ratio m1/m2 >= 1
chi1z – Dimensionless spin of primary along z, in [-1, 1]
chi2z – Dimensionless spin of secondary along z, in [-1, 1]
return_std – If True, also return parameter uncertainty estimate

Returns:

Kick velocity in km/s V_kick_std (optional): Estimated uncertainty in km/s

Return type:

V_kick

GPR kick (Islam & Wadekar 2025)

class gwModels.remnants.IW2025_kick_gpr.gwModel_kick_q200_GPR(model_path)[source]

Bases: object

GPR-based aligned-spin kick velocity model. From Islam & Wadekar (2025), https://arxiv.org/abs/2511.11536

Gaussian Process trained on kick data with features [log2(q), chi_hat, chi_a].

For the analytical kick model, use gwModel_kick_q200 from IW2025_kick_nonprecessing.

Parameters:: model_path (str) – Path to the .pkl model file.

predict(q, chi1z, chi2z)[source]

GPR kick prediction.

Parameters:

q – Mass ratio m1/m2 >= 1
chi1z – Dimensionless spin of primary along z, in [-1, 1]
chi2z – Dimensionless spin of secondary along z, in [-1, 1]

Returns:

Kick velocity in km/s vk_std: GPR uncertainty in km/s

Return type:

vk

info()[source]

Precessing kick flow (Islam & Wadekar 2025)

class gwModels.remnants.IW2025_kick_precessing.gwModel_kick_prec_flow(datadir)[source]

Bases: object

Normalizing-flow model for precessing-spin kick velocity distributions.

Samples kick velocities for given (q, a1, a2), marginalizing over spin orientation angles.

Parameters:: datadir (str) – Directory containing gwModel_kick_prec_flow.pt and gwModel_kick_prec_flow_config.npy

sample(q, a1, a2, num_samples=5000)[source]

Sample kick velocities from the flow model.

Accepts scalar or array (q, a1, a2). Array inputs (length N) are evaluated in a single batched call over the flow rather than one binary at a time. For non-spinning systems (a1==0 and a2==0), falls back to the aligned-spin model gwModel_kick_q200 (applied per element).

Parameters:

q – Mass ratio(s) (m1/m2 >= 1), scalar or array
a1 – Primary spin magnitude(s), scalar or array
a2 – Secondary spin magnitude(s), scalar or array
num_samples – Number of samples to draw per binary

Returns:

kick velocities in km/s. Shape conventions:

scalar (q, a1, a2) -> (num_samples,)
array of length N, num_samples=1 -> (N,)
array of length N, num_samples>1 -> (N, num_samples)

Return type:

samples

Note

Batched and per-binary calls are statistically equivalent but not element-wise identical (the RNG is consumed in a different order).

log_prob(v_kick, q, a1, a2)[source]

Conditional log-density log p(v_kick | q, a1, a2) of the kick magnitude.

Evaluates the flow’s density of the recoil magnitude v = |x| by folding the two signed branches of the underlying variable and including the normalization Jacobian, so that exp(log_prob) integrates to 1 over v >= 0. All inputs broadcast to a common shape and are scored in a single batched call.

This is the primitive for inverting the model (inferring progenitor q, a1, a2 from an observed kick via Bayes). It represents the smooth flow density and does not apply the non-spinning delta-function fallback used by sample(); intended for spinning systems.

Parameters:

v_kick – Observed kick magnitude(s) [km/s], scalar or array
q – Progenitor parameters, scalar or array
a1 – Progenitor parameters, scalar or array
a2 – Progenitor parameters, scalar or array

Returns:

log-density, scalar if all inputs are scalar else a 1-D array.

info()[source]

HLZ kick

gwModels.remnants.HLZ_kick.spin_difference_vector(small_q, a1, a2, theta1, theta2, delta_phi)[source]

Calculate the antisymmetric spin combination Delta = (S2/m2 - S1/m1)/(1+q).

Parameters:

small_q – mass ratio m2/m1 <= 1 (internal convention)
a1 – dimensionless spin magnitudes
a2 – dimensionless spin magnitudes
theta1 – angles between L and spin vectors (radians)
theta2 – angles between L and spin vectors (radians)
delta_phi – azimuthal angle difference between spins (radians)

Returns:

Delta_parallel, Delta_perp

gwModels.remnants.HLZ_kick.total_spin_vector(small_q, a1, a2, theta1, theta2, delta_phi)[source]

Calculate the symmetric spin combination chi = (S1 + S2)/M^2.

Parameters:

small_q – mass ratio m2/m1 <= 1 (internal convention)
a1 – dimensionless spin magnitudes
a2 – dimensionless spin magnitudes
theta1 – angles between L and spin vectors (radians)
theta2 – angles between L and spin vectors (radians)
delta_phi – azimuthal angle difference between spins (radians)

Returns:

chi_tilde_parallel, chi_tilde_perp

gwModels.remnants.HLZ_kick.calculate_kick_components(small_q, a1, a2, theta1, theta2, delta_phi, Theta=None)[source]

Calculate the three kick velocity components.

Parameters:

small_q – mass ratio m2/m1 <= 1 (internal convention)
a1 – dimensionless spin magnitudes
a2 – dimensionless spin magnitudes
theta1 – angles between L and spin vectors (radians)
theta2 – angles between L and spin vectors (radians)
delta_phi – azimuthal angle difference between spins (radians)
Theta – angle between Delta x L and fiducial infall direction (radians). If None, a random value between 0 and 2pi is used.

Returns:

Vm, Vs_perp, Vs_parallel, Theta_used

gwModels.remnants.HLZ_kick.bbh_final_kick_precessing_CLZM2007(q, a1, a2, theta1, theta2, delta_phi, Theta=None, debug=False)[source]

Calculate total kick velocity magnitude.

Parameters:

q – mass ratio q = m1/m2 >= 1
a1 – dimensionless spin magnitudes
a2 – dimensionless spin magnitudes
theta1 – angles between L and spin vectors (radians)
theta2 – angles between L and spin vectors (radians)
delta_phi – azimuthal angle difference between spins (radians)
Theta – angle between Delta x L and fiducial infall direction (radians). If None, a random value between 0 and 2pi is used.
debug – if True, return all components

Returns:

total kick velocity in km/s If debug=True: V_kick, Vm, Vs_perp, Vs_parallel, Theta_used

Return type:

V_kick (float)

gwModels.remnants.HLZ_kick.bbh_final_kick_nonprecessing_HLZ2014(q, chi1z, chi2z)[source]

RIT aligned-spin recoil (kick) for binaries with spins along +/-z. Coefficients from arXiv:1406.7295.

Parameters:

q – mass ratio q = m1/m2 >= 1
chi1z – dimensionless spin of primary along z in [-1, 1]
chi2z – dimensionless spin of secondary along z in [-1, 1]

Returns:

kick velocity in km/s

Return type:

V_kick

HBR final mass and spin

gwModels.remnants.HBR_mass_spin.energy_at_isco(a)[source]: Dimensionless specific energy at the ISCO: E_ISCO(a).

gwModels.remnants.HBR_mass_spin.angular_momentum_at_isco(a)[source]: Dimensionless specific angular momentum at ISCO: L_ISCO(a).

gwModels.remnants.HBR_mass_spin.angle_between_spins(theta1, theta2, delta_phi)[source]: Angle alpha between the two spin vectors using spherical law of cosines.

gwModels.remnants.HBR_mass_spin.angle_correction(theta, eps)[source]: Angle remapping from Eq. (18): tan(theta’/2) = (1+eps) tan(theta/2).

gwModels.remnants.HBR_mass_spin.bbh_final_mass_precessing_BMR2012(q, a1, a2, theta1, theta2, verbose=False)[source]

Final remnant mass using Barausse-Morozova-Rezzolla (2012) fit.

Parameters:

q – Mass ratio q = m1/m2 >= 1
a1 – Dimensionless spin magnitudes (0 <= a <= 1)
a2 – Dimensionless spin magnitudes (0 <= a <= 1)
theta1 – Angles (radians) between orbital momentum and spins
theta2 – Angles (radians) between orbital momentum and spins
verbose – Print intermediate calculations (default: False)

Returns:

Remnant mass as fraction of initial total mass M_f/M

Return type:

Mfin

Reference: Barausse, Morozova & Rezzolla (2012), ApJ 758, 63, arXiv:1206.3803

gwModels.remnants.HBR_mass_spin.bbh_final_spin_precessing_HBR2016(q, a1, a2, theta1, theta2, delta_phi, model='HBR16_34corr', verbose=False)[source]

Final spin magnitude using Hofmann, Barausse & Rezzolla (2016) fit.

Parameters:

q – Mass ratio q = m1/m2 >= 1
a1 – Dimensionless spin magnitudes (0 <= a <= 1)
a2 – Dimensionless spin magnitudes (0 <= a <= 1)
theta1 – Angles (radians) between orbital momentum and spins
theta2 – Angles (radians) between orbital momentum and spins
delta_phi – Angle between spin projections on orbital plane
model – Fit model selection (default: “HBR16_34corr”)
verbose – Print intermediate calculations

Returns:

Final spin magnitude |a_final| <= 1

Return type:

chi_final

Reference: Hofmann, Barausse & Rezzolla (2016), ApJL 825, L19, arXiv:1605.01938

UIB2016 final mass and spin

gwModels.remnants.UIB2016_mass_spin.bbh_final_mass_non_precessing_UIB2016(q, chi1z, chi2z, version='v2')[source]

Final mass fraction Mf/M using the UIB2016 fit, parameterized by mass ratio.

Parameters:

q – Mass ratio q = m1/m2 >= 1
chi1z – Dimensionless spins along z in [-1, 1]
chi2z – Dimensionless spins along z in [-1, 1]
version – “v1” or “v2” (default “v2”)

Returns:

Final mass as a fraction of total mass

Return type:

Mf_over_M

gwModels.remnants.UIB2016_mass_spin.bbh_final_spin_non_precessing_UIB2016(q, chi1z, chi2z, version='v2')[source]

Final spin using the UIB2016 fit, parameterized by mass ratio.

Parameters:

q – Mass ratio q = m1/m2 >= 1
chi1z – Dimensionless spins along z in [-1, 1]
chi2z – Dimensionless spins along z in [-1, 1]
version – “v1” or “v2” (default “v2”)

Returns:

Final spin magnitude

Return type:

chif

Utilities

gwModels.remnants.remnant_utils.validate_q(q)[source]: Validate that q = m1/m2 >= 1.

gwModels.remnants.remnant_utils.validate_spin_magnitudes(a1, a2)[source]: Validate that spin magnitudes are in [0, 1].

gwModels.remnants.remnant_utils.validate_spin_z(chi1z, chi2z)[source]: Validate that spin z-components are in [-1, 1].

gwModels.remnants.remnant_utils.symmetric_mass_ratio(q)[source]

Calculate symmetric mass ratio eta(q) = q/(1+q)^2.

eta = 0.25 for equal masses (q = 1), eta -> 0 for q -> infinity. The formula is symmetric under q -> 1/q, so works for any q > 0.

Parameters:: q – Mass ratio q = m1/m2 >= 1.
Returns:: Symmetric mass ratio.
Return type:: float or array

gwModels.remnants.remnant_utils.kerr_isco_radius(a)[source]

Calculate Boyer-Lindquist r_ISCO(a) for equatorial orbits of a Kerr BH.

Parameters:: a – Dimensionless spin parameter (|a| <= 1). Positive for prograde, negative for retrograde orbits.
Returns:: ISCO radius in units of GM/c^2.
Return type:: float or array