Examples

ciao ciao ciao

Package documentation

precession. TODO: write me here

precession.affine(vec, low, up)

precession.angles_to_Jframe(theta1, theta2, deltaphi, r, q, chi1, chi2)

Convert the angles (theta1,theta2,deltaphi) to angular momentum vectors (L,S1,S2) in the frame aligned with the total angular momentum. In particular, we set Jx=Jy=Ly=0.

Parameters:

theta1: float: Angle between orbital angular momentum and primary spin.
theta2: float: Angle between orbital angular momentum and secondary spin.
deltaphi: float: Angle between the projections of the two spins onto the orbital plane.
r: float: Binary separation.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

Lvec: array: Cartesian vector of the orbital angular momentum.
S1vec: array: Cartesian vector of the primary spin.
S2vec: array: Cartesian vector of the secondary spin.

Examples

Lvec,S1vec,S2vec = angles_to_Jframe(theta1,theta2,deltaphi,r,q,chi1,chi2)

precession.angles_to_Lframe(theta1, theta2, deltaphi, r, q, chi1, chi2)

Convert the angles (theta1,theta2,deltaphi) to angular momentum vectors (L,S1,S2) in the frame aligned with the orbital angular momentum. In particular, we set Lx=Ly=S1y=0.

Parameters:

theta1: float: Angle between orbital angular momentum and primary spin.
theta2: float: Angle between orbital angular momentum and secondary spin.
deltaphi: float: Angle between the projections of the two spins onto the orbital plane.
r: float: Binary separation.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

Lvec: array: Cartesian vector of the orbital angular momentum.
S1vec: array: Cartesian vector of the primary spin.
S2vec: array: Cartesian vector of the secondary spin.

Examples

Lvec,S1vec,S2vec = angles_to_Lframe(theta1,theta2,deltaphi,r,q,chi1,chi2)

precession.angles_to_conserved(theta1, theta2, deltaphi, r, q, chi1, chi2, full_output=False)

Convert angles (theta1,theta2,deltaphi) into conserved quantities (S,J,chieff).

Parameters:

theta1: float: Angle between orbital angular momentum and primary spin.
theta2: float: Angle between orbital angular momentum and secondary spin.
deltaphi: float: Angle between the projections of the two spins onto the orbital plane.
r: float: Binary separation.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
full_output: boolean, optional (default: False): Return additional outputs.

Returns:

S: float: Magnitude of the total spin.
J: float: Magnitude of the total angular momentum.
chieff: float: Effective spin.
Other parameters

cyclesign: integer: Sign (either +1 or -1) to cover the two halves of a precesion cycle.

Examples

S,J,chieff = angles_to_conserved(theta1,theta2,deltaphi,r,q,chi1,chi2,full_output=False) S,J,chieff,cyclesign = angles_to_conserved(theta1,theta2,deltaphi,r,q,chi1,chi2,full_output=True)

precession.anglesresonances(r, chieff, q, chi1, chi2)

Compute the values of the angles corresponding to the two spin-orbit resonances.

Parameters:

J: float, optional (default: None): Magnitude of the total angular momentum.
r: float, optional (default: None): Binary separation.
chieff: float, optional (default: None): Effective spin.
q: float, optional (default: None): Mass ratio: 0<=q<=1.
chi1: float, optional (default: None): Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float, optional (default: None): Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

theta1atmin: float: Value of the angle theta1 at the resonance that minimizes either J or chieff, depending on the input.
theta2atmin: float: Value of the angle theta2 at the resonance that minimizes either J or chieff, depending on the input.
deltaphiatmin: float: Value of the angle deltaphi at the resonance that minimizes either J or chieff, depending on the input.
theta1atmax: float: Value of the angle theta1 at the resonance that maximizes either J or chieff, depending on the input.
theta2atmax: float: Value of the angle theta2 at the resonance that maximizes either J or chieff, depending on the input.
deltaphiatmax: float: Value of the angle deltaphi at the resonance that maximizes either J or chieff, depending on the input.

Examples

theta1atmin,theta2atmin,deltaphiatmin,theta1atmax,theta2atmax,deltaphiatmax = anglesresonances(J=None,r=None,chieff=None,q=None,chi1=None,chi2=None)

precession.chiefflimits_definition(q, chi1, chi2)

Limits on the effective spin based only on the definition chieff = (1+q)S1.L + (1+1/q)S2.L.

Parameters:

q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

chieffmin: float: Minimum value of the effective spin chieff.
chieffmax: float: Maximum value of the effective spin chieff.

Examples

chieffmin,chieffmax = chiefflimits_definition(q,chi1,chi2)

precession.chip_terms(theta1, theta2, q, chi1, chi2)

Compute the two terms entering the effective precessing spin chip.

Parameters:

theta1: float: Angle between orbital angular momentum and primary spin.
theta2: float: Angle between orbital angular momentum and secondary spin.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

chipterm1: float: Term in effective precessing spin chip.
chipterm2: float: Term in effective precessing spin chip.

Examples

chipterm1,chipterm2 = chip_terms(theta1,theta2,q,chi1,chi2)

precession.conserved_to_Jframe(deltachi, kappa, r, chieff, q, chi1, chi2, cyclesign=1)

precession.conserved_to_Lframe(deltachi, kappa, r, chieff, q, chi1, chi2, cyclesign=1)

precession.conserved_to_angles(deltachi, kappa, r, chieff, q, chi1, chi2, cyclesign=1)

Convert conserved quantities (S,J,chieff) into angles (theta1,theta2,deltaphi).

Parameters:

S: float: Magnitude of the total spin.
J: float: Magnitude of the total angular momentum.
r: float: Binary separation.
chieff: float: Effective spin.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
cyclesign: integer, optional (default: +1): Sign (either +1 or -1) to cover the two halves of a precesion cycle.

Returns:

theta1: float: Angle between orbital angular momentum and primary spin.
theta2: float: Angle between orbital angular momentum and secondary spin.
deltaphi: float: Angle between the projections of the two spins onto the orbital plane.

Examples

theta1,theta2,deltaphi = conserved_to_angles(S,J,r,chieff,q,chi1,chi2,cyclesign=+1)

precession.dchidt2_RHS(deltachi, kappa, r, chieff, q, chi1, chi2, precomputedroots=None, donotnormalize=False)

precession.ddchidt_prefactor(r, chieff, q)

Numerical prefactor to the S derivative.

Parameters:

r: float: Binary separation.
chieff: float: Effective spin.
q: float: Mass ratio: 0<=q<=1.

Returns:

mathcalA: float: Prefactor in the dSdt equation.

Examples

mathcalA = derS_prefactor(r,chieff,q)

precession.deltachicubic_coefficients(kappa, u, chieff, q, chi1, chi2)

precession.deltachicubic_rescaled_coefficients(kappa, u, chieff, q, chi1, chi2)

precession.deltachilimits_definition(q, chi1, chi2)

Limits on the effective spin based only on the definition chieff = (1+q)S1.L + (1+1/q)S2.L.

Parameters:

q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

chieffmin: float: Minimum value of the effective spin chieff.
chieffmax: float: Maximum value of the effective spin chieff.

Examples

chieffmin,chieffmax = chiefflimits_definition(q,chi1,chi2)

precession.deltachilimits_plusminus(kappa, r, chieff, q, chi1, chi2, precomputedroots=None)

precession.deltachilimits_rectangle(chieff, q, chi1, chi2)

Limits on the asymptotic angular momentum. The contraints considered depend on the inputs provided. - If r, q, chi1, and chi2 are provided, the limits are given by kappa=S1+S2. - If r, chieff, q, chi1, and chi2 are provided, the limits are given by the two spin-orbit resonances. The boolean flag enforce allows raising an error in case the inputs are not compatible.

Parameters:

r: float, optional (default: None): Binary separation.
chieff: float, optional (default: None): Effective spin.
q: float, optional (default: None): Mass ratio: 0<=q<=1.
chi1: float, optional (default: None): Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float, optional (default: None): Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
enforce: boolean, optional (default: False): If True raise errors, if False raise warnings.

