Remnant Calculators

Base calculator classes that compute individual remnant properties. GWRemnantCalculator inherits from all of these.

Inheritance diagram of gw_remnant.gw_remnant_calculator.GWRemnantCalculator

InitialEnergyMomenta

class gw_remnant.remnant_calculators.initial_energy_momenta.InitialEnergyMomenta(time, h_dict, q, chi1=None, chi2=None, e_ref=None, E_initial=None, L_initial=None)[source]

Bases: object

Calculator for the initial orbital energy and angular momentum of a binary.

Computes the initial orbital binding energy and orbital angular momentum of a binary black hole using post-Newtonian (PN) approximations. The defaults are valid for:

  • non-spinning circular binaries to 5PN (analytic 4PN + NR-calibrated 5PN)

  • aligned-spin binaries to 3PN (spin-orbit and spin-spin)

  • eccentric binaries to 3PN (including spin x eccentricity cross terms)

Initial conditions can either be computed from the PN expressions above or be supplied directly by the user (e.g. read from numerical-relativity metadata).

Sign conventions (geometric units, G = c = 1):

  • E_initial is the POSITIVE binding-energy magnitude, E_initial = -E_bind, so that the ADM mass is M_ADM = M_initial - E_initial. To use an NR value pass E_initial = M_initial - M_ADM (= 1 - initial_ADM_energy for unit total mass).

  • L_initial is the orbital angular momentum magnitude (in units of M^2).

Parameters:

  • time (ndarray) – Array of time values in geometric units (M)

  • h_dict (dict[tuple[int, int], ndarray]) – Dictionary of complex waveform modes with (l,m) tuple keys, e.g., {(2,2): h_22(t), (3,3): h_33(t), …}

  • q (float) – Mass ratio q = m1/m2, where m1 >= m2

  • chi1 (ndarray | list[float] | None) – Spin vector [sx, sy, sz] for the primary black hole at the reference time, dimensionless. Only the aligned (z) component enters the PN energy/angular momentum. Default None.

  • chi2 (ndarray | list[float] | None) – Spin vector [sx, sy, sz] for the secondary black hole at the reference time, dimensionless. Default None.

  • e_ref (float | None) – Eccentricity at the reference time. Default None (circular).

  • E_initial (float | None) – Initial binding-energy magnitude in units of total mass M. If None, computed from the PN expressions. Set to 0 to track energy changes relative to the reference. Default None.

  • L_initial (float | None) – Initial orbital angular momentum in units of M^2. If None, computed from the PN expressions. Set to 0 to track angular momentum changes relative to the reference. Default None.

time

Time array

Type:

np.ndarray

h_dict

Waveform mode dictionary

Type:

dict

q

Mass ratio

Type:

float

chi1

Primary spin vector

Type:

np.ndarray

chi2

Secondary spin vector

Type:

np.ndarray

e_ref

Eccentricity

Type:

float

E_initial

Initial orbital binding-energy magnitude

Type:

float

L_initial

Initial orbital angular momentum

Type:

float

RemnantMassCalculator

class gw_remnant.remnant_calculators.remnant_mass_calculator.RemnantMassCalculator(time, h_dict, q, chi1=None, chi2=None, e_ref=None, E_initial=None, L_initial=None, M_initial=1, use_filter=False)[source]

Bases: InitialEnergyMomenta

Calculator for remnant mass and energy evolution of binary black holes.

This is the base class for all remnant property calculations in the package. It computes the time evolution of energy flux, radiated energy, and mass, culminating in the final remnant black hole mass.

The class computes energy loss through gravitational wave emission by integrating the flux across all waveform modes. It supports optional filtering for smoothing noisy numerical data.

Parameters:

  • time (ndarray) – Array of time values in geometric units (M)

  • h_dict (dict[tuple[int, int], ndarray]) – Dictionary of complex waveform modes with (l,m) tuple keys, e.g., {(2,2): h_22(t), (3,3): h_33(t), …}

  • q (float) – Mass ratio q = m1/m2, where m1 >= m2

  • chi1 (ndarray | list[float] | None) – Spin vector [sx, sy, sz] for primary black hole at the start of the waveform, in dimensionless units. Default is None

  • chi2 (ndarray | list[float] | None) – Spin vector [sx, sy, sz] for secondary black hole at the start of the waveform, in dimensionless units. Default is None

  • e_ref (float | None) – Eccentricity at the reference time. User must provide accurate value; code does not validate. Default is None

  • E_initial (float | None) – Initial energy of the binary in units of total mass M. If None, computed using PN expressions. Set to 0 to inspect energy changes relative to reference. Default is None

  • L_initial (float | None) – Initial angular momentum of the binary in units of M^2. If None, computed using PN expressions. Set to 0 to inspect angular momentum changes relative to reference. Default is None

  • M_initial (float) – Initial total mass of the binary in units of M. Default is 1

  • use_filter (bool) – Whether to apply spline filtering to smooth computed flux. Useful for noisy numerical data. Default is False

