Eccentricity Measures

Eccentricity from modulations

class gwModels.ecc_measures.compute_ecc_xi.ComputeEccentricityFromModulations(time_xi, xi, q, t_ref=None, ecc_prefactor=None, distance_btw_peaks=100, fit_funcs_orders=None, include_zero_zero=False, set_unphysical_xi_to_zero=False, set_unphysical_ecc_to_zero=False, tc=0)

Bases: object

Class to compute eccentricity using eccentric modulation parameter.

__init__(time_xi, xi, q, t_ref=None, ecc_prefactor=None, distance_btw_peaks=100, fit_funcs_orders=None, include_zero_zero=False, set_unphysical_xi_to_zero=False, set_unphysical_ecc_to_zero=False, tc=0)

Parameters:

• time_xi – time axis

• xi – common modulation parameter

• q – mass ratio (q>=1)

• t_ref – reference time to compute eccentricity

• ecc_prefactor – pre-factor in eccentricity definition; default is 2/3

• distance_btw_peaks – distance between peaks for PeakFinderScipy; default: 100

• fit_funcs_orders – orders of the upper and lower xi fit functions; available options: keys of FIT_ORDER_MAP

• include_zero_zero – if True, include (t=0, y=0) to extrema lists

• set_unphysical_xi_to_zero – if True, set negative/NaN values in fitted xi to zero

• set_unphysical_ecc_to_zero – if True, set negative/NaN values in fitted eccentricity to zero

• tc – time at merger; default is zero

Newtonian_e_t(t, e_0, q, tau_0=None)

Newtonian eccentricity evolution. Page 41, Eq C1 of https://arxiv.org/pdf/1605.00304

PN_order2_e_t(t, e_0, q, tau_0=None)

2PN eccentricity evolution equation.

PN_e_t(t, e_0, q, tau_0=None)

3PN eccentricity evolution equation. Page 41, Eq C1 of https://arxiv.org/pdf/1605.00304

PNorder_to_func_translation(order)

Translate fit function PN order string to fit function callable.

fit_func_2PN(t, e_0)

fit_func_3PN(t, e_0)

fit_func_3PN_m1over8(t, e_0, A1)

fit_func_3PN_m7over8(t, e_0, A7)

fit_func_3PN_m8over8(t, e_0, A8)

fit_func_3PN_m1over8_m8over8(t, e_0, A1, A8)

fit_func_3PN_m1over8_m7over8(t, e_0, A1, A7)

fit_func_3PN_m7over8_m8over8(t, e_0, A7, A8)

fit_func_3PN_m1over8_m7over8_m8over8(t, e_0, A1, A7, A8)

plot_xi(figsize=(8, 5))

Plot the modulation parameter xi.

plot_xi_with_peaks(figsize=(8, 5))

Plot xi with periastron and apastron peaks.

plot_maximas_fit(figsize=(8, 5))

Plot upper envelope fits.

plot_minimas_fit(figsize=(8, 5))

Plot lower envelope fits.

plot_fit_errors(figsize=(8, 5))

Plot errors in upper and lower envelope fits.

plot_xi_with_peaks_and_fits(figsize=(8, 5))

Plot xi with upper and lower envelope fits.

plot_maximas_and_minimas_fit(figsize=(8, 5))

Plot both upper and lower envelope fits.

plot_maximas_minimas_and_avg_fit(figsize=(8, 5))

Plot upper, lower, and average envelope fits.

plot_eccentricity(figsize=(8, 5))

Plot eccentricity evolution.

class gwModels.ecc_measures.compute_ecc_xi.ComputeEccentricity(t_ecc=None, h_ecc_dict=None, t_cir=None, h_cir_dict=None, q=None, t_ref=None, ecc_prefactor=None, distance_btw_peaks=None, fit_funcs_orders=None, include_zero_zero=False, set_unphysical_xi_to_zero=False, set_unphysical_ecc_to_zero=True, method='xi_amp', use_xi_amp_to_get_xi_freq=False, tc=0, t_buffer=0)

Bases: object

Class to compute eccentricity using 22 mode eccentric and circular waveforms.

This is a convenience wrapper that: 1. Computes modulations via NRHME 2. Delegates eccentricity extraction to ComputeEccentricityFromModulations