Returns:

kappainfmin: float: Minimum value of the asymptotic angular momentum kappainf.
kappainfmin: float: Minimum value of the asymptotic angular momentum kappainf.

Examples

kappainfmin,kappainfmin = kappainflimits(r=None,chieff=None,q=None,chi1=None,chi2=None,enforce=False)

precession.deltachioft(t, kappa, r, chieff, q, chi1, chi2, precomputedroots=None)

Evolution of S on the precessional timescale (without radiation reaction). The broadcasting rules for this function are more general than those of the rest of the code. The variable t is allowed to have shapes (N,M) while all the other variables have shape (N,). This is useful to sample M precession configuration for each of the N binaries specified as inputs.

Parameters:

t: float: Time.
J: float: Magnitude of the total angular momentum.
r: float: Binary separation.
chieff: float: Effective spin.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
precomputedroots: array, optional (default: None): Pre-computed output of Ssroots for computational efficiency.

Returns:

S: float: Magnitude of the total spin.

Examples

S = Soft(t,J,r,chieff,q,chi1,chi2,precomputedroots=None)

precession.deltachirescaling(deltachitilde, kappa, r, chieff, q, chi1, chi2, precomputedroots=None)

precession.deltachiresonance(kappa=None, r=None, u=None, chieff=None, q=None, chi1=None, chi2=None)

Assuming that the inputs correspond to a spin-orbit resonance, find the corresponding value of S. There will be two roots that are conincident if not for numerical errors: for concreteness, return the mean of the real part. This function does not check that the input is a resonance; it is up to the user. Provide either J or kappa and either r or u.

Parameters:

J: float, optional (default: None): Magnitude of the total angular momentum.
kappa: float, optional (default: None): Regularized angular momentum (J^2-L^2)/(2L).
r: float, optional (default: None): Binary separation.
u: float, optional (default: None): Compactified separation 1/(2L).
chieff: float, optional (default: None): Effective spin.
q: float, optional (default: None): Mass ratio: 0<=q<=1.
chi1: float, optional (default: None): Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float, optional (default: None): Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

S: float: Magnitude of the total spin.

Examples

S = Satresonance(J=None,kappa=None,r=None,u=None,chieff=None,q=None,chi1=None,chi2=None)

precession.deltachiroots(kappa, u, chieff, q, chi1, chi2, full_output=True, precomputedroots=None)

Roots of the cubic equation in S^2 that identifies the effective potentials.

Parameters:

J: float: Magnitude of the total angular momentum.
r: float: Binary separation.
chieff: float: Effective spin.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
precomputedroots: array, optional (default: None): Pre-computed output of Ssroots for computational efficiency.

Returns:

Sminuss: float: Lowest physical root, if present, of the effective potential equation.
Spluss: float: Largest physical root, if present, of the effective potential equation.
S3s: float: Spurious root of the effective potential equation.

Examples

Sminuss,Spluss,S3s = Ssroots(J,r,chieff,q,chi1,chi2,precomputedroots=None)

precession.deltachisampling(kappa, r, chieff, q, chi1, chi2, N=1, precomputedroots=None)

Sample N values of S at fixed separation accoring to its PN-weighted distribution function. Can only be used to sample the same number of configuration for each binary. If the inputs J,r,chieff,q,chi1, and chi2 have shape (M,) the output will have shape - (M,N) if M>1 and N>1; - (M,) if N=1; - (N,) if M=1.

Parameters:

J: float: Magnitude of the total angular momentum.
r: float: Binary separation.
chieff: float: Effective spin.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
N: integer, optional (default: 1): Number of samples.

Returns:

S: float: Magnitude of the total spin.

Examples

S = Ssampling(J,r,chieff,q,chi1,chi2,N = 1)

precession.deltachitildeav(m, tol=1e-07)

Factor depending on the elliptic parameter in the precession averaged squared total spin. This is (1 - E(m)/K(m)) / m.

Parameters:

m: float: Parameter of elliptic function(s).

Returns:

coeff: float: Coefficient.

Examples

coeff = deltachitildeav(m)

precession.deltachitildeav2(m, tol=1e-07)

Factor depending on the elliptic parameter in the precession averaged squared total spin. This is (1 - E(m)/K(m)) / m.

Parameters:

m: float: Parameter of elliptic function(s).

Returns:

coeff: float: Coefficient.

Examples

coeff = deltachitildeav(m)

precession.dot_nested(x, y)

Dot product between 2D arrays along last axis.

Parameters:

xarray: Input array.
yarray: Input array.

Returns:

zarray: Dot product array.

Examples

z = dot_nested(x, y)

precession.ellippi(n, phi, m)

Incomplete elliptic integral of the third kind. This is reconstructed using scipy’s implementation of Carlson’s R integrals (arxiv:math/9409227).

Parameters:

n: foat: Characheristic of the elliptic integral.
phi: float: Amplitude of the elliptic integral.
m: float: Parameter of the elliptic integral

Returns:

piintegral: float: Incomplete elliptic integral of the third kind

Examples

piintegral = precession.ellippi(n, phi, m)

precession.elliptic_parameter(kappa, u, chieff, q, chi1, chi2, precomputedroots=None)

Parameter m entering elliptic functions for the evolution of S.

Parameters:

Sminuss: float: Lowest physical root, if present, of the effective potential equation.
Spluss: float: Largest physical root, if present, of the effective potential equation.
S3s: float: Spurious root of the effective potential equation.

Returns:

m: float: Parameter of elliptic function(s).

Examples

m = elliptic_parameter(Sminuss,Spluss,S3s)

precession.eval_J(theta1=None, theta2=None, deltaphi=None, kappa=None, r=None, q=None, chi1=None, chi2=None)

Magnitude of the total angular momentum. Provide either (theta1,theta,deltaphi,r,q,chi1,chhi2) or (kappa,r,q).

Parameters:

theta1: float, optional (default: None): Angle between orbital angular momentum and primary spin.
theta2: float, optional (default: None): Angle between orbital angular momentum and secondary spin.
deltaphi: float, optional (default: None): Angle between the projections of the two spins onto the orbital plane.
kappa: float, optional (default: None): Regularized angular momentum (J^2-L^2)/(2L).
r: float, optional (default: None): Binary separation.
q: float, optional (default: None): Mass ratio: 0<=q<=1.
chi1: float, optional (default: None): Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float, optional (default: None): Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

J: float: Magnitude of the total angular momentum.

Examples

J = eval_J(theta1=None,theta2=None,deltaphi=None,kappa=None,r=None,q=None,chi1=None,chi2=None)

precession.eval_L(r, q)

Newtonian angular momentum of the binary.

Parameters:

r: float: Binary separation.
q: float: Mass ratio: 0<=q<=1.

Returns:

L: float: Magnitude of the Newtonian orbital angular momentum.

Examples

L = eval_L(r,q)

precession.eval_OmegaL(deltachi, kappa, r, chieff, q, chi1, chi2)

Compute the precession frequency OmegaL along the precession cycle.

Parameters:

S: float: Magnitude of the total spin.
J: float: Magnitude of the total angular momentum.
r: float: Binary separation.
chieff: float: Effective spin.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

OmegaL: float: Precession frequency of L about J.

Examples

OmegaL = eval_OmegaL(S,J,r,chieff,q,chi1,chi2)

precession.eval_S(theta1, theta2, deltaphi, q, chi1, chi2)

Magnitude of the total spin from the spin angles.

Parameters:

theta1: float: Angle between orbital angular momentum and primary spin.
theta2: float: Angle between orbital angular momentum and secondary spin.
deltaphi: float: Angle between the projections of the two spins onto the orbital plane.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

S: float: Magnitude of the total spin.

Examples

S = eval_S(theta1,theta2,deltaphi,q,chi1,chi2)

precession.eval_S1(q, chi1)

Spin angular momentum of the heavier black hole.

Parameters:

q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.

Returns:

S1: float: Magnitude of the primary spin.

Examples

S1 = eval_S1(q,chi1)

precession.eval_S2(q, chi2)