use_filter

Whether filtering is applied

Type:

bool

M_initial

Initial total mass

Type:

float

h_dot

Time derivatives of waveform modes

Type:

dict

E_dot

Energy flux (luminosity) as a function of time

Type:

np.ndarray

Eoft

Cumulative radiated energy as a function of time

Type:

np.ndarray

E_rad

Total radiated energy

Type:

float

Moft

Bondi mass (dynamic mass) as a function of time

Type:

np.ndarray

remnant_mass

Final remnant black hole mass

Type:

float

Inherits From:

InitialEnergyMomenta: Provides initial condition calculations

References

Energy flux formulas from arXiv:1802.04276 Remnant mass from arXiv:2301.07215

LinearMomentumCalculator

class gw_remnant.remnant_calculators.kick_velocity_calculator.LinearMomentumCalculator(time, h_dict, q, chi1=None, chi2=None, e_ref=None, E_initial=None, L_initial=None, M_initial=1, use_filter=False)[source]

Bases: RemnantMassCalculator

Calculator for linear momentum and kick velocity of binary black hole mergers.

This class computes the linear momentum carried away by gravitational waves and the resulting recoil (kick) velocity imparted to the remnant black hole. The calculations use angular momentum flux formulas from gravitational wave multipoles.

All calculations are performed in geometric units where G=c=1, with masses in units of total mass M and velocities in units of speed of light c.

Parameters:

  • time (ndarray) – Array of time values in geometric units (M)

  • h_dict (dict[tuple[int, int], ndarray]) – Dictionary of complex waveform modes with (l,m) tuple keys, e.g., {(2,2): h_22(t), (3,3): h_33(t), …}

  • q (float) – Mass ratio q = m1/m2, where m1 >= m2

  • chi1 (ndarray | list[float] | None) – Spin vector [sx, sy, sz] for primary black hole at the start of the waveform, in dimensionless units. Default is None

  • chi2 (ndarray | list[float] | None) – Spin vector [sx, sy, sz] for secondary black hole at the start of the waveform, in dimensionless units. Default is None

  • e_ref (float | None) – Eccentricity at the reference time. User must provide accurate value; code does not validate. Default is None

  • E_initial (float | None) – Initial energy of the binary in units of total mass M. If None, computed using PN expressions. Set to 0 to inspect energy changes relative to reference. Default is None

  • L_initial (float | None) – Initial angular momentum of the binary in units of M^2. If None, computed using PN expressions. Set to 0 to inspect angular momentum changes relative to reference. Default is None

  • M_initial (float) – Initial total mass of the binary in units of M. Default is 1

  • use_filter (bool) – Whether to apply filtering to computed quantities. Default is False

lmax

Maximum l value of modes in the waveform

Type:

int

P_dot

Linear momentum flux vector [3 x N_times] in units of M

Type:

np.ndarray

Poft

Cumulative radiated linear momentum [3 x N_times] in units of M

Type:

np.ndarray

voft

Center of mass velocity vector [3 x N_times] in units of c

Type:

np.ndarray

kickoft

Kick velocity magnitude as a function of time in units of c

Type:

np.ndarray

remnant_kick

Final kick velocity magnitude in units of c

Type:

float

remnant_kick_vector

Final kick velocity vector (3,) in units of c

Type:

np.ndarray

peak_kick

Peak kick velocity magnitude in units of c

Type:

float

Inherits From:

RemnantMassCalculator: Provides mass and energy calculations

References

Kick velocity formulas from arXiv:1802.04276 and arXiv:0707.4654

AngularMomentumCalculator

class gw_remnant.remnant_calculators.remnant_spin_calculator.AngularMomentumCalculator(time, h_dict, q, chi1=None, chi2=None, e_ref=None, E_initial=None, L_initial=None, M_initial=1, use_filter=False)[source]

Bases: LinearMomentumCalculator, RemnantMassCalculator, InitialEnergyMomenta

Calculator for angular momentum and remnant spin of binary black holes.

This class computes the angular momentum carried away by gravitational waves and the resulting dimensionless spin of the remnant black hole. The calculations use angular momentum flux formulas from gravitational wave multipoles.