__init__(t_ecc=None, h_ecc_dict=None, t_cir=None, h_cir_dict=None, q=None, t_ref=None, ecc_prefactor=None, distance_btw_peaks=None, fit_funcs_orders=None, include_zero_zero=False, set_unphysical_xi_to_zero=False, set_unphysical_ecc_to_zero=True, method='xi_amp', use_xi_amp_to_get_xi_freq=False, tc=0, t_buffer=0)

Parameters:

• t_ecc – time array for the eccentric 22 mode waveform

• h_ecc_dict – dictionary of eccentric waveform modes (should contain 22 mode)

• t_cir – time array for the circular waveform modes

• h_cir_dict – dictionary of circular non-spinning waveform modes

• q – mass ratio (q>=1)

• t_ref – reference time to compute eccentricity

• ecc_prefactor – pre-factor in eccentricity definition; default is 2/3

• distance_btw_peaks – distance between peaks for PeakFinderScipy

• fit_funcs_orders – orders of the upper and lower xi fit functions

• include_zero_zero – if True, include (t=0, y=0) to extrema lists

• set_unphysical_xi_to_zero – if True, set negative/NaN in fitted xi to zero

• set_unphysical_ecc_to_zero – if True, set negative/NaN in fitted eccentricity to zero

• method – ‘xi_amp’ or ‘xi_freq’

• use_xi_amp_to_get_xi_freq – if True, compute freq modulation from amp modulation

• tc – time at merger; default is zero

• t_buffer – buffer time for common time grid

Eccentricity from orbital frequency

class gwModels.ecc_measures.compute_ecc_omega_ecc_gw.ComputeEccentricityFromOmega(time_xi, xi_lower, xi_upper, gwnrhme_obj, ecc_prefactor, t_ref)

Bases: object

Class to compute smooth eccentricity using eccentric modulation parameter.

compute_omega_22_ecc()

Compute 22 mode frequency of the eccentric waveform.

compute_omega_22_cir()

Compute 22 mode frequency of the circular waveform.

compute_omega_22_periastron()

Compute omega_22 at periastron from xi parameter.

compute_omega_22_apastron()

Compute omega_22 at apastron from xi parameter.

compute_ecc_omega_22()

Compute ecc_omega_22 eccentricity. Based on Eq(5) of https://arxiv.org/pdf/2209.03390

compute_psi()

Compute psi transformation to have correct Newtonian limit at the leading order. Based on Eq(6b) of https://arxiv.org/pdf/2209.03390

compute_ecc_gw()

Compute e_gw. Based on Eq(6a) of https://arxiv.org/pdf/2209.03390

plot_eccentricities(figsize=(8, 5))

Plot eccentricity evolutions.

plot_omega_22_with_peaks_and_fits(figsize=(8, 5))

Plot eccentric omega 22 along with upper and lower envelope fits.

Initial eccentricity

gwModels.ecc_measures.initial_eccentricity.compute_et_harmonic_3PN(Eb, L, eta)

Compute the initial time-eccentricity e_t in harmonic coordinates at 3PN order for nonspinning compact binaries using the generalized quasi-Keplerian parametrization.

Eq(A120) of arXiv:2409.17636, based on Memmesheimer, Gopakumar, and Schaefer, Phys. Rev. D 70, 104011 (2004).

Parameters:

• Eb (float) – Orbital binding energy (negative for bound orbits).

• L (float) – Orbital angular momentum.

• eta (float) – Symmetric mass ratio, eta = m1*m2/(m1+m2)^2.

Returns:

The time-eccentricity e_t in harmonic coordinates.

Return type:

float

gwModels.ecc_measures.initial_eccentricity.compute_et_ADM_2PN(Eb, L, eta, chi1=0.0, chi2=0.0)

Compute the initial time-eccentricity e_t in ADM coordinates at 2PN order for spin-aligned compact binaries using the quasi-Keplerian parametrization.

Eq(A121) of arXiv:2409.17636, based on Memmesheimer, Gopakumar, and Schaefer, Phys. Rev. D 70, 104011 (2004).

Parameters:

• Eb (float) – Orbital binding energy (negative for bound orbits).

• L (float) – Orbital angular momentum.

• eta (float) – Symmetric mass ratio, eta = m1*m2/(m1+m2)^2.

• chi1 (float) – Dimensionless spin of the heavier body. Default 0.

• chi2 (float) – Dimensionless spin of the lighter body. Default 0.

Returns:

The time-eccentricity e_t in ADM coordinates.

Return type:

float