Spin angular momentum of the lighter black hole.

Parameters:

q: float: Mass ratio: 0<=q<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

S2: float: Magnitude of the secondary spin.

Examples

S2 = eval_S2(q,chi2)

precession.eval_S_from_deltachi(deltachi, kappa, r, chieff, q)

precession.eval_alpha(kappa, r, chieff, q, chi1, chi2, precomputedroots=None)

precession.eval_bracket_omega(kappa, r, chieff, q, chi1, chi2, precomputedroots=None)

Precession average of the precession frequency of S as it oscillates from S- to S+ back to S-

Parameters:

J: float: Magnitude of the total angular momentum.
r: float: Binary separation.
xi: float: Effective spin.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
precomputedroots: array, optional (default: None): Pre-computed output of Ssroots for computational efficiency.

Returns:

bracket_omega: float: Precession averaged precession frequency.

Examples

bracket_omega = eval_bracket_omega(J,r,xi,q,chi1,chi2,precomputedroots=None)

precession.eval_bracket_theta(kappa, r, chieff, q, chi1, chi2, **kwargs)

Precession average of precession amplitude of S as it oscillates from S- to S+ back to S-

Parameters:

J: float: Magnitude of the total angular momentum.
r: float: Binary separation.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

bracket_theta: float: Precession-averaged precession amplitude.

Examples

bracket_theta = eval_bracket_theta(J,r,xi,q,chi1,chi2,precomputedroots=None)

precession.eval_chi1(q, S1)

Spin angular momentum of the heavier black hole.

Parameters:

q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.

Returns:

S1: float: Magnitude of the primary spin.

Examples

S1 = eval_S1(q,chi1)

precession.eval_chi2(q, S2)

Spin angular momentum of the heavier black hole.

Parameters:

q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.

Returns:

S1: float: Magnitude of the primary spin.

Examples

S1 = eval_S1(q,chi1)

precession.eval_chieff(theta1, theta2, q, chi1, chi2)

Eftective spin. Provide either (theta1,theta2,q,chi1,chi2) or (S,varphi,J,r,q,chi1,chi2).

Parameters:

theta1: float, optional (default: None): Angle between orbital angular momentum and primary spin.
theta2: float, optional (default: None): Angle between orbital angular momentum and secondary spin.
S: float, optional (default: None): Magnitude of the total spin.
varphi: float, optional (default: None): Generalized nutation coordinate (Eq 9 in arxiv:1506.03492).
J: float, optional (default: None): Magnitude of the total angular momentum.
r: float, optional (default: None): Binary separation.
q: float, optional (default: None): Mass ratio: 0<=q<=1.
chi1: float, optional (default: None): Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float, optional (default: None): Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

chieff: float: Effective spin.

Examples

chieff = eval_chieff(theta1=None,theta2=None,S=None,varphi=None,J=None,r=None,q=None,chi1=None,chi2=None)

precession.eval_chip(theta1=None, theta2=None, deltaphi=None, deltachi=None, kappa=None, r=None, chieff=None, q=None, chi1=None, chi2=None, which='averaged', **kwargs)

Compute the effective precessing spin chip, see arxiv:2011.11948. The keyword which one of the following definitions: - heuristic, as in Schmidt et al 2015. Required inputs: theta1,theta2,q,chi1,chi2 - generalized, retail all precession-timescale variations. Required inputs: theta1,theta2,deltaphi,q,chi1,chi2 - asymptotic, large-separation limit. Required inputs: theta1,theta2,q,chi1,chi2 - averaged (default), averages over all precession-timescale variations. Required inputs are either (theta1,theta2,deltaphi,r,q,chi1,chi2) or (J,r,chieff,q,chi1,chi2). The additional keywords methods and Nsamples are passed to precession_average.

Parameters:

theta1: float, optional (default: None): Angle between orbital angular momentum and primary spin.
theta2: float, optional (default: None): Angle between orbital angular momentum and secondary spin.
deltaphi: float, optional (default: None): Angle between the projections of the two spins onto the orbital plane.
J: float, optional (default: None): Magnitude of the total angular momentum.
r: float, optional (default: None): Binary separation.
chieff: float, optional (default: None): Effective spin.
q: float, optional (default: None): Mass ratio: 0<=q<=1.
chi1: float, optional (default: None): Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float, optional (default: None): Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
which: string, optional (default: “averaged”): Select function behavior.
method: string (default: ‘quadrature’): Either ‘quadrature’ or ‘montecarlo’
Nsamples: integer (default: 1e4): Number of Monte Carlo samples.

Returns:

chip: float: Effective precessing spin chip.

Examples

chip = eval_chip(theta1=None,theta2=None,deltaphi=None,J=None,r=None,chieff=None,q=None,chi1=None,chi2=None,which=”averaged”,method=’quadrature’,Nsamples=1e4)

precession.eval_chip_averaged(kappa, r, chieff, q, chi1, chi2, **kwargs)

Averaged definition of the effective precessing spin chip, see arxiv:2011.11948. This definition consistently averages over all variations on the precession timescale. Valid inputs are one of the following (but not both) - theta1, theta2, deltaphi - J, chieff The parameters r, q, chi1, and chi2 should always be provided. The keywords arguments method and Nsamples are passed directly to precession_average.

Parameters:

theta1: float, optional (default: None): Angle between orbital angular momentum and primary spin.
theta2: float, optional (default: None): Angle between orbital angular momentum and secondary spin.
deltaphi: float, optional (default: None): Angle between the projections of the two spins onto the orbital plane.
J: float, optional (default: None): Magnitude of the total angular momentum.
r: float, optional (default: None): Binary separation.
chieff: float, optional (default: None): Effective spin.
q: float, optional (default: None): Mass ratio: 0<=q<=1.
chi1: float, optional (default: None): Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float, optional (default: None): Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
method: string (default: ‘quadrature’): Either ‘quadrature’ or ‘montecarlo’
Nsamples: integer (default: 1e4): Number of Monte Carlo samples.

Returns:

chip: float: Effective precessing spin chip.

Examples

chip = eval_chip_averaged(theta1=None,theta2=None,deltaphi=None,J=None,r=None,chieff=None,q=None,chi1=None,chi2=None,method=’quadrature’,Nsamples=1e4)

precession.eval_chip_generalized(theta1, theta2, deltaphi, q, chi1, chi2)

Generalized definition of the effective precessing spin chip, see arxiv:2011.11948. This definition retains all variations on the precession timescale.

Parameters:

theta1: float: Angle between orbital angular momentum and primary spin.
theta2: float: Angle between orbital angular momentum and secondary spin.
deltaphi: float: Angle between the projections of the two spins onto the orbital plane.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

chip: float: Effective precessing spin chip.

Examples

chip = eval_chip_generalized(theta1,theta2,deltaphi,q,chi1,chi2)

precession.eval_chip_heuristic(theta1, theta2, q, chi1, chi2)

Heuristic definition of the effective precessing spin chip (Schmidt et al 2015), see arxiv:2011.11948. This definition inconsistently averages over some, but not all, variations on the precession timescale.

Parameters:

theta1: float: Angle between orbital angular momentum and primary spin.
theta2: float: Angle between orbital angular momentum and secondary spin.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

chip: float: Effective precessing spin chip.

Examples

chip = eval_chip_heuristic(theta1,theta2,q,chi1,chi2)

precession.eval_chip_rms(kappa, r, chieff, q, chi1, chi2)

precession.eval_cosdeltaphi(deltachi, kappa, r, chieff, q, chi1, chi2)

Cosine of the angle deltaphi between the projections of the two spins onto the orbital plane.

Parameters:

S: float: Magnitude of the total spin.
J: float: Magnitude of the total angular momentum.
r: float: Binary separation.
chieff: float: Effective spin.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

cosdeltaphi: float: Cosine of the angle between the projections of the two spins onto the orbital plane.

Examples

cosdeltaphi = eval_cosdeltaphi(S,J,r,chieff,q,chi1,chi2)

precession.eval_costheta1(deltachi, chieff, q, chi1)

