Functions
def	get_tilts (chi1x, chi1y, chi1z, chi2x, chi2y, chi2z, Lnx, Lny, Lnz)
	Given the spins and ang momentum at a given frequency, find the tilt and in-plane spin angles at that frequency. More...

def	calc_v_trans (q)
	Calculates the transition orbital speed (v_trans) to shift from orbit-averaged to precession-averaged evolution in this hybrid spin evolution code. More...

def	get_nsteps (v_trans)
	Determine the number of frequency steps to use in each segment of the integration while performing orbit-averaged evolution from fref to v_trans. More...

def	get_dt_constant (v_trans)
	Determine the step-size (dt) to use in each frequency interval used for orbit-averaged evolution from fref to v_trans. More...

def	calc_tilts_at_infty_hybrid_evolve (m1, m2, chi1, chi2, tilt1, tilt2, phi12, fref, approx="SpinTaylorT5", spinO=6, lscorr=1, verbose=False, prec_only=False, version='v1', failure_mode='None', **kwargs)
	Calculate tilts at infinity with hybrid orbit-averaged and precession-averaged evolution Evolves tilt1 and tilt2 for a given binary from a reference frequency, fref, to infinite separation by first evolving using orbit-averaged evolution until a transition orbital speed (v_trans) given by calc_v_trans(), and from that point until infinity using precession-averaged evolution. More...

Function Documentation

◆ get_tilts()

def lalsimulation.tilts_at_infinity.hybrid_spin_evolution.get_tilts	(	chi1x,
		chi1y,
		chi1z,
		chi2x,
		chi2y,
		chi2z,
		Lnx,
		Lny,
		Lnz
	)

Given the spins and ang momentum at a given frequency, find the tilt and in-plane spin angles at that frequency.

Inputs: chi1x, chi1y, chi1z: Cartesian spin-magnitude components for the primary object (m1) of the binary chi2x, chi2y, chi2z: Cartesian spin-magnitude components for the secondary object (m2) of the binary Lnx, Lny, Lnz: Cartesian components of the direction of the Newtonian orbital angular momentum (will be normalized) of the binary

Output: tilt1, tilt2: tilt angles of the binary spin-vectors w.r.t. the z-axis: the direction of the Newtonian orbital angular momentum phi12: angle between projection of the two spin-vectors onto the xy plane

Definition at line 30 of file hybrid_spin_evolution.py.

◆ calc_v_trans()

def lalsimulation.tilts_at_infinity.hybrid_spin_evolution.calc_v_trans ( q )

Calculates the transition orbital speed (v_trans) to shift from orbit-averaged to precession-averaged evolution in this hybrid spin evolution code.

