lalsuite 7.26.2.dev20251210__cp312-cp312-macosx_12_0_arm64.whl

lalinference/imrtgr/nrutils.py

@@ -0,0 +1,1366 @@
+"""
+Various fitting formulas provided by numerical relativity
+
+Archisman Ghosh, Nathan K. Johnson-McDaniel, P. Ajith, 2015-04-09
+"""
+
+import numpy as np
+import scipy.optimize as so
+try:
+    import lal
+except ImportError:
+    print('Cannot import lal SWIG bindings')
+
+# Functions to check that input values are physical
+
+def _check_m(m1,m2):
+    if np.any(m1<=0):
+        raise ValueError("m1 has to be positive")
+    if np.any(m2<=0):
+        raise ValueError("m2 has to be positive")
+
+def _check_chi(chi1, chi2):
+    if np.any(chi1>1):
+      raise ValueError("chi1 has to be <= 1")
+    if np.any(chi2>1):
+      raise ValueError("chi2 has to be <= 1")
+    if np.any(chi1<0):
+      raise ValueError("chi1 has to be nonnegative")
+    if np.any(chi2<0):
+      raise ValueError("chi2 has to be nonnegative")
+
+def _check_chi_aligned(chi1, chi2):
+    if np.any(abs(chi1)>1):
+      raise ValueError("chi1 has to be <= 1")
+    if np.any(abs(chi2)>1):
+      raise ValueError("chi2 has to be <= 1")
+
+def _check_mchi(m1,m2,chi1,chi2):
+    _check_m(m1,m2)
+    _check_chi(chi1,chi2)
+
+def _check_mchi_aligned(m1,m2,chi1,chi2):
+    _check_m(m1,m2)
+    _check_chi_aligned(chi1,chi2)
+
+###########################
+# Final mass and spin fits
+###########################
+
+# list of final mass and spin fit names
+class bbh_final_state_fits:
+    pan2011   = "Pan2011"   # Pan et al.             [Phys Rev D 84, 124052 (2011)] (mass+spin, non-spinning)
+    hlz2014   = "HLZ2014"   # Healy et al.           [Phys Rev D 90, 104004 (2014)] (mass+spin, aligned)
+    phenD     = "PhenomD"   # Husa et al.            [Phys Rev D 93, 044006 (2016)] (mass+spin, aligned)
+    uib2016v1 = "UIB2016v1" # Jimenez-Forteza et al. [arXiv:1611.00332v1]           (mass+spin, aligned)
+    uib2016   = "UIB2016"   # Jimenez-Forteza et al. [LIGO-P1600270-v4 / arXiv:1611.00332v2]           (mass+spin, aligned)
+    hbr2016   = "HBR2016"   # Hofmann et al.         [ApJL 825:L19 (2016)]          (spin only, precessing)
+    hl2016    = "HL2016"    # Healy and Lousto       [arXiv:1610.09713]             (mass+spin, aligned)
+
+# list of Kerr truncation behaviours
+class bbh_Kerr_trunc_opts:
+    trunc        = "TRUNCATE"       # truncate fit value to 1.0, with an info message
+    trunc_silent = "TRUNCATESILENT" # truncate fit value to 1.0, without info message
+    keep         = "KEEP"           # keep fit value, even if superextremal, but still give the info message
+    ign          = "IGNORE"         # keep fit value, even if superextremal, without info message
+    err          = "ERROR"          # abort with an error if fit value is superextremal
+
+# Function to truncate final spins at Kerr limit (with various options)
+
+def _truncate_at_Kerr_limit(chif, behavior, fitname="this"):
+    if behavior not in list(bbh_Kerr_trunc_opts.__dict__.values()):
+      raise ValueError("Unknown user option '%s' for Kerr truncation behavior." % behavior)
+    if behavior!=bbh_Kerr_trunc_opts.ign and np.any(abs(chif)>1.0):
+      if isinstance(chif,(list,np.ndarray)):
+        idx_over = np.where(abs(chif)>1.0)
+        if behavior==bbh_Kerr_trunc_opts.trunc or behavior==bbh_Kerr_trunc_opts.trunc_silent:
+          chif_trunc = np.sign(chif[idx_over])*1.0
+          if behavior==bbh_Kerr_trunc_opts.trunc:
+            print("Truncating %d excessive chif values from %s fit to Kerr limit of +-1.0" % (np.size(idx_over), fitname))
+          chif[idx_over] = chif_trunc
+        elif behavior==bbh_Kerr_trunc_opts.keep:
+          print("Note: %s fit predicts %d chif values in excess of the Kerr limit." % (fitname, np.size(idx_over)))
+        elif behavior==bbh_Kerr_trunc_opts.err:
+          raise ValueError("%s fit predicts %d chif values in excess of the Kerr limit." % (fitname, np.size(idx_over)))
+      else:
+        if behavior==bbh_Kerr_trunc_opts.trunc or behavior==bbh_Kerr_trunc_opts.trunc_silent:
+          chif_trunc = np.sign(chif)*1.0
+          if behavior==bbh_Kerr_trunc_opts.trunc:
+            print("Truncating excessive chif of %f from %s fit to Kerr limit of %f" % (chif, fitname, chif_trunc))
+          chif = chif_trunc
+        elif behavior==bbh_Kerr_trunc_opts.keep:
+          print("Note: %s fit predicts chif of %f in excess of the Kerr limit." % (fitname, chif))
+        elif behavior==bbh_Kerr_trunc_opts.err:
+          raise ValueError("%s fit predicts chif of %f in excess of the Kerr limit." % (fitname, chif))
+    return chif
+
+# Final mass and spin functions
+
+def bbh_final_mass_non_spinning_Panetal(m1, m2):
+    """
+    Calculate the mass of the final BH resulting from the merger of two non-spinning black holes using eqn. 29a of from Pan et al, Phys Rev D 84, 124052 (2011).
+
+    Parameters
+    ----------
+    m1, m2 : component masses
+
+    Returns
+    ------
+    final mass, mf
+    """
+    m1 = np.array(m1,dtype=np.float64)
+    m2 = np.array(m2,dtype=np.float64)
+
+    m = m1 + m2
+    eta = m1*m2/(m1+m2)**2.
+    return m*(1. + (np.sqrt(8./9.)-1.)*eta - 0.4333*(eta**2.) - (0.4392*(eta**3)))
+
+def bbh_final_spin_non_spinning_Panetal(m1, m2):
+    """
+    Calculate the spin of the final BH resulting from the merger of two non-spinning black holes using eqn. 29b of Pan et al, Phys Rev D 84, 124052 (2011).
+
+    Parameters
+    ----------
+    m1, m2 : component masses
+
+    Returns
+    ------
+    final dimensionless spin, chif
+    """
+    m1 = np.array(m1,dtype=np.float64)
+    m2 = np.array(m2,dtype=np.float64)
+
+    eta = m1*m2/(m1+m2)**2.
+    return np.sqrt(12.)*eta - 3.871*(eta**2.) + 4.028*(eta**3)
+
+def calc_isco_radius(a):
+    """
+    Calculate the ISCO radius of a Kerr BH as a function of the Kerr parameter using eqns. 2.5 and 2.8 from Ori and Thorne, Phys Rev D 62, 24022 (2000)
+
+    Parameters
+    ----------
+    a : Kerr parameter
+
+    Returns
+    -------
+    ISCO radius
+    """
+
+    a = np.minimum(np.array(a),1.) # Only consider a <=1, to avoid numerical problems
+
+    # Ref. Eq. (2.5) of Ori, Thorne Phys Rev D 62 124022 (2000)
+    z1 = 1.+(1.-a**2.)**(1./3)*((1.+a)**(1./3) + (1.-a)**(1./3))
+    z2 = np.sqrt(3.*a**2 + z1**2)
+    a_sign = np.sign(a)
+    return 3+z2 - np.sqrt((3.-z1)*(3.+z1+2.*z2))*a_sign
+
+
+def _RIT_setup(m1, m2, chi1, chi2):
+    """ Internal function to compute the combinations of masses and spins that are used in the RIT fits """
+
+    _check_mchi_aligned(m1, m2, chi1, chi2)
+
+    m = m1+m2
+    eta = m1*m2/m/m
+    delta_m = (m1 - m2)/m
+
+    S = (m1*m1*chi1 + m2*m2*chi2)/m**2 # symmetric spin (dimensionless -- called \tilde{S} in the paper)
+    Delta = (m2*chi2 - m1*chi1)/m # antisymmetric spin (dimensionless -- called tilde{Delta} in the paper
+
+    return eta, delta_m, S, Delta
+
+def _RIT_symm_express(eta, delta_m, S, Delta, coeffs):
+    """
+    Internal function to return the basic even-in-interchange-of-particles expression used in the RIT fits for the final mass, final spin, and peak luminosity
+
+    The coefficients in the expression are passed as a vector as [0 1 2a 2b 2c 2d 3a 3b 3c 3d 4a 4b 4c 4d 4e 4f 4g 4h 4i] (giving the subscripts).
+    """
+
+    S2 = S*S
+
+    dm2 = delta_m*delta_m
+
+    Deltadm = Delta*delta_m
+
+    Delta2 = Delta*Delta
+
+    return 16.*eta*eta*(coeffs[0] + coeffs[1]*S + coeffs[2]*Deltadm + coeffs[3]*S2 + coeffs[4]*Delta2 \
+        + coeffs[5]*dm2 + coeffs[6]*Deltadm*S + coeffs[7]*S*Delta2 + coeffs[8]*S2*S \
+        + coeffs[9]*S*dm2 + coeffs[10]*Deltadm*S2 + coeffs[11]*Delta2*Deltadm \
+        + coeffs[12]*Delta2*Delta2 + coeffs[13]*S2*S2 + coeffs[14]*Delta2*S2 + coeffs[15]*dm2*dm2 + coeffs[16]*Deltadm*dm2 \
+        + coeffs[17]*Delta2*dm2 + coeffs[18]*S2*dm2)
+
+def _final_spin_diff_Healyetal(a_f, eta, delta_m, S, Delta, version):
+    """ Internal function: the final spin with the Healy et al. fits is determined by minimizing this function """
+
+    # calculate ISCO radius
+    r_isco = calc_isco_radius(a_f)
+
+    # angular momentum at ISCO -- Eq.(2.8) of Ori, Thorne Phys Rev D 62 124022 (2000)
+    J_isco = (3*np.sqrt(r_isco)-2*a_f)*2./np.sqrt(3*r_isco)
+
+    # fitting coefficients
+    if version == "2014": # From Table XI of Healy et al Phys Rev D 90, 104004 (2014) [fourth order fits]
+        L0  = 0.686710
+        L1  = 0.613247
+        L2a = -0.145427
+        L2b = -0.115689
+        L2c = -0.005254
+        L2d = 0.801838
+        L3a = -0.073839
+        L3b = 0.004759
+        L3c = -0.078377
+        L3d = 1.585809
+        L4a = -0.003050
+        L4b = -0.002968
+        L4c = 0.004364
+        L4d = -0.047204
+        L4e = -0.053099
+        L4f = 0.953458
+        L4g = -0.067998
+        L4h = 0.001629
+        L4i = -0.066693
+    elif version == "2016": # From Table III of Healy and Lousto arXiv:1610.09713 (values taken from Matlab implementation and thus slightly more precise than the ones in the table)
+        L0  = 0.686732132
+        L1  = 0.613284976
+        L2a = -0.148530075
+        L2b = -0.113826318
+        L2c = -0.00323995784
+        L2d = 0.798011319
+        L3a = -0.0687823713
+        L3b = 0.00129103641
+        L3c = -0.0780143929
+        L3d = 1.55728564
+        L4a = -0.00571010557
+        L4b = 0.005919799
+        L4c = -0.00170575554
+        L4d = -0.0588819084
+        L4e = -0.0101866693
+        L4f = 0.964444768
+        L4g = -0.11088507
+        L4h = -0.00682082169
+        L4i = -0.0816482139
+    else:
+        raise ValueError('Unknown version--should be either "2014" or "2016".')
+
+    dm2 = delta_m*delta_m
+    dm4 = dm2*dm2
+    dm6 = dm4*dm2
+
+    a_f_new = _RIT_symm_express(eta, delta_m, S, Delta, [L0, L1, L2a, L2b, L2c, L2d, L3a, L3b, L3c, L3d, L4a, L4b, L4c, L4d, L4e, L4f, L4g, L4h, L4i]) \
+        + S*(1. + 8.*eta)*dm4 + eta*J_isco*dm6
+
+    return abs(a_f-a_f_new)
+
+def bbh_final_spin_non_precessing_Healyetal(m1, m2, chi1, chi2, version="2014"):
+    """
+    Calculate the spin of the final BH resulting from the merger of two black holes with
+    non-precessing spins using fit from Healy et al Phys Rev D 90, 104004 (2014) (version == "2014")
+    or the small update from Healy and Lousto arXiv:1610.09713 (version == "2016")
+
+    Parameters
+    ----------
+    m1, m2 : component masses
+    chi1, chi2 : dimensionless spins of two BHs
+
+    Returns
+    -------
+    dimensionless final spin, chif
+    """
+    m1 = np.array(m1,dtype=np.float64)
+    m2 = np.array(m2,dtype=np.float64)
+    chi1 = np.array(chi1,dtype=np.float64)
+    chi2 = np.array(chi2,dtype=np.float64)
+    eta, delta_m, S, Delta = _RIT_setup(m1, m2, chi1, chi2)
+    def func(eta, delta_m, S, Delta):
+        return so.leastsq(_final_spin_diff_Healyetal, 0., args=(eta, delta_m, S, Delta, version))[0][0]
+    chif = np.vectorize(func)(eta, delta_m, S, Delta)
+    return chif.item() if np.ndim(chif) == 0 else chif
+
+def bbh_final_mass_non_precessing_Healyetal(m1, m2, chi1, chi2, version="2014", chif=None):
+    """
+    Calculate the mass of the final BH resulting from the merger of two black holes with non-precessing spins using fit from Healy et al Phys Rev D 90, 104004 (2014) (version == "2014") or the small update from Healy and Lousto arXiv:1610.09713 (version == "2016")
+
+    Parameters
+    ----------
+    m1, m2 : component masses
+    chi1, chi2 : dimensionless spins of two BHs
+    chif: final spin (optional), if already calculated
+
+    Returns
+    -------
+    final mass, mf
+    """
+    m1 = np.array(m1,dtype=np.float64)
+    m2 = np.array(m2,dtype=np.float64)
+    chi1 = np.array(chi1,dtype=np.float64)
+    chi2 = np.array(chi2,dtype=np.float64)
+
+    eta, delta_m, S, Delta = _RIT_setup(m1, m2, chi1, chi2)
+
+    if chif is None:
+        chif = bbh_final_spin_non_precessing_Healyetal(m1, m2, chi1, chi2, version)
+    else:
+        chif = np.array(chif)
+
+    # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+    # now compute the final mass
+    # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+    r_isco = calc_isco_radius(chif)
+
+    # fitting coefficients
+    if version == "2014": # From Table XI of Healy et al Phys Rev D 90, 104004 (2014) [fourth order fits]
+        M0  = 0.951507
+        K1  = -0.051379
+        K2a = -0.004804
+        K2b = -0.054522
+        K2c = -0.000022
+        K2d = 1.995246
+        K3a = 0.007064
+        K3b = -0.017599
+        K3c = -0.119175
+        K3d = 0.025000
+        K4a = -0.068981
+        K4b = -0.011383
+        K4c = -0.002284
+        K4d = -0.165658
+        K4e = 0.019403
+        K4f = 2.980990
+        K4g = 0.020250
+        K4h = -0.004091
+        K4i = 0.078441
+    elif version == "2016": # From Table III of Healy and Lousto arXiv:1610.09713 (values taken from Matlab implementation and thus slightly more precise than the ones in the table)
+        M0  = 0.951659087
+        K1  = -0.0511301363
+        K2a = -0.00569897591
+        K2b = -0.0580644933
+        K2c = -0.00186732281
+        K2d = 1.99570464
+        K3a = 0.00499137602
+        K3b = -0.00923776244
+        K3c = -0.120577082
+        K3d = 0.0164168385
+        K4a = -0.0607207285
+        K4b = -0.00179828653
+        K4c = 0.000654388173
+        K4d = -0.156625642
+        K4e = 0.0103033606
+        K4f = 2.97872857
+        K4g = 0.00790433045
+        K4h = 0.000631241195
+        K4i = 0.0844776942
+    else:
+        raise ValueError('Unknown version--should be either "2014" or "2016".')
+
+    # binding energy at ISCO -- Eq.(2.7) of Ori, Thorne Phys Rev D 62 124022 (2000)
+    E_isco = (1. - 2./r_isco + chif/r_isco**1.5)/np.sqrt(1. - 3./r_isco + 2.*chif/r_isco**1.5)
+
+    dm2 = delta_m*delta_m
+    dm6 = dm2*dm2*dm2
+
+    m = m1 + m2
+
+    # final mass -- Eq. (14) of Healy et al Phys Rev D 90, 104004 (2014)
+    mf = _RIT_symm_express(eta, delta_m, S, Delta, [M0, K1, K2a, K2b, K2c, K2d, K3a, K3b, K3c, K3d, K4a, K4b, K4c, K4d, K4e, K4f, K4g, K4h, K4i]) \
+        + (1+eta*(E_isco+11.))*dm6
+
+    return mf*m
+
+def bbh_final_spin_projected_spin_Healyetal(m1, m2, chi1, chi2, tilt1, tilt2):
+    """
+    wrapper to bbh_final_spin_projected_spins() for backwards compatibility
+    """
+    return bbh_final_spin_projected_spins(m1, m2, chi1, chi2, tilt1, tilt2, "HLZ2014")
+
+def bbh_final_mass_projected_spin_Healyetal(m1, m2, chi1, chi2, tilt1, tilt2, chif=None):
+    """
+    wrapper to bbh_final_mass_projected_spins() for backwards compatibility
+    """
+    return bbh_final_mass_projected_spins(m1, m2, chi1, chi2, tilt1, tilt2, "HLZ2014", chif)
+
+def bbh_final_spin_precessing_Healyetal_extension_Minit(m1, m2, chi1, chi2, tilt1, tilt2, phi12):
+   """
+   wrapper to bbh_final_spin_precessing() for backwards compatibility
+   """
+   return bbh_final_spin_precessing(m1, m2, chi1, chi2, tilt1, tilt2, phi12, "HLZ2014")
+
+def bbh_final_mass_projected_spins(m1, m2, chi1, chi2, tilt1, tilt2, fitname, chif=None):
+    """
+    Calculate the mass of the final BH resulting from the merger of two black holes,
+    only using the projected spins along the total angular momentum
+    and some aligned-spin fit from the literature
+
+    Parameters
+    ----------
+    m1, m2 : component masses
+    chi1, chi2 : dimensionless spins of two BHs
+    tilt1, tilt2 : tilts (in radians) in the new spin convention
+    fitname: fit selection currently supports Pan2011 (non-spinning), HLZ2014, PhenomD, UIB2016, HL2016
+    chif: final spin (optional, only used for HLZ2014 and HL2016), if already calculated
+
+    Returns
+    -------
+    final mass, mf
+    """
+
+    m1    = np.array(m1,dtype=np.float64)
+    m2    = np.array(m2,dtype=np.float64)
+    chi1  = np.array(chi1,dtype=np.float64)
+    chi2  = np.array(chi2,dtype=np.float64)
+    tilt1 = np.array(tilt1,dtype=np.float64)
+    tilt2 = np.array(tilt2,dtype=np.float64)
+    if chif is not None:
+       chif = np.array(chif,dtype=np.float64)
+
+    _check_mchi(m1,m2,chi1,chi2) # Check that inputs are physical
+
+    chi1proj = chi1*np.cos(tilt1)
+    chi2proj = chi2*np.cos(tilt2)
+
+    if fitname==bbh_final_state_fits.pan2011:
+       if np.any(chi1!=0) or np.any(chi2!=0) or np.any(tilt1!=0) or np.any(tilt2!=0):
+          print("Note: Pan2011 fit does not use spins.")
+       if chif is not None:
+          print("Note: Precomputed chif not used by this fit.")
+       mf = bbh_final_mass_non_spinning_Panetal(m1, m2)
+    elif fitname==bbh_final_state_fits.hlz2014:
+       mf = bbh_final_mass_non_precessing_Healyetal(m1, m2, chi1proj, chi2proj, version="2014", chif=chif)
+    elif fitname==bbh_final_state_fits.hl2016:
+       mf = bbh_final_mass_non_precessing_Healyetal(m1, m2, chi1proj, chi2proj, version="2016", chif=chif)
+    elif fitname==bbh_final_state_fits.phenD:
+       if chif is not None:
+          print("Note: Precomputed chif not used by this fit.")
+       mf = bbh_final_mass_non_precessing_Husaetal(m1, m2, chi1proj, chi2proj)
+    elif fitname==bbh_final_state_fits.uib2016:
+       if chif is not None:
+          print("Note: Precomputed chif not used by this fit.")
+       mf = bbh_final_mass_non_precessing_UIB2016(m1, m2, chi1proj, chi2proj, version="v2")
+    elif fitname==bbh_final_state_fits.uib2016v1:
+       if chif is not None:
+          print("Note: Precomputed chif not used by this fit.")
+       mf = bbh_final_mass_non_precessing_UIB2016(m1, m2, chi1proj, chi2proj, version="v1")
+    else:
+       raise ValueError("Unrecognized fit name.")
+
+    return mf
+
+def bbh_final_spin_projected_spins(m1, m2, chi1, chi2, tilt1, tilt2, fitname, truncate=bbh_Kerr_trunc_opts.trunc):
+    """
+    Calculate the (signed) dimensionless spin parameter of the final BH resulting from the merger of two black holes,
+    only using the projected spins along the total angular momentum
+    and some aligned-spin fit from the literature
+
+    Parameters
+    ----------
+    m1, m2 : component masses
+    chi1, chi2 : dimensionless spins of two BHs
+    tilt1, tilt2 : tilts (in radians) in the new spin convention
+    fitname: fit selection currently supports Pan2011 (non-spinning), HLZ2014, PhenomD, UIB2016, HBR2016, HL2016
+
+    Returns
+    -------
+    (signed) dimensionless final spin parameter, chif
+    """
+
+    m1    = np.array(m1,dtype=np.float64)
+    m2    = np.array(m2,dtype=np.float64)
+    chi1  = np.array(chi1,dtype=np.float64)
+    chi2  = np.array(chi2,dtype=np.float64)
+    tilt1 = np.array(tilt1,dtype=np.float64)
+    tilt2 = np.array(tilt2,dtype=np.float64)
+
+    _check_mchi(m1,m2,chi1,chi2) # Check that inputs are physical
+
+    chi1proj = chi1*np.cos(tilt1)
+    chi2proj = chi2*np.cos(tilt2)
+
+    if fitname==bbh_final_state_fits.pan2011:
+       if np.any(chi1!=0) or np.any(chi2!=0) or np.any(tilt1!=0) or np.any(tilt2!=0):
+          print("Note: Pan2011 fit does not use spins.")
+       chif = bbh_final_spin_non_spinning_Panetal(m1, m2)
+    elif fitname==bbh_final_state_fits.hlz2014:
+       chif = bbh_final_spin_non_precessing_Healyetal(m1, m2, chi1proj, chi2proj, version="2014")
+    elif fitname==bbh_final_state_fits.hl2016:
+       chif = bbh_final_spin_non_precessing_Healyetal(m1, m2, chi1proj, chi2proj, version="2016")
+    elif fitname==bbh_final_state_fits.phenD:
+       chif = bbh_final_spin_non_precessing_Husaetal(m1, m2, chi1proj, chi2proj)
+    elif fitname==bbh_final_state_fits.uib2016:
+       chif = bbh_final_spin_non_precessing_UIB2016(m1, m2, chi1proj, chi2proj, version="v2")
+    elif fitname==bbh_final_state_fits.uib2016v1:
+       chif = bbh_final_spin_non_precessing_UIB2016(m1, m2, chi1proj, chi2proj, version="v1")
+    elif fitname==bbh_final_state_fits.hbr2016:
+       chif = bbh_final_spin_non_precessing_HBR2016(m1, m2, chi1proj, chi2proj)
+    else:
+       raise ValueError("Unrecognized fit name.")
+
+    chif = _truncate_at_Kerr_limit(chif, truncate, fitname) # optionally truncate and/or warn at Kerr limit, depending on user option
+
+    return chif
+
+def bbh_final_spin_precessing(m1, m2, chi1, chi2, tilt1, tilt2, phi12, fitname, truncate=bbh_Kerr_trunc_opts.trunc):
+    """
+    Calculate the magnitude of the dimensionless spin parameter of the final BH resulting from the merger of two black holes,
+    including the in-plane spin components;
+    by either using a precessing fit from the literature;
+    or by first projecting the spins along the angular momentum and using an aligned-spin fit from the literature,
+    then adding in quadrature the in-plane dimensionful spin scaled by the initial mass squared.
+
+    Parameters
+    ----------
+    m1, m2 : component masses
+    chi1, chi2 : dimensionless spins of two BHs
+    tilt1, tilt2 : tilts (in radians) in the new spin convention
+    phi12: angle (in radians) between in-plane spin components
+    fitname: fit selection currently supports Pan2011 (non-spinning), HLZ2014 (aligned+augmentation),
+                                              PhenomD (aligned+augmentation), UIB2016 (aligned+augmentation),
+                                              HL2016 (aligned+augmentation), HBR2016 (precessing)
+
+    Returns
+    -------
+    magnitude of the dimensionless final spin parameter, chif
+    """
+
+    m1    = np.array(m1,dtype=np.float64)
+    m2    = np.array(m2,dtype=np.float64)
+    chi1  = np.array(chi1,dtype=np.float64)
+    chi2  = np.array(chi2,dtype=np.float64)
+    tilt1 = np.array(tilt1,dtype=np.float64)
+    tilt2 = np.array(tilt2,dtype=np.float64)
+    phi12 = np.array(phi12,dtype=np.float64)
+
+    _check_mchi(m1,m2,chi1,chi2) # Check that inputs are physical
+
+    if fitname==bbh_final_state_fits.pan2011 or fitname==bbh_final_state_fits.hlz2014 or fitname==bbh_final_state_fits.phenD or fitname==bbh_final_state_fits.uib2016 or fitname==bbh_final_state_fits.uib2016v1 or fitname==bbh_final_state_fits.hl2016:
+       precfit = False
+    elif fitname==bbh_final_state_fits.hbr2016:
+       precfit = True
+       chif = bbh_final_spin_precessing_HBR2016(m1, m2, chi1, chi2, tilt1, tilt2, phi12)
+    else:
+       raise ValueError("Unrecognized fit name.")
+
+    if not precfit:
+       # First compute the final mass and parallel component of the final spin using the aligned components of the initial spins
+       chifaligned = bbh_final_spin_projected_spins(m1, m2, chi1, chi2, tilt1, tilt2, fitname, truncate)
+
+       # Now compute the squared magnitude of the in-plane dimensionful spin, first computing the magnitudes of the initial in-plane spins
+       S1perpmag = m1*m1*chi1*np.sin(tilt1)
+       S2perpmag = m2*m2*chi2*np.sin(tilt2)
+       Sperpmag2 = S1perpmag*S1perpmag + S2perpmag*S2perpmag + 2.*S1perpmag*S2perpmag*np.cos(phi12)
+
+       # Combine together
+       chif = (chifaligned*chifaligned + Sperpmag2/(m1+m2)**4.)**0.5
+
+    chif = _truncate_at_Kerr_limit(chif, truncate, "augmented "+fitname) # optionally truncate and/or warn at Kerr limit, depending on user option
+
+    return chif
+
+def bbh_final_mass_non_precessing_Husaetal(m1, m2, chi1, chi2):
+    """
+    Calculate the mass of the final BH resulting from the
+    merger of two black holes with non-precessing spins using the fits
+    used by IMRPhenomD, given in Eqs. (3.6) and (3.8) of Husa et al.
+    arXiv:1508.07250. Note that Eq. (3.8) gives the radiated energy, not
+    the final mass directly
+
+    m1, m2: component masses
+    chi1, chi2: dimensionless spins of two BHs
+    """
+    m1 = np.array(m1,dtype=np.float64)
+    m2 = np.array(m2,dtype=np.float64)
+    chi1 = np.array(chi1,dtype=np.float64)
+    chi2 = np.array(chi2,dtype=np.float64)
+
+    if np.any(abs(chi1)>1):
+      raise ValueError("chi1 has to be in [-1, 1]")
+    if np.any(abs(chi2)>1):
+      raise ValueError("chi2 has to be in [-1, 1]")
+
+    # binary parameters
+    m = m1+m2
+    msq = m*m
+
+    eta = m1*m2/msq
+    eta2 = eta*eta
+    eta3 = eta2*eta
+    eta4 = eta3*eta
+
+    S1 = chi1*m1**2/msq                   # spin angular momentum 1 (in m = 1 units)
+    S2 = chi2*m2**2/msq                   # spin angular momentum 2 (in m = 1 units)
+    S = S1+S2                        # total spin
+    Sh = S/(1. - 2.*eta)                    # rescaled total spin
+
+    # Expressions copied from LALSimIMRPhenomD_internals.c (except with two notation differences: S is capitalized in chif and s -> Sh in Mf, in addition to the "m*(1. - ...)" to obtain the final mass from the radiated mass in m = 1 units which is calculated in the LAL code)
+
+    Mf = m*(1. - ((0.055974469826360077*eta + 0.5809510763115132*eta2 - 0.9606726679372312*eta3 + 3.352411249771192*eta4)*
+    (1. + (-0.0030302335878845507 - 2.0066110851351073*eta + 7.7050567802399215*eta2)*Sh))/(1. + (-0.6714403054720589 - 1.4756929437702908*eta + 7.304676214885011*eta2)*Sh))
+
+    return Mf
+
+def bbh_final_spin_non_precessing_Husaetal(m1, m2, chi1, chi2):
+    """
+    Calculate the spin of the final BH resulting from the
+    merger of two black holes with non-precessing spins using the fits
+    used by IMRPhenomD, given in Eqs. (3.6) and (3.8) of Husa et al.
+    arXiv:1508.07250. Note that Eq. (3.8) gives the radiated energy, not
+    the final mass directly
+
+    m1, m2: component masses
+    chi1, chi2: dimensionless spins of two BHs
+    """
+    # Vectorize the function if arrays are provided as input
+    m1 = np.array(m1,dtype=np.float64)
+    m2 = np.array(m2,dtype=np.float64)
+    chi1 = np.array(chi1,dtype=np.float64)
+    chi2 = np.array(chi2,dtype=np.float64)
+
+    if np.any(abs(chi1)>1):
+      raise ValueError("chi1 has to be in [-1, 1]")
+    if np.any(abs(chi2)>1):
+      raise ValueError("chi2 has to be in [-1, 1]")
+
+    # binary parameters
+    m = m1+m2
+    msq = m*m
+
+    eta = m1*m2/msq
+    eta2 = eta*eta
+    eta3 = eta2*eta
+    eta4 = eta3*eta
+
+    S1 = chi1*m1**2/msq                   # spin angular momentum 1 (in m = 1 units)
+    S2 = chi2*m2**2/msq                   # spin angular momentum 2 (in m = 1 units)
+    S = S1+S2                        # total spin
+    Sh = S/(1. - 2.*eta)                    # rescaled total spin
+
+    Ssq = S*S
+    Scu = Ssq*S
+    Squ = Scu*S
+
+    # Expressions copied from LALSimIMRPhenomD_internals.c (except with two notation differences: S is capitalized in chif and s -> Sh in Mf, in addition to the "m*(1. - ...)" to obtain the final mass from the radiated mass in m = 1 units which is calculated in the LAL code)
+
+    chif = 3.4641016151377544*eta - 4.399247300629289*eta2 + 9.397292189321194*eta3 - 13.180949901606242*eta4 + (1 - 0.0850917821418767*eta - 5.837029316602263*eta2)*S + (0.1014665242971878*eta - 2.0967746996832157*eta2)*Ssq + (-1.3546806617824356*eta + 4.108962025369336*eta2)*Scu + (-0.8676969352555539*eta + 2.064046835273906*eta2)*Squ
+
+    return chif
+
+def bbh_UIBfits_setup(m1, m2, chi1, chi2):
+    """
+    common setup function for UIB final-state and luminosity fit functions
+    """
+
+    # Vectorize the function if arrays are provided as input
+    m1   = np.array(m1,dtype=np.float64)
+    m2   = np.array(m2,dtype=np.float64)
+    chi1 = np.array(chi1,dtype=np.float64)
+    chi2 = np.array(chi2,dtype=np.float64)
+
+    if np.any(m1<0):
+      raise ValueError("m1 must not be negative")
+    if np.any(m2<0):
+      raise ValueError("m2 must not be negative")
+
+    if np.any(abs(chi1)>1):
+      raise ValueError("chi1 has to be in [-1, 1]")
+    if np.any(abs(chi2)>1):
+      raise ValueError("chi2 has to be in [-1, 1]")
+
+    # binary masses
+    m    = m1+m2
+    if np.any(m<=0):
+      raise ValueError("m1+m2 must be positive")
+    msq  = m*m
+    m1sq = m1*m1
+    m2sq = m2*m2
+
+    # symmetric mass ratio
+    eta  = m1*m2/msq
+    if np.any(eta>0.25):
+      print("Truncating eta from above to 0.25. This should only be necessary in some rounding corner cases, but better check your m1 and m2 inputs...")
+      eta = np.minimum(eta,0.25)
+    if np.any(eta<0.0):
+      print("Truncating negative eta to 0.0. This should only be necessary in some rounding corner cases, but better check your m1 and m2 inputs...")
+      eta = np.maximum(eta,0.0)
+    eta2 = eta*eta
+    eta3 = eta2*eta
+    eta4 = eta2*eta2
+
+    # spin variables (in m = 1 units)
+    S1    = chi1*m1sq/msq # spin angular momentum 1
+    S2    = chi2*m2sq/msq # spin angular momentum 2
+    Stot  = S1+S2         # total spin
+    Shat  = (chi1*m1sq+chi2*m2sq)/(m1sq+m2sq) # effective spin, = msq*Stot/(m1sq+m2sq)
+    Shat2 = Shat*Shat
+    Shat3 = Shat2*Shat
+    Shat4 = Shat2*Shat2
+
+    # asymmetric spin combination (spin difference), where the paper assumes m1>m2
+    # to make our implementation symmetric under simultaneous exchange of m1<->m2 and chi1<->chi2,
+    # we flip the sign here when m2>m1
+    chidiff  = chi1 - chi2
+    if np.any(m2>m1):
+      chidiff = np.sign(m1-m2)*chidiff
+    chidiff2 = chidiff*chidiff
+
+    # typical squareroots and functions of eta
+    sqrt2 = 2.**0.5
+    sqrt3 = 3.**0.5
+    sqrt1m4eta = (1. - 4.*eta)**0.5
+
+    return m, eta, eta2, eta3, eta4, Stot, Shat, Shat2, Shat3, Shat4, chidiff, chidiff2, sqrt2, sqrt3, sqrt1m4eta
+
+def bbh_final_mass_non_precessing_UIB2016(m1, m2, chi1, chi2, version="v2"):
+    """
+    Calculate the final mass with the aligned-spin NR fit
+    by Xisco Jimenez Forteza, David Keitel, Sascha Husa et al.
+    [LIGO-P1600270] [https://arxiv.org/abs/1611.00332]
+    versions v1 and v2 use the same ansatz,
+    with v2 calibrated to additional SXS and RIT data
+
+    m1, m2: component masses
+    chi1, chi2: dimensionless spins of two BHs
+    Results are symmetric under simultaneous exchange of m1<->m2 and chi1<->chi2.
+    """
+
+    m, eta, eta2, eta3, eta4, Stot, Shat, Shat2, Shat3, Shat4, chidiff, chidiff2, sqrt2, sqrt3, sqrt1m4eta = bbh_UIBfits_setup(m1, m2, chi1, chi2)
+
+    if version == "v1":
+        # rational-function Pade coefficients (exact) from Eq. (22) of 1611.00332v1
+        b10 = 0.487
+        b20 = 0.295
+        b30 = 0.17
+        b50 = -0.0717
+        # fit coefficients from Tables VII-X of 1611.00332v1
+        # values at increased numerical precision copied from
+        # https://gravity.astro.cf.ac.uk/cgit/cardiff_uib_share/tree/Luminosity_and_Radiated_Energy/UIBfits/LALInference/EradUIB2016_pyform_coeffs.txt
+        # git commit 636e5a71462ecc448060926890aa7811948d5a53
+        a2 = 0.5635376058169299
+        a3 = -0.8661680065959881
+        a4 = 3.181941595301782
+        b1 = -0.15800074104558132
+        b2 = -0.15815904609933157
+        b3 = -0.14299315232521553
+        b5 = 8.908772171776285
+        f20 = 3.8071100104582234
+        f30 = 25.99956516423936
+        f50 = 1.552929335555098
+        f10 = 1.7004558922558886
+        f21 = 0.
+        d10 = -0.12282040108157262
+        d11 = -3.499874245551208
+        d20 = 0.014200035799803777
+        d30 = -0.01873720734635449
+        d31 = -5.1830734185518725
+        f11 = 14.39323998088354
+        f31 = -232.25752840151296
+        f51 = -0.8427987782523847
+
+    elif version == "v2":
+        # rational-function Pade coefficients (exact) from Eq. (22) of LIGO-P1600270-v4
+        b10 = 0.346
+        b20 = 0.211
+        b30 = 0.128
+        b50 = -0.212
+        # fit coefficients from Tables VII-X of LIGO-P1600270-v4
+        # values at increased numerical precision copied from
+        # https://dcc.ligo.org/DocDB/0128/P1600270/004/FinalStateUIB2016_suppl_Erad_coeffs.txt
+        a2 = 0.5609904135313374
+        a3 = -0.84667563764404
+        a4 = 3.145145224278187
+        b1 = -0.2091189048177395
+        b2 = -0.19709136361080587
+        b3 = -0.1588185739358418
+        b5 = 2.9852925538232014
+        f20 = 4.271313308472851
+        f30 = 31.08987570280556
+        f50 = 1.5673498395263061
+        f10 = 1.8083565298668276
+        f21 = 0.
+        d10 = -0.09803730445895877
+        d11 = -3.2283713377939134
+        d20 = 0.01118530335431078
+        d30 = -0.01978238971523653
+        d31 = -4.91667749015812
+        f11 = 15.738082204419655
+        f31 = -243.6299258830685
+        f51 = -0.5808669012986468
+
+    else:
+        raise ValueError('Unknown version -- should be either "v1" or "v2".')
+
+    # Calculate the radiated-energy fit from Eq. (28) of LIGO-P1600270-v4
+    Erad = (((1. + -2.0/3.0*sqrt2)*eta + a2*eta2 + a3*eta3 + a4*eta4)*(1. + b10*b1*Shat*(f10 + f11*eta + (16. - 16.*f10 - 4.*f11)*eta2) + b20*b2*Shat2*(f20 + f21*eta + (16. - 16.*f20 - 4.*f21)*eta2) + b30*b3*Shat3*(f30 + f31*eta + (16. - 16.*f30 - 4.*f31)*eta2)))/(1. + b50*b5*Shat*(f50 + f51*eta + (16. - 16.*f50 - 4.*f51)*eta2)) + d10*sqrt1m4eta*eta2*(1. + d11*eta)*chidiff + d30*Shat*sqrt1m4eta*eta*(1. + d31*eta)*chidiff + d20*eta3*chidiff2
+
+    # Convert to actual final mass
+    Mf = m*(1.-Erad)
+
+    return Mf
+
+def bbh_final_spin_non_precessing_UIB2016(m1, m2, chi1, chi2, version="v2"):
+    """
+    Calculate the final spin with the aligned-spin NR fit
+    by Xisco Jimenez Forteza, David Keitel, Sascha Husa et al.
+    [LIGO-P1600270] [https://arxiv.org/abs/1611.00332]
+    versions v1 and v2 use the same ansatz,
+    with v2 calibrated to additional SXS and RIT data
+
+    m1, m2: component masses
+    chi1, chi2: dimensionless spins of two BHs
+    Results are symmetric under simultaneous exchange of m1<->m2 and chi1<->chi2.
+    """
+
+    m, eta, eta2, eta3, eta4, Stot, Shat, Shat2, Shat3, Shat4, chidiff, chidiff2, sqrt2, sqrt3, sqrt1m4eta = bbh_UIBfits_setup(m1, m2, chi1, chi2)
+
+    if version == "v1":
+        # rational-function Pade coefficients (exact) from Eqs. (7) and (8) of 1611.00332v1
+        a20 = 5.28
+        a30 = 1.27
+        a50 = 2.89
+        b10 = -0.194
+        b20 = 0.075
+        b30 = 0.00782
+        b50 = -0.527
+        # fit coefficients from Tables I-IV of 1611.00332v1
+        # values at increased numerical precision copied from
+        # https://gravity.astro.cf.ac.uk/cgit/cardiff_uib_share/tree/Luminosity_and_Radiated_Energy/UIBfits/LALInference/FinalSpinUIB2016_pyform_coeffs.txt
+        # git commit 636e5a71462ecc448060926890aa7811948d5a53
+        a2 = 3.772362507208651
+        a3 = -9.627812453422376
+        a5 = 2.487406038123681
+        b1 = 1.0005294518146604
+        b2 = 0.8823439288807416
+        b3 = 0.7612809461506448
+        b5 = 0.9139185906568779
+        f21 = 8.887933111404559
+        f31 = 23.927104476660883
+        f50 = 1.8981657997557002
+        f11 = 4.411041530972546
+        f52 = 0.
+        d10 = 0.2762804043166152
+        d11 = 11.56198469592321
+        d20 = -0.05975750218477118
+        d30 = 2.7296903488918436
+        d31 = -3.388285154747212
+        f12 = 0.3642180211450878
+        f22 = -40.35359764942015
+        f32 = -178.7813942566548
+        f51 = -5.556957394513334
+
+    elif version == "v2":
+        # rational-function Pade coefficients (exact) from Eqs. (7) and (8) of LIGO-P1600270-v4
+        a20 = 5.24
+        a30 = 1.3
+        a50 = 2.88
+        b10 = -0.194
+        b20 = 0.0851
+        b30 = 0.00954
+        b50 = -0.579
+        # fit coefficients from Tables I-IV of LIGO-P1600270-v4
+        # values at increased numerical precision copied from
+        # https://dcc.ligo.org/DocDB/0128/P1600270/004/FinalStateUIB2016_suppl_spin_coeffs.txt
+        a2 = 3.8326341618708577
+        a3 = -9.487364155598392
+        a5 = 2.5134875145648374
+        b1 = 1.0009563702914628
+        b2 = 0.7877509372255369
+        b3 = 0.6540138407185817
+        b5 = 0.8396665722805308
+        f21 = 8.77367320110712
+        f31 = 22.830033250479833
+        f50 = 1.8804718791591157
+        f11 = 4.409160174224525
+        f52 = 0.
+        d10 = 0.3223660562764661
+        d11 = 9.332575956437443
+        d20 = -0.059808322561702126
+        d30 = 2.3170397514509933
+        d31 = -3.2624649875884852
+        f12 = 0.5118334706832706
+        f22 = -32.060648277652994
+        f32 = -153.83722669033995
+        f51 = -4.770246856212403
+
+    else:
+        raise ValueError('Unknown version -- should be either "v1" or "v2".')
+
+    # Calculate the fit for the Lorb' quantity from Eq. (16) of LIGO-P1600270-v4
+    Lorb = (2.*sqrt3*eta + a20*a2*eta2 + a30*a3*eta3)/(1. + a50*a5*eta) + (b10*b1*Shat*(f11*eta + f12*eta2 + (64. - 16.*f11 - 4.*f12)*eta3) + b20*b2*Shat2*(f21*eta + f22*eta2 + (64. - 16.*f21 - 4.*f22)*eta3) + b30*b3*Shat3*(f31*eta + f32*eta2 + (64. - 16.*f31 - 4.*f32)*eta3))/(1. + b50*b5*Shat*(f50 + f51*eta + f52*eta2 + (64. - 64.*f50 - 16.*f51 - 4.*f52)*eta3)) + d10*sqrt1m4eta*eta2*(1. + d11*eta)*chidiff + d30*Shat*sqrt1m4eta*eta3*(1. + d31*eta)*chidiff + d20*eta3*chidiff2
+
+    # Convert to actual final spin
+    chif = Lorb + Stot
+
+    return chif
+
+def _bbh_HBR2016_setup(m1, m2, chi1, chi2):
+    """
+    Setup function for the Hofmann, Barausse, and Rezzolla final spin fits to vectorize the masses and spins and calculate the mass ratio.
+    """
+
+    # Vectorize if arrays are provided as input
+    m1 = np.array(m1,dtype=np.float64)
+    m2 = np.array(m2,dtype=np.float64)
+    chi1 = np.array(chi1,dtype=np.float64)
+    chi2 = np.array(chi2,dtype=np.float64)
+
+    return m1, m2, chi1, chi2, m2/m1
+
+def _bbh_HBR2016_ell(m1, m2, chi1z, chi2z, version):
+    """
+    Compute the orbital angular momentum ell used by the Hofmann, Barausse, and Rezzolla final spin fit [from ApJL 825, L19 (2016)], henceforth HBR.
+    The three versions available correspond to the three choices of fit coefficients given in Table 1 of that paper, with 6, 16, and 20 coefficients, respectively.
+
+    version can thus be "M1J2", "M3J3", or "M3J4"
+    """
+
+    # Set upper bounds for sums and coefficients from Table 1 in HBR; k00 is calculated from Eq. (11) in the paper
+
+    if version == "M1J2":
+        nM = 1
+        nJ = 2
+
+        k00 = -3.82116
+        k01 = -1.2019
+        k02 = -1.20764
+        k10 = 3.79245
+        k11 = 1.18385
+        k12 = 4.90494
+        xi = 0.41616
+
+    elif version == "M3J3":
+        nM = 3
+        nJ = 3
+
+        k00 = -5.83164
+        k01 = 2.87025
+        k02 = -1.53315
+        k03 = -3.78893
+        k10 = 32.9127
+        k11 = -62.9901
+        k12 = 10.0068
+        k13 = 56.1926
+        k20 = -136.832
+        k21 = 329.32
+        k22 = -13.2034
+        k23 = -252.27
+        k30 = 210.075
+        k31 = -545.35
+        k32 = -3.97509
+        k33 = 368.405
+        xi = 0.463926
+
+    elif version == "M3J4":
+        nM = 3
+        nJ = 4
+
+        k00 = -5.97723
+        k01 = 3.39221
+        k02 = 4.48865
+        k03 = -5.77101
+        k04 = -13.0459
+        k10 = 35.1278
+        k11 = -72.9336
+        k12 = -86.0036
+        k13 = 93.7371
+        k14 = 200.975
+        k20 = -146.822
+        k21 = 387.184
+        k22 = 447.009
+        k23 = -467.383
+        k24 = -884.339
+        k30 = 223.911
+        k31 = -648.502
+        k32 = -697.177
+        k33 = 753.738
+        k34 = 1166.89
+        xi = 0.474046
+
+    else:
+        raise ValueError('Unknown version--should be either "M1J2", "M3J3", or "M3J4".')
+
+    # Calculate eta, atot, and aeff; note that HBR call the symmetric mass ratio nu instead of eta
+
+    m = m1 + m2
+    q = m2/m1
+    eta = m1*m2/(m*m)
+
+    atot = (chi1z + q*q*chi2z)/((1.+q)*(1.+q)) # Eq. (12) in HBR
+    aeff = atot + xi*eta*(chi1z + chi2z) # Inline equation below Eq. (7); see also Eq. (15) for the precessing analogue
+
+    # Calculate ISCO energy and angular momentum
+    r_isco = calc_isco_radius(aeff)
+    e_isco = (1. - 2./3./r_isco)**0.5 # Eq. (2) in HBR
+    l_isco = 2./(3.*3.**0.5)*(1. + 2.*(3.*r_isco - 2.)**0.5) # Eq. (3) in HBR
+
+    # The following expressions give the double sum in Eq. (13) in HBR (without the overall factor of eta that is put in below) specialized to the nJ values for the three versions, i.e., nJ = 2 => M1J2, nJ = 3 => M3J3, nJ = 4 => M3J4
+    if nJ >= 2:
+        aeff2 = aeff*aeff
+        ksum = k00 + k01*aeff + k02*aeff2 + eta*(k10 + k11*aeff + k12*aeff2)
+    if nJ >= 3:
+        eta2 = eta*eta
+        eta3 = eta2*eta
+        aeff3 = aeff2*aeff
+        ksum = ksum + (k03 + eta*k13)*aeff3 + eta2*(k20 + k21*aeff + k22*aeff2 + k23*aeff3) + eta3*(k30 + k31*aeff + k32*aeff2 + k33*aeff3)
+    if nJ >= 4:
+        ksum = ksum + (k04 + eta*k14 + eta2*k24 + eta3*k34)*aeff3*aeff
+
+    # Calculate the absolute value of ell
+    ell = abs((l_isco - 2.*atot*(e_isco - 1.)) + eta*ksum) # Eq. (13) in HBR
+
+    return ell
+
+def bbh_final_spin_non_precessing_HBR2016(m1, m2, chi1z, chi2z, version="M3J3"):
+    """
+    Calculate the (signed) dimensionless spin of the final BH resulting from the
+    merger of two black holes with aligned spins using the fit from Hofmann, Barausse, and Rezzolla ApJL 825, L19 (2016), henceforth HBR.
+
+    The three versions available correspond to the three choices of fit coefficients given in Table 1 of that paper, with 6, 16, and 20 coefficients, respectively.
+
+    version can thus be "M1J2", "M3J3", or "M3J4"
+
+    m1, m2: component masses
+    chi1z, chi2z: components of the dimensionless spins of the two BHs along the orbital angular momentum
+    """
+
+    # Calculate q and vectorize the masses and spins if arrays are provided as input
+
+    m1, m2, chi1z, chi2z, q = _bbh_HBR2016_setup(m1, m2, chi1z, chi2z)
+
+    # Calculate the final spin
+
+    atot = (chi1z + chi2z*q*q)/((1.+q)*(1.+q)) # Eq. (12) in HBR
+
+    ell = _bbh_HBR2016_ell(m1, m2, chi1z, chi2z, version)
+
+    return atot + ell/(1./q + 2. + q) # Eq. (12) in HBR, writing the symmetric mass ratio in terms of q
+
+def bbh_final_spin_precessing_HBR2016(m1, m2, chi1, chi2, tilt1, tilt2, phi12, version="M3J3"):
+    """
+    Calculate the dimensionless spin of the final BH resulting from the
+    merger of two black holes with precessing spins using the fit from Hofmann, Barausse, and Rezzolla ApJL 825, L19 (2016), henceforth HBR.
+
+    The three versions available correspond to the three choices of fit coefficients given in Table 1 of that paper, with 6, 16, and 20 coefficients, respectively.
+
+    version can thus be "M1J2", "M3J3", or "M3J4"
+
+    m1, m2: component masses
+    chi1, chi2: dimensionless spins of two BHs
+    tilt1, tilt2: tilt angles of the spins from the orbital angular momentum
+    phi12: angle between in-plane spin components
+    """
+
+    # Calculate q and vectorize the masses and spins if arrays are provided as input
+
+    m1, m2, chi1, chi2, q = _bbh_HBR2016_setup(m1, m2, chi1, chi2)
+
+    # Vectorize the spin angles if arrays are provided as input
+    tilt1 = np.array(tilt1,dtype=np.float64)
+    tilt2 = np.array(tilt2,dtype=np.float64)
+    phi12 = np.array(phi12,dtype=np.float64)
+
+    # Set eps (\epsilon_\beta or \epsilon_\gamma) to the value given below Eq. (18) in HBR
+
+    eps = 0.024
+
+    # Computing angles defined in Eq. (17) of HBR. The betas and gammas expressions are for the starred quantities computed using the second (approximate) equality in Eq. (18) in HBR
+    cos_beta = np.cos(tilt1)
+    cos_betas = np.cos(tilt1 + eps*np.sin(tilt1))
+    cos_gamma = np.cos(tilt2)
+    cos_gammas = np.cos(tilt2 + eps*np.sin(tilt2))
+    cos_alpha = ((1 - cos_beta*cos_beta)*(1 - cos_gamma*cos_gamma))**0.5*np.cos(phi12) + cos_beta*cos_gamma # This rewrites the inner product definition of cos_alpha in terms of cos_beta, cos_gamma, and phi12
+
+    # Define a shorthand and compute the final spin
+
+    q2 = q*q
+
+    ell = _bbh_HBR2016_ell(m1, m2, chi1*cos_betas, chi2*cos_gammas, version)
+
+    # Compute the final spin value [Eq. (16) in HBR], truncating the argument of the square root at zero if it becomes negative
+    sqrt_arg = chi1*chi1 + chi2*chi2*q2*q2 + 2.*chi1*chi2*q2*cos_alpha + 2.*(chi1*cos_betas + chi2*q2*cos_gammas)*ell*q + ell*ell*q2
+    if np.any(sqrt_arg < 0.):
+        print(f"bbh_final_spin_precessing_HBR2016(): The argument of the square root is negative for indexes {np.where(sqrt_arg < 0)[0]}; truncating it to zero.")
+        sqrt_arg = np.clip(sqrt_arg,0.,None)
+
+    # Return the final spin value [Eq. (16) in HBR]
+    return sqrt_arg**0.5/((1.+q)*(1.+q))
+
+#######################
+# Peak luminosity fits
+#######################
+
+# list of peak luminosity fit names
+class bbh_Lpeak_fits:
+    t1600018  = "T1600018" # Jimenez Forteza et al. [LIGO-T1600018 (2016)]         (aligned)
+    uib2016   = "UIB2016"  # Keitel et al.          [arXiv:1612.09566]             (aligned)
+    hl2016    = "HL2016"   # Healy and Lousto       [arXiv:1610.09713]             (aligned)
+
+def _rescale_Lpeak(Lpeak):
+    """
+    convert from geometric units ("Planck luminosity" of c^5/G) to multiples of 10^56 erg/s = 10^49 J/s
+    """
+    LumPl_ergs_per_sec = lal.LUMPL_SI*1e-49 # Approximate value = 3628.505
+    return LumPl_ergs_per_sec*Lpeak
+
+def bbh_aligned_Lpeak_6mode_SHXJDK(q, chi1, chi2):
+    """
+    wrapper to bbh_peak_luminosity_non_precessing_T1600018() for backwards compatibility
+
+    q: mass ratio (here m2/m1, where m1>m2)
+    chi1: the component of the dimensionless spin of m1 along the angular momentum (z)
+    chi2: the component of the dimensionless spin of m2 along the angular momentum (z)
+    """
+    # Vectorize the function if arrays are provided as input
+    q = np.array(q,dtype=np.float64)
+
+    # from bayespputils.py convention is q = m2/m1, where m1>m2.
+    if np.any(q<=0.):
+      raise ValueError("q has to be > 0.")
+    if np.any(q>1.):
+      raise ValueError("q has to be <= 1.")
+
+    # T1600018 fit expects m1>m2;
+    # implementation here should be symmetric,
+    # but we follow that convention to be sure
+    m1 = 1./(1.+q)
+    m2 = q/(1.+q)
+
+    return bbh_peak_luminosity_non_precessing_T1600018(m1, m2, chi1, chi2)
+
+def bbh_peak_luminosity_non_precessing_T1600018(m1, m2, chi1, chi2):
+    """
+    Calculate the peak luminosity (using modes 22, 21, 33, 32, 44, and 43) of a binary black hole with aligned spins using the fit made by Sascha Husa, Xisco Jimenez Forteza, David Keitel [LIGO-T1500598] using 5th order in chieff and return results in units of 10^56 ergs/s
+
+    m1, m2: component masses
+    chi1: the component of the dimensionless spin of m1 along the angular momentum (z)
+    chi2: the component of the dimensionless spin of m2 along the angular momentum (z)
+    Results are symmetric under simultaneous exchange of m1<->m2 and chi1<->chi2.
+    """
+
+    # Vectorize the function if arrays are provided as input
+    m1 = np.array(m1,dtype=np.float64)
+    m2 = np.array(m2,dtype=np.float64)
+    chi1 = np.array(chi1,dtype=np.float64)
+    chi2 = np.array(chi2,dtype=np.float64)
+
+    # Calculate powers of eta and the effective spin S (not used in this fit)
+    m, eta, eta2, eta3, eta4, Stot, Shat, Shat2, Shat3, Shat4, chidiff, chidiff2, sqrt2, sqrt3, sqrt1m4eta = bbh_UIBfits_setup(m1, m2, chi1, chi2)
+
+    dm2 = 1. - 4.*eta # equivalent to sqrt1m4eta**2
+
+    chi_eff = (m1*chi1+m2*chi2)/m # equivalent to (q_inv*chi1 + chi2)/(1. + q_inv)
+    chi_eff2 = chi_eff*chi_eff
+    chi_eff3 = chi_eff2*chi_eff
+    chi_eff4 = chi_eff3*chi_eff
+    chi_eff5 = chi_eff4*chi_eff
+
+    # Calculate best fit (from [https://dcc.ligo.org/T1500598-v4])
+    Lpeak = (0.012851338846828302 + 0.007822265919928252*chi_eff + 0.010221856361035788*chi_eff2 + 0.015805535732661396*chi_eff3 + 0.0011356206806770043*chi_eff4 - 0.009868152529667197*chi_eff5)*eta2 + (0.05681786589129071 - 0.0017473702709303457*chi_eff - 0.10150706091341818*chi_eff2 - 0.2349153289253309*chi_eff3 + 0.015657737820040145*chi_eff4 + 0.19556893194885075*chi_eff5)*eta4 + 0.026161288241420833*dm2**0.541825641769908*eta**3.1629576945611757*chidiff + 0.0007771032100485481*dm2**0.4499151697918658*eta**1.7800346166040835*chidiff2
+
+    # Convert to 10^56 ergs/s units
+    return _rescale_Lpeak(Lpeak)
+
+def bbh_peak_luminosity_non_precessing_UIB2016(m1, m2, chi1, chi2):
+    """
+    Calculate the peak luminosity with the aligned-spin NR fit
+    by David Keitel, Xisco Jimenez Forteza, Sascha Husa, Lionel London et al.
+    [LIGO-P1600279-v5] [https://arxiv.org/abs/1612.09566v1]
+    using modes up to lmax=6,
+    and return results in units of 10^56 ergs/s
+
+    m1, m2: component masses
+    chi1, chi2: dimensionless spins of two BHs
+    Results are symmetric under simultaneous exchange of m1<->m2 and chi1<->chi2.
+    """
+
+    m, eta, eta2, eta3, eta4, Stot, Shat, Shat2, Shat3, Shat4, chidiff, chidiff2, sqrt2, sqrt3, sqrt1m4eta = bbh_UIBfits_setup(m1, m2, chi1, chi2)
+    eta5 = eta3*eta2
+
+    # fit coefficients corresponding to Table I, II, IV,
+    # exact values corresponding to https://arxiv.org/src/1612.09566v1/anc/LpeakUIB2016_suppl_coeffs.txt
+    # fi2 coefficients are replaced by functions of fi0, fi1 as in Eq. (10)
+    a0 = 0.8742169580717333
+    a1 = -2.111792574893241
+    a2 = 35.214103272783646
+    a3 = -244.94930678226913
+    a4 = 877.1061892200927
+    a5 = -1172.549896493467
+    b1 = 0.9800204548606681
+    b2 = -0.1779843936224084
+    b4 = 1.7859209418791981
+    d10 = 3.789116271213293
+    d20 = 0.40214125006660567
+    d30 = 4.273116678713487
+    f10 = 1.6281049269810424
+    f11 = -3.6322940180721037
+    f20 = 31.710537408279116
+    f21 = -273.84758785648336
+    f30 = -0.23470852321351202
+    f31 = 6.961626779884965
+    f40 = 0.21139341988062182
+    f41 = 1.5255885529750841
+    f60 = 3.0901740789623453
+    f61 = -16.66465705511997
+    f70 = 0.8362061463375388
+    f71 = 0.
+
+    # calculate the Lpeak/(eta2*L0) fit from Eq. (14), using the constraints for fi2 from Eq. (10)
+    Lpeak = a0 + a1*eta + a2*eta2 + a3*eta3 + a4*eta4 + a5*eta5 + (0.465*b1*Shat*(f10 + f11*eta + (16. - 16.*f10 - 4.*f11)*eta2) + 0.107*b2*Shat2*(f20 + f21*eta + (16. - 16.*f20 - 4.*f21)*eta2) + Shat3*(f30 + f31*eta + (-16.*f30 - 4.*f31)*eta2) + Shat4*(f40 + f41*eta + (-16.*f40 - 4.*f41)*eta2))/(1. - 0.328*b4*Shat*(f60 + f61*eta + (16. - 16.*f60 - 4.*f61)*eta2) + Shat2*(f70 + f71*eta + (-16.*f70 - 4.*f71)*eta2)) + eta3*((d10+d30*Shat)*sqrt1m4eta*chidiff + d20*chidiff2)
+
+    # Lpeak(eta=0.25,chi1=chi2=0)/0.25^2
+    L0 = 0.016379197203103536
+
+    # Convert to actual peak luminosity
+    Lpeak = Lpeak*eta2*L0
+
+    # Convert to 10^56 ergs/s units
+    return _rescale_Lpeak(Lpeak)
+
+def bbh_peak_luminosity_non_precessing_Healyetal(m1, m2, chi1z, chi2z):
+    """
+    Calculate the peak luminosity of an aligned-spin binary black hole coalescence using the fit from Healy and Lousto arXiv:1610.09713 (henceforth HL)
+
+    Parameters
+    ----------
+    m1, m2 : component masses
+    chi1z, chi2z : components of the dimensionless spins of the two BHs along their orbital angular momentum
+
+    Returns
+    -------
+    peak luminosity in units of 10^56 ergs/s
+
+    """
+
+    m1 = np.array(m1,dtype=np.float64)
+    m2 = np.array(m2,dtype=np.float64)
+    chi1z = np.array(chi1z,dtype=np.float64)
+    chi2z = np.array(chi2z,dtype=np.float64)
+
+    eta, delta_m, S, Delta = _RIT_setup(m1, m2, chi1z, chi2z)
+
+    # fitting coefficients (from the RIT group's private Matlab implementation; versions to fewer digits are given in Table IV of HL)
+    coeffs = [0.00102101737,0.000897428902,-9.77467189e-05,0.000920883841,1.86982704e-05,-0.000391316975,-0.000120214144,0.000148102239,0.00137901473,-0.000493730555,0.000884792724,3.29254224e-07,1.70170729e-05,0.00151484008,-0.000148456828,0.000136659593,0.000160343115,-6.18530577e-05,-0.00103602521]
+
+    # Return the peak luminosity in units of 10^56 ergs/s [cf. Eq. (3) in HL]
+    Lpeak = _RIT_symm_express(eta, delta_m, S, Delta, coeffs)
+
+    return _rescale_Lpeak(Lpeak)
+
+def bbh_peak_luminosity_projected_spins(m1, m2, chi1, chi2, tilt1, tilt2, fitname):
+    """
+    Calculate the peak luminosity of the merger of two black holes,
+    only using the projected spins along the total angular momentum
+    and some aligned-spin fit from the literature
+
+    Parameters
+    ----------
+    m1, m2 : component masses
+    chi1, chi2 : dimensionless spins of two BHs
+    tilt1, tilt2 : tilts (in radians) in the new spin convention
+    fitname: fit selection currently supports T1600018, UIB2016, HL2016
+
+    Returns
+    -------
+    peak luminosity, Lpeak, in units of 10^56 ergs/s
+    """
+
+    m1    = np.array(m1,dtype=np.float64)
+    m2    = np.array(m2,dtype=np.float64)
+    chi1  = np.array(chi1,dtype=np.float64)
+    chi2  = np.array(chi2,dtype=np.float64)
+    tilt1 = np.array(tilt1,dtype=np.float64)
+    tilt2 = np.array(tilt2,dtype=np.float64)
+
+    _check_mchi(m1,m2,chi1,chi2) # Check that inputs are physical
+
+    chi1proj = chi1*np.cos(tilt1)
+    chi2proj = chi2*np.cos(tilt2)
+
+    if fitname==bbh_Lpeak_fits.t1600018:
+       Lpeak = bbh_peak_luminosity_non_precessing_T1600018(m1, m2, chi1proj, chi2proj)
+    elif fitname==bbh_Lpeak_fits.uib2016:
+       Lpeak = bbh_peak_luminosity_non_precessing_UIB2016(m1, m2, chi1proj, chi2proj)
+    elif fitname==bbh_Lpeak_fits.hl2016:
+       Lpeak = bbh_peak_luminosity_non_precessing_Healyetal(m1, m2, chi1proj, chi2proj)
+    else:
+       raise ValueError("Unrecognized fit name.")
+
+    return Lpeak
+
+#########################
+# Convenience functions
+#########################
+
+def bbh_average_fits_precessing(m1, m2, chi1, chi2, tilt1, tilt2, phi12, quantity, fits):
+    """
+    Calculate the average of the predictions of various fits, currently just for the final mass, final spin, or peak luminosity of a quasicircular
+    binary black hole coalescence. The final spin calculation returns the magnitude of the final spin, including the contribution
+    from in-plane spins; the other two cases just apply aligned-spin fits to the components of the spins along the orbital angular momentum.
+
+    Parameters
+    ----------
+    m1, m2 : component masses
+    chi1, chi2 : dimensionless spins of two BHs
+    tilt1, tilt2 : tilts (in radians) in the new spin convention
+    phi12: angle (in radians) between in-plane spin components (only used for the final spin)
+    quantity: "Mf", "af", "afz", or "Lpeak"
+    fits: An array of fit names to be used. The possible fit names are those known by bbh_final_mass_projected_spins, bbh_final_spin_precessing,
+          and bbh_peak_luminosity_projected_spins
+
+    The shape of m1 is used to determine the shape of the output.
+
+    Returns
+    -------
+    Average of the results for the given fits for the chosen quantity
+    """
+
+    if quantity != "af" and max(abs(np.atleast_1d(phi12))) != 0:
+        print("Note: phi12 is only used for the full final spin calculation.")
+
+    if quantity not in ["Mf", "af", "afz", "Lpeak"]:
+        raise ValueError("Unknown quantity: %s"%quantity)
+
+    # Define function to return the appropriate quantity
+
+    def _return_quantity(m1, m2, chi1, chi2, tilt1, tilt2, phi12, fitname):
+        if quantity == "Mf":
+            return bbh_final_mass_projected_spins(m1, m2, chi1, chi2, tilt1, tilt2, fitname)
+        elif quantity == "af":
+            return bbh_final_spin_precessing(m1, m2, chi1, chi2, tilt1, tilt2, phi12, fitname)
+        elif quantity == "afz":
+            return bbh_final_spin_projected_spins(m1, m2, chi1, chi2, tilt1, tilt2, fitname)
+        elif quantity == "Lpeak":
+            return bbh_peak_luminosity_projected_spins(m1, m2, chi1, chi2, tilt1, tilt2, fitname)
+
+    # Define a function that returns the length of an array when passed an array and 1 when not passed an array
+    def _len_smart(x):
+        if hasattr(x, '__len__'):
+            return len(x)
+        else:
+            return 1
+
+    # Initialize
+
+    fits = np.atleast_1d(fits)
+
+    if not fits.size: # Check to make sure that fits is not an empty array
+        raise ValueError("The list of fits passed cannot be an empty array.")
+
+    num_fits = len(fits)
+    num_data = max(_len_smart(m1), _len_smart(m2), _len_smart(chi1), _len_smart(chi2), _len_smart(tilt1), _len_smart(tilt2), _len_smart(phi12))
+
+    data = np.zeros([num_fits, num_data])
+
+    # Convert the input from bayespputils into a format that is compatible with the following loop
+
+    if hasattr(m1, 'shape'):
+        data_shape = m1.shape
+    else:
+        data_shape = -1
+
+    # Loop over the fits
+
+    for k, fit in enumerate(fits):
+        data_portion = _return_quantity(m1, m2, chi1, chi2, tilt1, tilt2, phi12, fit)
+        data[k] = data_portion.reshape(-1)
+
+    # Calculate average:
+    data_avg = np.mean(data,axis=0)
+
+    return data_avg.reshape(data_shape)