Cosine of the angle theta1 between the orbital angular momentum and the spin of the primary black hole.

Parameters:

S: float: Magnitude of the total spin.
J: float: Magnitude of the total angular momentum.
r: float: Binary separation.
chieff: float: Effective spin.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

costheta1: float: Cosine of the angle between orbital angular momentum and primary spin.

Examples

costheta1 = eval_costheta1(S,J,r,chieff,q,chi1,chi2)

precession.eval_costheta12(theta1=None, theta2=None, deltaphi=None, deltachi=None, kappa=None, chieff=None, q=None, chi1=None, chi2=None)

Cosine of the angle theta12 between the two spins. Valid inputs are either (theta1,theta2,deltaphi) or (S,q,chi1,chi2).

Parameters:

theta1: float, optional (default: None): Angle between orbital angular momentum and primary spin.
theta2: float, optional (default: None): Angle between orbital angular momentum and secondary spin.
deltaphi: float, optional (default: None): Angle between the projections of the two spins onto the orbital plane.
S: float, optional (default: None): Magnitude of the total spin.
q: float, optional (default: None): Mass ratio: 0<=q<=1.
chi1: float, optional (default: None): Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float, optional (default: None): Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

costheta12: float: Cosine of the angle between the two spins.

Examples

costheta12 = eval_costheta12(theta1=None,theta2=None,deltaphi=None,S=None,q=None,chi1=None,chi2=None)

precession.eval_costheta2(deltachi, chieff, q, chi2)

Cosine of the angle theta1 between the orbital angular momentum and the spin of the primary black hole.

Parameters:

S: float: Magnitude of the total spin.
J: float: Magnitude of the total angular momentum.
r: float: Binary separation.
chieff: float: Effective spin.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

costheta1: float: Cosine of the angle between orbital angular momentum and primary spin.

Examples

costheta1 = eval_costheta1(S,J,r,chieff,q,chi1,chi2)

precession.eval_costhetaL(deltachi, kappa, r, chieff, q)

Cosine of the angle thetaL betwen orbital angular momentum and total angular momentum.

Parameters:

S: float: Magnitude of the total spin.
J: float: Magnitude of the total angular momentum.
r: float: Binary separation.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

costhetaL: float: Cosine of the angle betwen orbital angular momentum and total angular momentum.

Examples

costhetaL = eval_costhetaL(S,J,r,q,chi1,chi2)

precession.eval_cyclesign(ddeltachidt=None, deltaphi=None, Lvec=None, S1vec=None, S2vec=None)

Evaluate if the input parameters are in the first of the second half of a precession cycle. We refer to this as the ‘sign’ of a precession cycle, defined as +1 if S is increasing and -1 S is decreasing. Valid inputs are one and not more of the following: - dSdt - deltaphi - varphi - Lvec, S1vec, S2vec.

Parameters:

dSdt: float, optional (default: None): Time derivative of the total spin.
deltaphi: float, optional (default: None): Angle between the projections of the two spins onto the orbital plane.
varphi: float, optional (default: None): Generalized nutation coordinate (Eq 9 in arxiv:1506.03492).
Lvec: array, optional (default: None): Cartesian vector of the orbital angular momentum.
S1vec: array, optional (default: None): Cartesian vector of the primary spin.
S2vec: array, optional (default: None): Cartesian vector of the secondary spin.

Returns:

cyclesign: integer: Sign (either +1 or -1) to cover the two halves of a precesion cycle.

Examples

cyclesign = eval_cyclesign(dSdt=None,deltaphi=None,varphi=None,Lvec=None,S1vec=None,S2vec=None)

precession.eval_delta_omega(kappa, r, chieff, q, chi1, chi2, precomputedroots=None)

Variation of the precession frequency of S as it oscillates from S- to S+ back to S- due to nutational effects

Parameters:

J: float: Magnitude of the total angular momentum.
r: float: Binary separation.
xi: float: Effective spin.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
precomputedroots: array, optional (default: None): Pre-computed output of Ssroots for computational efficiency.

Returns:

delta_omega: float: Precession frequency variation due to nutation.

Examples

delta_omega = eval_delta_omega(J,r,xi,q,chi1,chi2,precomputedroots=None)

precession.eval_delta_theta(kappa, r, chieff, q, chi1, chi2, precomputedroots=None)

Nutation amplitude of S as it oscillates from S- to S+ back to S-

Parameters:

J: float: Magnitude of the total angular momentum.
r: float: Binary separation.
xi: float: Effective spin.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
precomputedroots: array, optional (default: None): Pre-computed output of Ssroots for computational efficiency.

Returns:

delta_theta: float: Nutation amplitude.

Examples

delta_theta = eval_delta_theta(J,r,xi,q,chi1,chi2,precomputedroots=None)

precession.eval_deltachi(theta1, theta2, q, chi1, chi2)

Eftective spin. Provide either (theta1,theta2,q,chi1,chi2) or (S,varphi,J,r,q,chi1,chi2).

Parameters:

theta1: float, optional (default: None): Angle between orbital angular momentum and primary spin.
theta2: float, optional (default: None): Angle between orbital angular momentum and secondary spin.
S: float, optional (default: None): Magnitude of the total spin.
varphi: float, optional (default: None): Generalized nutation coordinate (Eq 9 in arxiv:1506.03492).
J: float, optional (default: None): Magnitude of the total angular momentum.
r: float, optional (default: None): Binary separation.
q: float, optional (default: None): Mass ratio: 0<=q<=1.
chi1: float, optional (default: None): Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float, optional (default: None): Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

chieff: float: Effective spin.

Examples

chieff = eval_chieff(theta1=None,theta2=None,S=None,varphi=None,J=None,r=None,q=None,chi1=None,chi2=None)

precession.eval_deltachiinf(kappa, chieff, q, chi1, chi2)

precession.eval_deltaphi(deltachi, kappa, r, chieff, q, chi1, chi2, cyclesign=1)

Angle deltaphi between the projections of the two spins onto the orbital plane. By default this is returned in [0,pi]. Setting cyclesign=-1 returns the other half of the precession cycle [-pi,0].

Parameters:

S: float: Magnitude of the total spin.
J: float: Magnitude of the total angular momentum.
r: float: Binary separation.
chieff: float: Effective spin.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
cyclesign: integer, optional (default: -1): Sign (either +1 or -1) to cover the two halves of a precesion cycle.

Returns:

deltaphi: float: Angle between the projections of the two spins onto the orbital plane.

Examples

deltaphi = eval_deltaphi(S,J,r,chieff,q,chi1,chi2,cyclesign=-1)

precession.eval_eta(q)

Symmetric mass ratio eta = m1*m2/(m1+m2)^2 = q/(1+q)^2.

Parameters:

q: float: Mass ratio: 0<=q<=1.

Returns:

eta: float: Symmetric mass ratio 0<=eta<=1/4.

Examples

eta = eval_eta(q)

precession.eval_kappa(theta1=None, theta2=None, deltaphi=None, J=None, r=None, q=None, chi1=None, chi2=None)

Change of dependent variable to regularize the infinite orbital separation limit of the precession-averaged evolution equation.

Parameters:

J: float: Magnitude of the total angular momentum.
r: float: Binary separation.
q: float: Mass ratio: 0<=q<=1.

Returns:

kappa: float: Regularized angular momentum (J^2-L^2)/(2L).

Examples

kappa = eval_kappa(J,r,q)

precession.eval_m1(q)

Mass of the heavier black hole in units of the total mass.

Parameters:

q: float: Mass ratio: 0<=q<=1.

Returns:

m1: float: Mass of the primary (heavier) black hole.

Examples

m1 = eval_m1(q)

precession.eval_m2(q)

Mass of the lighter black hole in units of the total mass.

Parameters:

q: float: Mass ratio: 0<=q<=1.

Returns:

m2: float: Mass of the secondary (lighter) black hole.

Examples

m2 = eval_m2(q)

precession.eval_nutation_freq(kappa, r, chieff, q, chi1, chi2, precomputedroots=None)