All calculations are performed in geometric units where G=c=1, with angular momentum in units of M^2 and spin being dimensionless.

Parameters:

  • time (ndarray) – Array of time values in geometric units (M)

  • h_dict (dict[tuple[int, int], ndarray]) – Dictionary of complex waveform modes with (l,m) tuple keys, e.g., {(2,2): h_22(t), (3,3): h_33(t), …}

  • q (float) – Mass ratio q = m1/m2, where m1 >= m2

  • chi1 (ndarray | list[float] | None) – Spin vector [sx, sy, sz] for primary black hole at the start of the waveform, in dimensionless units. Default is None

  • chi2 (ndarray | list[float] | None) – Spin vector [sx, sy, sz] for secondary black hole at the start of the waveform, in dimensionless units. Default is None

  • e_ref (float | None) – Eccentricity at the reference time. User must provide accurate value; code does not validate. Default is None

  • E_initial (float | None) – Initial energy of the binary in units of total mass M. If None, computed using PN expressions. Set to 0 to inspect energy changes relative to reference. Default is None

  • L_initial (float | None) – Initial angular momentum of the binary in units of M^2. If None, computed using PN expressions. Set to 0 to inspect angular momentum changes relative to reference. Default is None

  • M_initial (float) – Initial total mass of the binary in units of M. Default is 1

  • use_filter (bool) – Whether to apply filtering to computed quantities. Default is False

J_dot

Angular momentum flux vector [3 x N_times] in units of M^2

Type:

np.ndarray

Joft

Cumulative radiated angular momentum [3 x N_times] in units of M^2

Type:

np.ndarray

spinoft

Dimensionless spin z-component as a function of time

Type:

np.ndarray

remnant_spin

Final remnant dimensionless spin z-component

Type:

float

spin_vector_oft

Dimensionless spin vector [3 x N_times] (x, y, z components)

Type:

np.ndarray

remnant_spin_vector

Final remnant dimensionless spin vector (3,)

Type:

np.ndarray

Inherits From:

LinearMomentumCalculator: Provides linear momentum calculations and _read_dhdt_dict method RemnantMassCalculator: Provides mass calculations InitialEnergyMomenta: Provides initial condition calculations

References

Angular momentum flux formulas from arXiv:1802.04276 and arXiv:0707.4654 Spin calculation from arXiv:2101.11015

PeakLuminosityCalculator

class gw_remnant.remnant_calculators.peak_luminosity_calculator.PeakLuminosityCalculator(time, h_dict, q, chi1=None, chi2=None, e_ref=None, E_initial=None, L_initial=None, M_initial=1, use_filter=False)[source]

Bases: RemnantMassCalculator

Calculator for peak gravitational wave luminosity.

This class computes the peak luminosity (energy flux) of gravitational wave radiation from binary black hole mergers. It uses 4th order spline interpolation to find the maximum of the energy flux time series with improved accuracy beyond the discrete time resolution.

The peak luminosity is an important characteristic of the merger, representing the maximum rate of energy emission in gravitational waves.

Parameters:

  • time (ndarray) – Array of time values in geometric units (M)

  • h_dict (dict[tuple[int, int], ndarray]) – Dictionary of complex waveform modes with (l,m) tuple keys, e.g., {(2,2): h_22(t), (3,3): h_33(t), …}

  • q (float) – Mass ratio q = m1/m2, where m1 >= m2

  • chi1 (ndarray | list[float] | None) – Spin vector [sx, sy, sz] for primary black hole at the start of the waveform, in dimensionless units. Default is None

  • chi2 (ndarray | list[float] | None) – Spin vector [sx, sy, sz] for secondary black hole at the start of the waveform, in dimensionless units. Default is None

  • e_ref (float | None) – Eccentricity at the reference time. User must provide accurate value; code does not validate. Default is None

  • E_initial (float | None) – Initial energy of the binary in units of total mass M. If None, computed using PN expressions. Set to 0 to inspect energy changes relative to reference. Default is None

  • L_initial (float | None) – Initial angular momentum of the binary in units of M^2. If None, computed using PN expressions. Set to 0 to inspect angular momentum changes relative to reference. Default is None

  • M_initial (float) – Initial total mass of the binary in units of M. Default is 1

  • use_filter (bool) – Whether to apply filtering to computed quantities. Default is False

L_peak

Peak luminosity in geometric units (dimensionless)

Type:

float

Inherits From:

RemnantMassCalculator: Provides energy flux (E_dot) calculations

References

Peak luminosity definition from arXiv:2010.00120, Eq. (1)