v_trans depends on the mass ratio, (q), and is determined using the fitting curve from the paper [Eq. (31) in the paper, https://dcc.ligo.org/P2100029, arXiv:2107.11902]

Input:

q, the binary mass ratio defined as m2/m1, with m1 being the primary (heavier) object; range (0,1].

Output: v_transition (float)

Definition at line 78 of file hybrid_spin_evolution.py.

◆ get_nsteps()

def lalsimulation.tilts_at_infinity.hybrid_spin_evolution.get_nsteps ( v_trans )

Determine the number of frequency steps to use in each segment of the integration while performing orbit-averaged evolution from fref to v_trans.

Input: v_trans (float): the transition orbital speed determined by the fit in calc_v_trans() The value for v_trans must be >= 0.01, which is the least transition orbital speed given in our fit in the paper [Eq. (31) in https://dcc.ligo.org/P2100029, arXiv:2107.11902]

Output: n_steps: (int), the number of steps for evolution to be used in calc_tilts_at_infty_hybrid_evolve()

Definition at line 100 of file hybrid_spin_evolution.py.

◆ get_dt_constant()

def lalsimulation.tilts_at_infinity.hybrid_spin_evolution.get_dt_constant ( v_trans )

Determine the step-size (dt) to use in each frequency interval used for orbit-averaged evolution from fref to v_trans.

This function returns the denominator X in the constant c = 1/X, such that f_high*dt = c in determining the timestep of orbital evolution. Here, f_high is the higher frequency in the frequency interval.

Input: v_trans (float): the transition orbital speed determined by the fit in calc_v_trans()

Output: dt_constant: (int) to be used in calc_tilts_at_infty_hybrid_evolve()

Definition at line 126 of file hybrid_spin_evolution.py.

◆ calc_tilts_at_infty_hybrid_evolve()

def lalsimulation.tilts_at_infinity.hybrid_spin_evolution.calc_tilts_at_infty_hybrid_evolve	(		m1,
			m2,
			chi1,
			chi2,
			tilt1,
			tilt2,
			phi12,
			fref,
			approx = `"SpinTaylorT5"`,
			spinO = `6`,
			lscorr = `1`,
			verbose = `False`,
			prec_only = `False`,
			version = `'v1'`,
			failure_mode = `'None'`,
		**	kwargs
	)

Calculate tilts at infinity with hybrid orbit-averaged and precession-averaged evolution Evolves tilt1 and tilt2 for a given binary from a reference frequency, fref, to infinite separation by first evolving using orbit-averaged evolution until a transition orbital speed (v_trans) given by calc_v_trans(), and from that point until infinity using precession-averaged evolution.

There is also an option to compute the bounds on the tilts and average values at a finite separation (given by the value of the orbital angular momentum, Lf) but the application of the hybrid evolution to this case is not so well tested. In particular, for small enough values of Lf, the hybrid evolution will end at a larger value of the orbital angular momentum than Lf and the precession-averaged evolution will fail because of this. This function does not check for this case.

Inputs:

–Required– m1, m2: Detector frame masses of the binary, in kg chi1, chi2: The dimensionless spin-magnitudes of the binary tilt1, tilt2: tilt angles of the binary spin-vectors w.r.t. the z-axis: the direction of the Newtonian orbital angular momentum phi12: angle between projection of the two spin-vectors onto the xy plane fref: Reference frequency, in Hz; must be <= 20 Hz, since the stepwise evolution is currently only calibrated for such values

–Optional– approx: The approximant to use (options: "SpinTaylorT1", "SpinTaylorT4", "SpinTaylorT5"), default: "SpinTaylorT5" spinO: The order of the spin contributions included in the post-Newtonian expansion (possible values:[4,5,6]), default: 6 lscorr: activates spin contributions to the orbital angular momentum in the precession equations, default: 1 (active) verbose (bool): display details of integration steps and print output of orbit-averaged evolution, default: False prec_only: Use only the precession-averaged evolution for a quick but less accurate result, default: False version: Version of the calculation to use–currently, two versions are available: v1 divides the orbit-averaged part of the hybrid evolution into a series of multiple integration steps, while in v2 it proceeds in a single step using a modified integrator that only outputs the final spin values, default: "v1", though this will be changed to "v2" in a near future release, since the "v2" evolution is much faster and somewhat more accurate failure_mode: How the code behaves when the evolution fails. 'Error' means that the code raises a RuntimeError, while 'NAN' and 'None' mean that the code raises a RuntimeWarning and returns np.nan or None for the output, respectively, default: 'None'

**kwargs: dict, optional: precession-averaged evolution settings, passed through **kwargs to prec_avg_tilt_comp() Please refer to the prec_avg_tilt_comp() documentation in calc_tilts_prec_avg_regularized.py for the list of settings

NOTE: The keyword argument Lf: Final magnitude of orbital angular momentum, if set to None, gives the output at infinity; this is the default. To obtain tilts at a finite separation, provide the corresponding Lf in total mass = 1 units

NOTE: prec_avg_tilt_comp() options LPNorder and LPNspins are not available through here, but are set automatically by the choice of spinO and lscorr.

Output:

Dictionary with entries 'tilt1_inf', 'tilt2_inf' for evolution to infinity, and entries 'tilt1_transition', 'tilt2_transition', 'phi12_transition' for the tilts at the transition orbital speed (v_trans).

NOTE: If kwarg Lf is not set to None in prec_avg_tilt_comp(), the output gives bounds and average values for the tilts at a final separation determined by Lf. In this case, the entries 'tilt1_inf' and 'tilt2_inf' will be replaced by 'tilt1_sep_min', 'tilt1_sep_max', 'tilt1_sep_avg', 'tilt2_sep_min', 'tilt2_sep_max', and 'tilt2_sep_avg'.