Nutation frequency of S as it oscillates from S- to S+ back to S-

Parameters:

J: float: Magnitude of the total angular momentum.
r: float: Binary separation.
xi: float: Effective spin.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
precomputedroots: array, optional (default: None): Pre-computed output of Ssroots for computational efficiency.

Returns:

little_omega: float: Nutation frequency.

Examples

little_omega = eval_little_omega(J,r,xi,q,chi1,chi2,precomputedroots=None)

precession.eval_phiL(deltachi, kappa, r, chieff, q, chi1, chi2, cyclesign=1, precomputedroots=None)

precession.eval_q(m1, m2)

Mass ratio, 0 < q = m2/m1 < 1.

Parameters:

m1: float: Mass of the primary (heavier) black hole.
m2: float: Mass of the secondary (lighter) black hole.

Returns:

q: float: Mass ratio: 0<=q<=1.

Examples

q = eval_q(m1,m2)

precession.eval_r(L=None, u=None, q=None)

Orbital separation of the binary. Valid inputs are either (L,q) or (u,q).

Parameters:

L: float, optional (default: None): Magnitude of the Newtonian orbital angular momentum.
u: float, optional (default: None): Compactified separation 1/(2L).
q: float, optional (default: None): Mass ratio: 0<=q<=1.

Returns:

r: float: Binary separation.

Examples

r = eval_r(L=None,u=None,q=None)

precession.eval_tau(kappa, r, chieff, q, chi1, chi2, precomputedroots=None, return_psiperiod=False, donotnormalize=False)

precession.eval_theta1(deltachi, chieff, q, chi1)

precession.eval_theta12(theta1=None, theta2=None, deltaphi=None, deltachi=None, kappa=None, chieff=None, q=None, chi1=None, chi2=None)

precession.eval_theta2(deltachi, chieff, q, chi2)

precession.eval_thetaL(deltachi, kappa, r, chieff, q)

Angle thetaL betwen orbital angular momentum and total angular momentum.

Parameters:

S: float: Magnitude of the total spin.
J: float: Magnitude of the total angular momentum.
r: float: Binary separation.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

thetaL: float: Angle betwen orbital angular momentum and total angular momentum.

Examples

thetaL = eval_thetaL(S,J,r,q,chi1,chi2)

precession.eval_u(r, q)

Change of independent variable to regularize the infinite orbital separation limit of the precession-averaged evolution equation.

Parameters:

r: float: Binary separation.
q: float: Mass ratio: 0<=q<=1.

Returns:

u: float: Compactified separation 1/(2L).

Examples

u = eval_u(r,q)

precession.eval_v(r)

Newtonian orbital velocity of the binary.

Parameters:

r: float: Binary separation.

Returns:

v: float: Newtonian orbital velocity.

Examples

v = eval_v(r)

precession.gwfrequency_to_pnseparation(theta1, theta2, deltaphi, fGW, q, chi1, chi2, M_msun, PNorder=[0, 1, 1.5, 2])

Convert GW frequency (in Hz) to PN orbital separation (in natural units, c=G=M=1). We use the 2PN expression reported in Eq. 4.13 of Kidder 1995, arxiv:gr-qc/9506022.

Parameters:

theta1: float: Angle between orbital angular momentum and primary spin.
theta2: float: Angle between orbital angular momentum and secondary spin.
deltaphi: float: Angle between the projections of the two spins onto the orbital plane.
f: float: Gravitational-wave frequency in Hz.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
M_msun: float: Total mass of the binary in solar masses.

Returns:

r: float: Binary separation.

Examples

r = gwfrequency_to_pnseparation(theta1,theta2,deltaphi,f,q,chi1,chi2,M_msun)

precession.inspiral(*args, which=None, **kwargs): TODO write docstings. This is the ultimate wrapper the user should call.

precession.inspiral_hybrid(theta1=None, theta2=None, deltaphi=None, deltachi=None, kappa=None, r=None, rswitch=None, u=None, uswitch=None, chieff=None, q=None, chi1=None, chi2=None, requested_outputs=None, **odeint_kwargs)

Perform hybrid inspirals, i.e. evolve the binary at large separation with a pression-averaged evolution and at small separation with an orbit-averaged evolution, properly matching the two. The variables q, chi1, and chi2 must always be provided. The integration range must be specified using either r or u (and not both); provide also uswitch and rswitch consistently. The initial conditions correspond to the binary at either r[0] or u[0]. The vector r or u needs to monotonic increasing or decreasing, allowing to integrate forward and backward in time. If integrating forward in time, perform the precession-average evolution first and then swith to orbit averaging. If integrating backward in time, perform the orbit-average evolution first and then swith to precession averaging. For infinitely large separation in the precession-averaged case, use r=np.inf or u=0. The switch value will not part of the output unless it is also present in the r/u array. The initial conditions must be specified in terms of one an only one of the following: - theta1,theta2, and deltaphi (but note that deltaphi is not necessary if integrating from infinite separation). - J, chieff (only if integrating from finite separations because J otherwise diverges). - kappa, chieff. The desired outputs can be specified with a list e.g. requested_outputs=[‘theta1’,’theta2’,’deltaphi’]. All the available variables are returned by default. These are: [‘theta1’, ‘theta2’, ‘deltaphi’, ‘S’, ‘J’, ‘kappa’, ‘r’, ‘u’, ‘chieff’, ‘q’, ‘chi1’, ‘chi2’].

Parameters:

theta1: float, optional (default: None): Angle between orbital angular momentum and primary spin.
theta2: float, optional (default: None): Angle between orbital angular momentum and secondary spin.
deltaphi: float, optional (default: None): Angle between the projections of the two spins onto the orbital plane.
S: float, optional (default: None): Magnitude of the total spin.
J: float, optional (default: None): Magnitude of the total angular momentum.
kappa: float, optional (default: None): Regularized angular momentum (J^2-L^2)/(2L).
r: float, optional (default: None): Binary separation.
rswitch: float, optional (default: None): Matching separation between the precession- and orbit-averaged chunks.
u: float, optional (default: None): Compactified separation 1/(2L).
uswitch: float, optional (default: None): Matching compactified separation between the precession- and orbit-averaged chunks.
chieff: float, optional (default: None): Effective spin.
q: float, optional (default: None): Mass ratio: 0<=q<=1.
chi1: float, optional (default: None): Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float, optional (default: None): Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
requested_outputs: list, optional (default: None): Set of outputs.

Returns:

outputs: dictionary: Set of outputs.

Examples

outputs = inspiral_hybrid(theta1=None,theta2=None,deltaphi=None,S=None,J=None,kappa=None,r=None,rswitch=None,u=None,uswitch=None,chieff=None,q=None,chi1=None,chi2=None,requested_outputs=None)

precession.inspiral_orbav(theta1=None, theta2=None, deltaphi=None, Lh=None, S1h=None, S2h=None, deltachi=None, kappa=None, r=None, u=None, chieff=None, q=None, chi1=None, chi2=None, cyclesign=1, PNorderpre=[0, 0.5], PNorderrad=[0, 1, 1.5, 2, 2.5, 3, 3.5], requested_outputs=None, **odeint_kwargs)

Perform orbit-averaged inspirals. The variables q, chi1, and chi2 must always be provided. The integration range must be specified using either r or u (and not both). The initial conditions correspond to the binary at either r[0] or u[0]. The vector r or u needs to monotonic increasing or decreasing, allowing to integrate forward and backward in time. Orbit-averaged integration can only be done between finite separations. The initial conditions must be specified in terms of one an only one of the following: - Lh, S1h, and S2h - theta1,theta2, and deltaphi. - J, chieff, and S. - kappa, chieff, and S. The desired outputs can be specified with a list e.g. requested_outputs=[‘theta1’,’theta2’,’deltaphi’]. All the available variables are returned by default. These are: [‘t’, ‘theta1’, ‘theta2’, ‘deltaphi’, ‘S’, ‘Lh’, ‘S1h’, ‘S2h’, ‘J’, ‘kappa’, ‘r’, ‘u’, ‘chieff’, ‘q’, ‘chi1’, ‘chi2’]

Parameters:

theta1: float, optional (default: None): Angle between orbital angular momentum and primary spin.
theta2: float, optional (default: None): Angle between orbital angular momentum and secondary spin.
deltaphi: float, optional (default: None): Angle between the projections of the two spins onto the orbital plane.
S: float, optional (default: None): Magnitude of the total spin.
Lh: array, optional (default: None): Direction of the orbital angular momentum, unit vector.
S1h: array, optional (default: None): Direction of the primary spin, unit vector.
S2h: array, optional (default: None): Direction of the secondary spin, unit vector.
J: float, optional (default: None): Magnitude of the total angular momentum.
kappa: float, optional (default: None): Regularized angular momentum (J^2-L^2)/(2L).
r: float, optional (default: None): Binary separation.
u: float, optional (default: None): Compactified separation 1/(2L).
chieff: float, optional (default: None): Effective spin.
q: float, optional (default: None): Mass ratio: 0<=q<=1.
chi1: float, optional (default: None): Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float, optional (default: None): Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
MISSING: COULD NOT BUILD, optional (default: False): FILL MANUALLY.
requested_outputs: list, optional (default: None): Set of outputs.

Returns:

outputs: dictionary: Set of outputs.

Examples

outputs = inspiral_orbav(theta1=None,theta2=None,deltaphi=None,S=None,Lh=None,S1h=None,S2h=None,J=None,kappa=None,r=None,u=None,chieff=None,q=None,chi1=None,chi2=None,quadrupole_formula=False,requested_outputs=None)

precession.inspiral_precav(theta1=None, theta2=None, deltaphi=None, deltachi=None, kappa=None, r=None, u=None, chieff=None, q=None, chi1=None, chi2=None, requested_outputs=None, **odeint_kwargs)

Perform precession-averaged inspirals. The variables q, chi1, and chi2 must always be provided. The integration range must be specified using either r or u (and not both). The initial conditions correspond to the binary at either r[0] or u[0]. The vector r or u needs to monotonic increasing or decreasing, allowing to integrate forward and backward in time. In addition, integration can be done between finite separations, forward from infinite to finite separation, or backward from finite to infinite separation. For infinity, use r=np.inf or u=0. The initial conditions must be specified in terms of one an only one of the following: - theta1,theta2, and deltaphi (but note that deltaphi is not necessary if integrating from infinite separation). - J, chieff (only if integrating from finite separations because J otherwise diverges). - kappa, chieff. The desired outputs can be specified with a list e.g. requested_outputs=[‘theta1’,’theta2’,’deltaphi’]. All the available variables are returned by default. These are: [‘theta1’, ‘theta2’, ‘deltaphi’, ‘S’, ‘J’, ‘kappa’, ‘r’, ‘u’, ‘chieff’, ‘q’, ‘chi1’, ‘chi2’].

Parameters:

theta1: float, optional (default: None): Angle between orbital angular momentum and primary spin.
theta2: float, optional (default: None): Angle between orbital angular momentum and secondary spin.
deltaphi: float, optional (default: None): Angle between the projections of the two spins onto the orbital plane.
S: float, optional (default: None): Magnitude of the total spin.
J: float, optional (default: None): Magnitude of the total angular momentum.
kappa: float, optional (default: None): Regularized angular momentum (J^2-L^2)/(2L).
r: float, optional (default: None): Binary separation.
u: float, optional (default: None): Compactified separation 1/(2L).
chieff: float, optional (default: None): Effective spin.
q: float, optional (default: None): Mass ratio: 0<=q<=1.
chi1: float, optional (default: None): Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float, optional (default: None): Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
requested_outputs: list, optional (default: None): Set of outputs.

Returns:

outputs: dictionary: Set of outputs.

Examples

outputs = inspiral_precav(theta1=None,theta2=None,deltaphi=None,S=None,J=None,kappa=None,r=None,u=None,chieff=None,q=None,chi1=None,chi2=None,requested_outputs=None)

precession.integrator_orbav(Lhinitial, S1hinitial, S2hinitial, v, q, chi1, chi2, PNorderpre=[0, 0.5], PNorderrad=[0, 1, 1.5, 2, 2.5, 3, 3.5], **odeint_kwargs)

Integration of the systems of ODEs describing orbit-averaged inspirals. Integration is performed in a reference frame where the z axis is along J and L lies in the x-z plane at the initial separation.

Parameters:

Lhinitial: array: Initial direction of the orbital angular momentum, unit vector.
S1hinitial: array: Initial direction of the primary spin, unit vector.
S2hinitial: array: Initial direction of the secondary spin, unit vector.
vinitial: float: Initial value of the newtonian orbital velocity.
vfinal: float: Final value of the newtonian orbital velocity.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
MISSING: COULD NOT BUILD, optional (default: False): FILL MANUALLY.

Returns:

ODEsolution: array of scipy OdeSolution objects: Solution of the ODE. Key method is .sol(t).

Examples

ODEsolution = integrator_orbav(Lhinitial,S1hinitial,S2hinitial,vinitial,vfinal,q,chi1,chi2,quadrupole_formula=False)

precession.integrator_precav(kappainitial, u, chieff, q, chi1, chi2, **odeint_kwargs)

Integration of ODE dkappa/du describing precession-averaged inspirals.

Parameters:

kappainitial: float: Initial value of the regularized momentum kappa.
uinitial: float: Initial value of the compactified separation 1/(2L).
ufinal: float: Final value of the compactified separation 1/(2L).
chieff: float: Effective spin.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

kappa: float: Regularized angular momentum (J^2-L^2)/(2L).

Examples

kappa = integrator_precav(kappainitial,uinitial,ufinal,chieff,q,chi1,chi2)

precession.intertial_ingredients(kappa, r, chieff, q, chi1, chi2)

Numerical prefactors entering the precession frequency.

Parameters:

J: float: Magnitude of the total angular momentum.
r: float: Binary separation.
chieff: float: Effective spin.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

mathcalC0: float: Prefactor in the OmegaL equation.
mathcalCplus: float: Prefactor in the OmegaL equation.
mathcalCminus: float: Prefactor in the OmegaL equation.

Examples

mathcalC0,mathcalCplus,mathcalCminus = frequency_prefactor_old(J,r,chieff,q,chi1,chi2)

precession.inverseaffine(rescaled, low, up)

precession.ismonotonic(vec, which)

Check if an array is monotonic. The parameter which can takes the following values: - < check array is strictly increasing. - <= check array is increasing. - > check array is strictly decreasing. - >= check array is decreasing.

Parameters:

vec: array: Input array.
which: string: Select function behavior.

Returns:

check: boolean: Result

Examples

check = ismonotonic(vec, which):

precession.isotropic_angles(N=1)

precession.kappadiscriminant_coefficients(u, chieff, q, chi1, chi2)

Coefficients of the quintic equation in kappa that defines the spin-orbit resonances.

Parameters:

u: float: Compactified separation 1/(2L).
chieff: float: Effective spin.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

coeff5: float: Coefficient to the x^5 term in polynomial.
coeff4: float: Coefficient to the x^4 term in polynomial.
coeff3: float: Coefficient to the x^3 term in polynomial.
coeff2: float: Coefficient to the x^2 term in polynomial.
coeff1: float: Coefficient to the x^1 term in polynomial.
coeff0: float: Coefficient to the x^0 term in polynomial.

Examples

coeff5,coeff4,coeff3,coeff2,coeff1,coeff0 = kappadiscriminant_coefficients(u,chieff,q,chi1,chi2)

precession.kappalimits(r=None, chieff=None, q=None, chi1=None, chi2=None, enforce=False, **kwargs)

Limits on the magnitude of the total angular momentum. The contraints considered depend on the inputs provided. - If r, q, chi1, and chi2 are provided, the limits are given by J=L+S1+S2. - If r, chieff, q, chi1, and chi2 are provided, the limits are given by the two spin-orbit resonances. The boolean flag enforce allows raising an error in case the inputs are not compatible.

Parameters:

r: float, optional (default: None): Binary separation.
chieff: float, optional (default: None): Effective spin.
q: float, optional (default: None): Mass ratio: 0<=q<=1.
chi1: float, optional (default: None): Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float, optional (default: None): Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
enforce: boolean, optional (default: False): If True raise errors, if False raise warnings.

Returns:

Jmin: float: Minimum value of the total angular momentum J.
Jmax: float: Maximum value of the total angular momentum J.

Examples

Jmin,Jmax = Jlimits(r=None,chieff=None,q=None,chi1=None,chi2=None,enforce=False)

precession.kappalimits_geometrical(r, q, chi1, chi2)

precession.kapparescaling(kappatilde, r, chieff, q, chi1, chi2)

precession.kapparesonances(r, chieff, q, chi1, chi2, tol=0.0001)

Regularized angular momentum of the two spin-orbit resonances. The resonances minimizes and maximizes kappa for a given value of chieff. The minimum corresponds to deltaphi=pi and the maximum corresponds to deltaphi=0. Examples ——– kappamin,kappamax = kapparesonances(u,chieff,q,chi1,chi2) Parameters ———- u: float

Compactified separation 1/(2L).

chieff: float: Effective spin.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

tol: FIX ME Returns ——- kappamin: float

Minimum value of the regularized angular momentum kappa.

kappamax: float: Maximum value of the regularized angular momentum kappa.

precession.limits_check(S=None, J=None, r=None, chieff=None, q=None, chi1=None, chi2=None)

Check if the inputs are consistent with the geometrical constraints.

Parameters:

S: float: Magnitude of the total spin.
J: float, optional: Magnitude of the total angular momentum.
r: float, optional: Binary separation.
chieff: float, optional: Effective spin
q: float: Mass ratio: 0 <= q <= 1.
chi1: float, optional: Dimensionless spin of the primary black hole: 0 <= chi1 <= 1.
chi2: float, optional: Dimensionless spin of the secondary black hole: 0 <= chi1 <= 1.

Returns:

check: bool: True if the given parameters are compatible with each other, false if not.

precession.masses(q)

Masses of the two black holes in units of the total mass.

Parameters:

q: float: Mass ratio: 0<=q<=1.

Returns:

m1: float: Mass of the primary (heavier) black hole.
m2: float: Mass of the secondary (lighter) black hole.

Examples

m1,m2 = masses(q)

precession.morphology(kappa, r, chieff, q, chi1, chi2, simpler=False, precomputedroots=None)

Evaluate the spin morphology and return L0 for librating about deltaphi=0, Lpi for librating about deltaphi=pi, C- for circulating from deltaphi=pi to deltaphi=0, and C+ for circulating from deltaphi=0 to deltaphi=pi. If simpler=True, do not distinguish between the two circulating morphologies and return C for both.

Parameters:

J: float: Magnitude of the total angular momentum.
r: float: Binary separation.
chieff: float: Effective spin.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
simpler: boolean, optional (default: False): If True simplifies output.

Returns:

morph: string: Spin morphology.

Examples

morph = morphology(J,r,chieff,q,chi1,chi2,simpler = False)

precession.norm_nested(x)

Norm of 2D array of shape (N,3) along last axis.

Parameters:

xarray: Input array.

Returns:

narray: Norm of the input arrays.

Examples

n = norm_nested(x)

precession.normalize_nested(x)

Normalize 2D array of shape (N,3) along last axis.

Parameters:

xarray: Input array.

Returns:

yarray: Normalized array.

Examples

y = normalize_nested(x)

precession.omegasq_aligned(r, q, chi1, chi2, which)

Squared oscillation frequency of a given perturbed aligned-spin binary. The flag which needs to be set to uu for up-up, ud for up-down, du for down-up or dd for down-down where the term before (after) the hyphen refers to the spin of the heavier (lighter) black hole.

Parameters:

r: float: Binary separation.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
which: string: Select function behavior.

Returns:

omegasq: float: Squared frequency.

Examples

omegasq = omegasq_aligned(r,q,chi1,chi2,which)

precession.pnseparation_to_gwfrequency(theta1, theta2, deltaphi, r, q, chi1, chi2, M_msun, PNorder=[0, 1, 1.5, 2])

Convert PN orbital separation in natural units (c=G=M=1) to GW frequency in Hz. We use the 2PN expression reported in Eq. 4.5 of Kidder 1995, arxiv:gr-qc/9506022.

Parameters:

theta1: float: Angle between orbital angular momentum and primary spin.
theta2: float: Angle between orbital angular momentum and secondary spin.
deltaphi: float: Angle between the projections of the two spins onto the orbital plane.
f: float: Gravitational-wave frequency in Hz.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
M_msun: float: Total mass of the binary in solar masses.

Returns:

r: float: Binary separation.

Examples

r = pnseparation_to_gwfrequency(theta1,theta2,deltaphi,f,q,chi1,chi2,M_msun)

precession.precession_average(kappa, r, chieff, q, chi1, chi2, func, *args, method='quadrature', Nsamples=10000.0)

Average a generic function over a precession cycle. The function needs to have call: func(S, *args). Keywords arguments are not supported.

There are integration methods implemented: - method=’quadrature’ uses scipy.integrate.quad. This is set by default and should be preferred. - method=’montecarlo’ samples t(S) and approximate the integral with a Monte Carlo sum. The number of samples can be specifed by Nsamples.

Parameters:

J: float: Magnitude of the total angular momentum.
r: float: Binary separation.
chieff: float: Effective spin.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
func: function: Function to precession-average.
*args: tuple: Extra arguments to pass to func.
method: string (default: ‘quadrature’): Either ‘quadrature’ or ‘montecarlo’
Nsamples: integer (default: 1e4): Number of Monte Carlo samples.

Returns:

func_av: float: Precession averaged value of func.

Examples

func_av = precession_average(J,r,chieff,q,chi1,chi2,func,*args,method=’quadrature’,Nsamples=1e4)

precession.reminantspindirection(theta1, theta2, deltaphi, rplunge, q, chi1, chi2): Angle between the spin of the remnant and the binary angular momentum, assuming that the spins stays in the direction of the total angular momentu ‘at plunge’

precession.remnantkick(theta1, theta2, deltaphi, q, chi1, chi2, kms=False, maxphase=False, superkick=True, hangupkick=True, crosskick=True, full_output=False)

Estimate the kick of the merger remnant. We collect various numerical-relativity results, as described in Gerosa and Kesden 2016. Flags let you switch the various contributions on and off (all on by default): superkicks (Gonzalez et al. 2007a; Campanelli et al. 2007), hang-up kicks (Lousto & Zlochower 2011), cross-kicks (Lousto & Zlochower 2013). The orbital-plane kick components are implemented as described in Kesden et al. 2010a. The final kick depends on the orbital phase at merger. By default, this is assumed to be uniformly distributed in [0,2pi]. The maximum kick is realized for Theta=0 and can be computed with the optional argument maxphase. The final kick is returned in geometrical units (i.e. vkick/c) by default, and converted to km/s if kms=True. This formula has to be applied close to merger, where numerical relativity simulations are available. You should do a PN evolution to transfer binaries at r~10M.

Parameters:

theta1: float: Angle between orbital angular momentum and primary spin.
theta2: float: Angle between orbital angular momentum and secondary spin.
deltaphi: float: Angle between the projections of the two spins onto the orbital plane.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
kms: boolean, optional (default: False): Return velocities in km/s.
maxphase: boolean, optional (default: False): Maximize over orbital phase at merger.
superkick: boolean, optional (default: True): Switch kick terms on and off.
hangupkick: boolean, optional (default: True): Switch kick terms on and off.
crosskick: boolean, optional (default: True): Switch kick terms on and off.
full_output: boolean, optional (default: False): Return additional outputs.

Returns:

vk: float: Kick of the black-hole remnant (magnitude).
Other parameters

vk_array: array: Kick of the black-hole remnant (in a frame aligned with L).

Examples

vk = remnantkick(theta1,theta2,deltaphi,q,chi1,chi2,kms=False,maxphase=False,superkick=True,hangupkick=True,crosskick=True,full_output=False) vk,vk_array = remnantkick(theta1,theta2,deltaphi,q,chi1,chi2,kms=False,maxphase=False,superkick=True,hangupkick=True,crosskick=True,full_output=True)

precession.remnantmass(theta1, theta2, q, chi1, chi2)

Estimate the final mass of the post-merger renmant. We implement the fitting formula to numerical relativity simulations by Barausse Morozova Rezzolla 2012. This formula has to be applied close to merger, where numerical relativity simulations are available. You should do a PN evolution to transfer binaries to r~10M.

Parameters:

theta1: float: Angle between orbital angular momentum and primary spin.
theta2: float: Angle between orbital angular momentum and secondary spin.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

mfin: float: Mass of the black-hole remnant.

Examples

mfin = remnantmass(theta1,theta2,q,chi1,chi2)

precession.remnantspin(theta1, theta2, deltaphi, q, chi1, chi2, which='HBR16_34corr')

Estimate the final spin of the post-merger renmant. We implement the fitting formula to numerical relativity simulations by Barausse and Rezzolla 2009 and Hofmann, Barausse and Rezzolla 2016. This can be selected by the keywork ` which, see those references for details. By default this returns the Hofmann+ expression with nM=3, nJ=4 and corrections for the effective angles (HBR16_34corr). This formula has to be applied close to merger, where numerical relativity simulations are available. You should do a PN evolution to transfer binaries at r~10M.

Parameters:

theta1: float: Angle between orbital angular momentum and primary spin.
theta2: float: Angle between orbital angular momentum and secondary spin.
deltaphi: float: Angle between the projections of the two spins onto the orbital plane.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
which: string, optional (default: ‘HBR16_34corr’): Select function behavior.

Returns:

chifin: float: Spin of the black-hole remnant.

Examples

chifin = remnantspin(theta1,theta2,deltaphi,q,chi1,chi2,which=’HBR16_34corr’)

precession.rhs_orbav(allvars, v, q, m1, m2, eta, chi1, chi2, S1, S2, PNorderpre=[0, 0.5], PNorderrad=[0, 1, 1.5, 2, 2.5, 3, 3.5])

Right-hand side of the systems of ODEs describing orbit-averaged inspiral. The equations are reported in Sec 4A of Gerosa and Kesden, arXiv:1605.01067. The format is d[allvars]/dv=RHS where allvars=[Lhx,Lhy,Lhz,S1hx,S1hy,S1hz,S2hx,S2hy,S2hz,t], h indicates unite vectors, v is the orbital velocity, and t is time. This is an internal function used by the ODE integrator and is not array-compatible.

Parameters:

v: float: Newtonian orbital velocity.
allvars: array: Packed ODE input variables.
q: float: Mass ratio: 0<=q<=1.
m1: float: Mass of the primary (heavier) black hole.
m2: float: Mass of the secondary (lighter) black hole.
eta: float: Symmetric mass ratio 0<=eta<=1/4.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.
S1: float: Magnitude of the primary spin.
S2: float: Magnitude of the secondary spin.
MISSING: COULD NOT BUILD, optional (default: False): FILL MANUALLY.

Returns:

RHS: float: Right-hand side.

Examples

RHS = rhs_orbav(v,allvars,q,m1,m2,eta,chi1,chi2,S1,S2,quadrupole_formula=False)

precession.rhs_precav(kappa, u, chieff, q, chi1, chi2)

Right-hand side of the dkappa/du ODE describing precession-averaged inspiral. This is an internal function used by the ODE integrator and is not array-compatible. It is equivalent to Ssav and Ssavinf and it has been re-written for optimization purposes.

Parameters:

kappa: float: Regularized angular momentum (J^2-L^2)/(2L).
u: float: Compactified separation 1/(2L).
chieff: float: Effective spin.
q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

RHS: float: Right-hand side.

Examples

RHS = rhs_precav(kappa,u,chieff,q,chi1,chi2)

precession.roots_vec(p)

Locate roots of polynomial using a vectorized version of numpy.roots. Equivalent to [np.roots(x) for x in p]. Credits: stackoverflow user pv, see https://stackoverflow.com/a/35853977

Parameters:

p: array: Polynomial coefficients.

Returns:

roots: array: Polynomial roots.

Methods

``roots = roots_vec(p)``

precession.rotate_nested(vec, align_zaxis, align_xzplane): Rotate a given vector vec to a frame such that the vector align_zaxis lies along z and the vector align_xzplane lies in the xz plane.

precession.rupdown(q, chi1, chi2)

The critical separations r_ud+/- marking the region of the up-down precessional instability.

Parameters:

q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

rudp: float: Outer orbital separation in the up-down instability.
rudm: float: Inner orbital separation in the up-down instability.

Examples

rudp,rudm = rupdown(q,chi1,chi2)

precession.sample_unitsphere(N=1)

Sample points uniformly on a sphere of unit radius. Returns array of shape (N,3).

Parameters:

N: integer, optional (default: 1): Number of samples.

Returns:

vec: array: Vector in Cartesian coomponents.

Examples

vec = sample_unitsphere(N = 1)

precession.scalar_nested(k, x)

Nested scalar product between a 1D and a 2D array.

Parameters:

kfloat: Input scalar.
xarray: Input array.

Returns:

yarray: Scalar product array.

Examples

y = scalar_nested(k, x)

precession.spinmags(q, chi1, chi2)

Spins of the black holes in units of the total mass.

Parameters:

q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

S1: float: Magnitude of the primary spin.
S2: float: Magnitude of the secondary spin.

Examples

S1,S2 = spinmags(q,chi1,chi2)

precession.tiler(thing, shaper)

precession.tofdeltachi(deltachi, kappa, r, chieff, q, chi1, chi2, cyclesign=1, precomputedroots=None)

precession.updown_endpoint(q, chi1, chi2)

precession.vectors_to_Jframe(Lvec, S1vec, S2vec)

precession.vectors_to_Lframe(Lvec, S1vec, S2vec)

precession.vectors_to_angles(Lvec, S1vec, S2vec)

Convert cartesian vectors (L,S1,S2) into angles (theta1,theta2,deltaphi). The convention for the sign of deltaphi is given in Eq. (2d) of arxiv:1506.03492.

Parameters:

Lvec: array: Cartesian vector of the orbital angular momentum.
S1vec: array: Cartesian vector of the primary spin.
S2vec: array: Cartesian vector of the secondary spin.

Returns:

theta1: float: Angle between orbital angular momentum and primary spin.
theta2: float: Angle between orbital angular momentum and secondary spin.
deltaphi: float: Angle between the projections of the two spins onto the orbital plane.

Examples

theta1,theta2,deltaphi = vectors_to_angles(Lvec,S1vec,S2vec)

precession.vectors_to_conserved(Lvec, S1vec, S2vec, q, full_output=False)

precession.widenutation_condition(r, q, chi1, chi2)

precession.widenutation_separation(q, chi1, chi2)

The critical separation r_wide below which the binary component with smaller dimensionless spin may undergo wide nutations.

Parameters:

q: float: Mass ratio: 0<=q<=1.
chi1: float: Dimensionless spin of the primary (heavier) black hole: 0<=chi1<=1.
chi2: float: Dimensionless spin of the secondary (lighter) black hole: 0<=chi2<=1.

Returns:

r_wide: float: Orbital separation where wide nutations becomes possible.

Examples

r_wide = widenutation(q,chi1,chi2)

precession.wraproots(coefficientfunction, *args, **kwargs)

Find roots of a polynomial given coefficients, ordered according to their real part. Complex roots are masked with nans. This is essentially a wrapper of numpy.roots.

Parameters:

coefficientfunction: callable: Function returning the polynomial coefficients ordered from highest to lowest degree.
*args, **kwargs:: Parameters of coefficientfunction.

Returns:

sols: array: Roots of the polynomial.

Examples

sols = precession.wraproots(coefficientfunction, *args, **kwargs)