pybhpt 0.9.4__cp314-cp314-macosx_14_0_x86_64.whl → 0.9.8__cp314-cp314-macosx_14_0_x86_64.whl

pybhpt/geo.py

@@ -4,21 +4,147 @@ from cybhpt_full import kerr_mino_frequencies_wrapper, kerr_orbital_constants_wr
 import numpy as np
 
 def kerrgeo_Vt_radial(a, En, Lz, Q, r):
+    """
+    The radial part of the potential Vt for the geodesic evolution of $t_p$.
+
+    Parameters
+    ----------
+    a : float
+        The black hole spin parameter.
+    En : float
+        The orbital energy of the particle.
+    Lz : float
+        The z-component of the orbital angular momentum of the particle.
+    Q : float
+        The Carter constant of the particle.
+    r : float
+        The radial coordinate.
+    
+    Returns
+    -------
+    float
+        The value of the radial potential Vt at the given parameters.
+    """
     return kerr_geo_V01(a, En, Lz, Q, r)
 
 def kerrgeo_Vt_polar(a, En, Lz, Q, theta):
+    """
+    The polar part of the potential Vt for the geodesic evolution of $t_p$.
+
+    Parameters
+    ----------
+    a : float
+        The black hole spin parameter.
+    En : float
+        The orbital energy of the particle.
+    Lz : float
+        The z-component of the orbital angular momentum of the particle.
+    Q : float
+        The Carter constant of the particle.
+    theta : float
+        The polar angle coordinate.
+
+    Returns
+    -------
+    float
+        The value of the polar potential Vt at the given parameters.
+    """
     return kerr_geo_V02(a, En, Lz, Q, theta)
 
 def kerrgeo_Vr(a, En, Lz, Q, r):
+    """
+    The (squared) radial potential Vr for the geodesic evolution of $r_p$.
+
+    Parameters
+    ----------
+    a : float
+        The black hole spin parameter.
+    En : float
+        The orbital energy of the particle.
+    Lz : float
+        The z-component of the orbital angular momentum of the particle.
+    Q : float
+        The Carter constant of the particle.
+    r : float
+        The radial coordinate.
+
+    Returns
+    -------
+    float
+        The value of the radial potential Vr at the given parameters.
+    """
     return kerr_geo_V11(a, En, Lz, Q, r)
 
 def kerrgeo_Vtheta(a, En, Lz, Q, theta):
+    """
+    The (squared) polar potential Vtheta for the geodesic evolution of $\theta_p$.
+
+    Parameters
+    ----------
+    a : float
+        The black hole spin parameter.
+    En : float
+        The orbital energy of the particle.
+    Lz : float
+        The z-component of the orbital angular momentum of the particle.
+    Q : float
+        The Carter constant of the particle.
+    theta : float
+        The polar angle coordinate.
+
+    Returns
+    -------
+    float
+        The value of the polar potential Vtheta at the given parameters.
+    """
     return kerr_geo_V22(a, En, Lz, Q, theta)
 
 def kerrgeo_Vphi_radial(a, En, Lz, Q, r):
+    """
+    The (squared) radial potential Vphi for the geodesic evolution of $r_p$.
+
+    Parameters
+    ----------
+    a : float
+        The black hole spin parameter.
+    En : float
+        The orbital energy of the particle.
+    Lz : float
+        The z-component of the orbital angular momentum of the particle.
+    Q : float
+        The Carter constant of the particle.
+    r : float
+        The radial coordinate.
+
+    Returns
+    -------
+    float
+        The value of the radial potential Vphi at the given parameters.
+    """
     return kerr_geo_V31(a, En, Lz, Q, r)
 
 def kerrgeo_Vphi_polar(a, En, Lz, Q, theta):
+    """
+    The (squared) polar potential Vphi for the geodesic evolution of $r_p$.
+
+    Parameters
+    ----------
+    a : float
+        The black hole spin parameter.
+    En : float
+        The orbital energy of the particle.
+    Lz : float
+        The z-component of the orbital angular momentum of the particle.
+    Q : float
+        The Carter constant of the particle.
+    theta : float
+        The polar angle coordinate.
+
+    Returns
+    -------
+    float
+        The value of the polar potential Vphi at the given parameters.
+    """
     return kerr_geo_V32(a, En, Lz, Q, theta)
 
 def kerr_mino_frequencies(a, p, e, x):
@@ -373,25 +499,256 @@ class KerrGeodesic:
         """
         return np.dot(np.array([n, k, m]), (self.frequencies))
     
-    def minotime(self, t):
+    def psi_radial(self, la):
+        """
+        Function that returns the radial true anomaly for a given Mino time value.
+
+        Parameters
+        ----------
+        la : float or numpy.ndarray
+            The Mino time value(s). If a numpy array is provided, the function will return a numpy array of the same shape.
+        
+        Returns 
+        -------
+        numpy.ndarray
+            The radial true anomaly for the given Mino time value(s).
+        """
+        if isinstance(la, np.ndarray) or isinstance(la, list):
+            return self.base.psi_radial_vec(np.array(la))
+        else:
+            return self.base.psi_radial(la)
+        
+    def psi_polar(self, la):
+        """
+        Function that returns the polar Darwin phase for a given Mino time value.
+
+        Parameters
+        ----------
+        la : float or numpy.ndarray
+            The Mino time value(s). If a numpy array is provided, the function will return a numpy array of the same shape.
+        
+        Returns 
+        -------
+        numpy.ndarray
+            The polar Darwin phase for the given Mino time value(s).
+        """
+        if isinstance(la, np.ndarray) or isinstance(la, list):
+            return self.base.psi_polar_vec(np.array(la))
+        else:
+            return self.base.psi_polar(la)
+        
+    def psi_radial_of_t(self, t):
+        """
+        Function that returns the radial true anomaly for a given time value.
+
+        Parameters
+        ----------
+        t : float or numpy.ndarray
+            The time value(s). If a numpy array is provided, the function will return a numpy array of the same shape.
+        
+        Returns 
+        -------
+        numpy.ndarray
+            The radial true anomaly for the given time value(s).
+        """
+        if isinstance(t, np.ndarray) or isinstance(t, list):
+            return self.base.psi_radial_time_vec(np.array(t))
+        else:
+            return self.base.psi_radial_time(t)
+
+    def psi_polar_of_t(self, t):
+        """
+        Function that returns the polar Darwin phase for a given time value.
+
+        Parameters
+        ----------
+        t : float or numpy.ndarray
+            The time value(s). If a numpy array is provided, the function will return a numpy array of the same shape.
+        
+        Returns 
+        -------
+        numpy.ndarray
+            The polar Darwin phase for the given time value(s).
+        """
+        if isinstance(t, np.ndarray) or isinstance(t, list):
+            return self.base.psi_polar_time_vec(np.array(t))
+        else:
+            return self.base.psi_polar_time(t)
+
+    def time_position(self, la):
+        """
+        Function that returns the time position for a given Mino time value.
+
+        Parameters
+        ----------
+        la : float or numpy.ndarray
+            The Mino time value(s). If a numpy array is provided, the function will return a numpy array of the same shape.
+        
+        Returns 
+        -------
+        numpy.ndarray
+            The time position for the given Mino time value(s).
+        """
+        if isinstance(la, np.ndarray) or isinstance(la, list):
+            return self.base.time_position_vec(np.array(la))
+        else:
+            return self.base.time_position(la)
+
+    def radial_position(self, la):
+        """
+        Function that returns the radial position for a given Mino time value.
+
+        Parameters
+        ----------
+        la : float or numpy.ndarray
+            The Mino time value(s). If a numpy array is provided, the function will return a numpy array of the same shape.
+        
+        Returns 
+        -------
+        numpy.ndarray
+            The radial position for the given Mino time value(s).
+        """
+        if isinstance(la, np.ndarray) or isinstance(la, list):
+            return self.base.radial_position_vec(np.array(la))
+        else:
+            return self.base.radial_position(la)
+        
+    def polar_position(self, la):
+        """
+        Function that returns the polar position for a given Mino time value.
+
+        Parameters
+        ----------
+        la : float or numpy.ndarray
+            The Mino time value(s). If a numpy array is provided, the function will return a numpy array of the same shape.
+        
+        Returns 
+        -------
+        numpy.ndarray
+            The polar position for the given Mino time value(s).
+        """
+        if isinstance(la, np.ndarray) or isinstance(la, list):
+            return self.base.polar_position_vec(np.array(la))
+        else:
+            return self.base.polar_position(la)
+    
+    def azimuthal_position(self, la):
+        """
+        Function that returns the azimuthal position for a given Mino time value.
+
+        Parameters
+        ----------
+        la : float or numpy.ndarray
+            The Mino time value(s). If a numpy array is provided, the function will return a numpy array of the same shape.
+        
+        Returns 
+        -------
+        numpy.ndarray
+            The azimuthal position for the given Mino time value(s).
+        """
+        if isinstance(la, np.ndarray) or isinstance(la, list):
+            return self.base.azimuthal_position_vec(np.array(la))
+        else:
+            return self.base.azimuthal_position(la)
+    
+    def radial_position_of_t(self, t):
+        """
+        Function that returns the radial position for a given Mino time value.
+
+        Parameters
+        ----------
+        t : float or numpy.ndarray
+            The Mino time value(s). If a numpy array is provided, the function will return a numpy array of the same shape.
+        
+        Returns 
+        -------
+        numpy.ndarray
+            The radial position for the given Mino time value(s).
+        """
+        if isinstance(t, np.ndarray) or isinstance(t, list):
+            return self.base.radial_position_time_vec(np.array(t))
+        else:
+            return self.base.radial_position_time(t)
+        
+    def polar_position_of_t(self, t):
+        """
+        Function that returns the polar position for a given time value.
+
+        Parameters
+        ----------
+        t : float or numpy.ndarray
+            The time value(s). If a numpy array is provided, the function will return a numpy array of the same shape.
+        
+        Returns 
+        -------
+        numpy.ndarray
+            The polar position for the given time value(s).
+        """
+        if isinstance(t, np.ndarray) or isinstance(t, list):
+            return self.base.polar_position_time_vec(np.array(t))
+        else:
+            return self.base.polar_position_time(t)
+    
+    def azimuthal_position_of_t(self, t):
+        """
+        Function that returns the azimuthal position for a given time value.
+
+        Parameters
+        ----------
+        t : float or numpy.ndarray
+            The time value(s). If a numpy array is provided, the function will return a numpy array of the same shape.
+        
+        Returns 
+        -------
+        numpy.ndarray
+            The azimuthal position for the given time value(s).
+        """
+        if isinstance(t, np.ndarray) or isinstance(t, list):
+            return self.base.azimuthal_position_time_vec(np.array(t))
+        else:
+            return self.base.azimuthal_position_time(t)
+    
+    def mino_of_t(self, t):
         """
         Function that returns the Mino time for a given Boyer-Lindquist time.
 
         Parameters
         ----------
-        t : float
-            The Boyer-Lindquist time.
+        t : float or numpy.ndarray
+            The Boyer-Lindquist time value(s). If a numpy array is provided, the function will return a numpy array of the same shape.
         
-        Returns
+        Returns 
         -------
-        float
-            The Mino time for the given Boyer-Lindquist time.
+        numpy.ndarray
+            The Mino time for the given Boyer-Lindquist time value(s).
         """
-        return self.base.mino_time(t)
+        if isinstance(t, np.ndarray) or isinstance(t, list):
+            return self.base.mino_time_vec(np.array(t))
+        else:
+            return self.base.mino_time(t)
     
-    def __call__(self, la):
+    def position_of_t(self, t):
         """
-        Function that returns the position vector for a given Mino time value.
+        Function that returns the position vector (r, theta, phi) for a given Boyer-Lindquist time value.
+        
+        Parameters
+        ----------
+        t : float or numpy.ndarray
+            The Boyer-Lindquist time value(s). If a numpy array is provided, the function will return a numpy array of the same shape.
+        
+        Returns 
+        -------
+        numpy.ndarray
+            The position vector (r, theta, phi) for the given Boyer-Lindquist time value(s).
+        """
+        if isinstance(t, np.ndarray) or isinstance(t, list):
+            return self.base.position_time_vec(np.array(t))
+        else:
+            return self.base.position_time(t)
+        
+    def position(self, la):
+        """
+        Function that returns the position vector (t, r, theta, phi) for a given Mino time value.
         Parameters
         ----------
         la : float or numpy.ndarray
@@ -399,9 +756,12 @@ class KerrGeodesic:
         Returns 
         -------
         numpy.ndarray
-            The position vector for the given Mino time value(s).
+            The position vector (t, r, theta, phi) for the given Mino time value(s).
         """
         if isinstance(la, np.ndarray) or isinstance(la, list):
             return self.base.position_vec(np.array(la))
         else:
-            return self.base.position(la)
+            return self.base.position(la)
+    
+    def __call__(self, la):
+        return self.position(la)

pybhpt/radial.py

@@ -11,14 +11,55 @@ def available_methods():
     """
     return available_methods_cython()
 
-def renormalized_angular_momentum(s, l, m, a, omega):
-    return nu_cython(s, l, m, a, omega)
+def renormalized_angular_momentum(s, j, m, a, omega):
+    """
+    Computes the renormalized angular momentum for the given parameters.
 
-def renormalized_angular_momentum_monodromy(s, l, m, a, omega, la):
-    return nu_2_cython(s, l, m, a, omega, la)
+    Parameters
+    ----------
+    s : int
+        The spin weight of the field.
+    j : int
+        The spheroidal harmonic mode number.
+    m : int
+        The azimuthal harmonic mode number.
+    a : float
+        The black hole spin parameter.
+    omega : float
+        The frequency of the mode.  
 
-def hypergeo_2F1(a, b, c, x):
-    return hypergeo_2F1_cython(a, b, c, x)
+    Returns
+    -------
+    complex
+        The renormalized angular momentum.
+    """
+    return nu_cython(s, j, m, a, omega)
+
+def renormalized_angular_momentum_monodromy(s, j, m, a, omega, la):
+    """
+    Computes the renormalized angular momentum using the monodromy method for the given parameters.
+
+    Parameters
+    ----------
+    s : int
+        The spin weight of the field.
+    j : int
+        The spheroidal harmonic mode number.
+    m : int
+        The azimuthal harmonic mode number.
+    a : float
+        The black hole spin parameter.
+    omega : complex
+        The frequency of the mode.
+    la : complex
+        The spheroidal eigenvalue.
+
+    Returns
+    -------
+    complex
+        The renormalized angular momentum.
+    """
+    return nu_2_cython(s, j, m, a, omega, la)
 
 class RadialTeukolsky:
     """A class for solving the homogeneous radial Teukolsky equation.
@@ -378,4 +419,26 @@ class RadialTeukolsky:
         elif deriv == 2:
             return self.radialderivatives2(bc)
         else:
-            raise ValueError("RadialTeukolsky only solves up to the second derivative")
+            raise ValueError("RadialTeukolsky only solves up to the second derivative")
+        
+def hypergeo_2F1(a, b, c, x):
+    """
+    Gauss hypergeometric function 2F1(a, b; c; x). Note that this function is not very stable across the complex domain.
+    
+    Parameters
+    ----------
+    a : complex
+        The first parameter of the hypergeometric function.
+    b : complex
+        The second parameter of the hypergeometric function.
+    c : complex
+        The third parameter of the hypergeometric function.
+    x : complex
+        The argument of the hypergeometric function.
+
+    Returns
+    -------
+    complex
+        The value of the hypergeometric function 2F1(a, b; c; x).
+    """
+    return hypergeo_2F1_cython(a, b, c, x)

pybhpt/swsh.py

@@ -4,114 +4,133 @@ from scipy.special import sph_harm
 from scipy.special import binom
 from scipy.special import factorial
 import numpy as np
+from cybhpt_full import YslmCy, clebschCy, w3jCy
 
 """
 Wigner 3j-symbol and Clebsch-Gordon coefficients
 """
 
 def fac(n):
+    """
+    Computes the factorial of a non-negative integer n.
+
+    Parameters
+    ----------
+    n : int
+        A non-negative integer.
+
+    Returns
+    -------
+    float
+        The factorial of n.
+    """
     if n < 0:
         return 0
     return float(np.math.factorial(n))
 
-def Yslm(s, l, m, th):
+def Yslm(s, l, m, th, ph = None):
+    """
+    Evaluate the spin-weighted spherical harmonic $Y_{s}^{lm}$ at a given angle theta.
+
+    Parameters
+    ----------
+    s : int
+        The spin weight of the harmonic.
+    l : int
+        The angular number of the spherical harmonic.
+    m : int
+        The azimuthal number of the spherical harmonic.
+    th : array_like
+        The polar angle(s) at which to evaluate the spherical harmonic.
+
+    Returns
+    -------
+    array_like
+        The values of the spherical harmonic at the specified angles.
+    """
+    assert isinstance(s, int) and isinstance(l, int) and isinstance(m, int), "s, l, and m must be integers"
+    if ph is not None:
+        return Yslm(s, l, m, th)*np.exp(1.j*m*ph)
     if np.abs(s) > l:
         return 0.*th
     if s == 0:
         return np.real(sph_harm(m, l, 0., th))
     elif s + m < 0:
-        return (-1.)**(s+m)*YslmBase(-s, l, -m, np.cos(th))
-#     elif th > np.pi/2.:
-#         return (-1.)**(l + m)*YslmBase(-s, l, m, -np.cos(th))
+        return (-1.)**(s+m)*YslmBase(-s, l, -m, th)
+    else:
+        return YslmBase(s, l, m, th)
+
+def YslmBase(s, l, m, th):
+    assert isinstance(s, int) and isinstance(l, int) and isinstance(m, int), "s, l, and m must be integers"
+    if not isinstance(th, (int, float)):
+        b = np.broadcast(th)
+        out = np.empty(b.shape)
+        out.flat = [YslmCy(s, l, m, thi) for (thi,) in b]
     else:
-        return YslmBase(s, l, m, np.cos(th))
+        out = YslmCy(s, l, m, th)
+    return out
 
-def YslmBase(s, l, m, z):
-    rmax = l - s
-    pref = (0.5)**(l)*(-1.)**m*np.sqrt(factorial(l+m)/factorial(l+s)*factorial(l-m)/factorial(l-s)*(2*l+1)/(4.*np.pi))*np.sqrt(1. - z)**(s + m)*np.sqrt(1. + z)**(s - m)
-    
-    yslm = 0.*pref
-    for r in range(0, rmax + 1):
-        yslm += binom(l - s, r)*binom(l + s, r + s - m)*(z - 1.)**(rmax - r)*(z + 1.)**(r)
-    
-    return pref*yslm
+def Yslm_eigenvalue(s, l, *args):
+    return l*(l + 1.) - s*(s + 1.)
 
 def clebsch(l1, l2, l3, m1, m2, m3):
-    return (-1)**(l1 - l2 + m3)*np.sqrt(2*l3 + 1)*w3j(l1, l2, l3, m1, m2, -m3);
+    """
+    Compute the Clebsch-Gordon coefficient <l1,m1,l2,m2|l3,m3>.
+
+    Parameters
+    ----------
+    l1 : int
+        The angular number of the first state.
+    l2 : int
+        The angular number of the second state.
+    l3 : int
+        The angular number of the combined state.
+    m1 : int
+        The azimuthal number of the first state.
+    m2 : int
+        The azimuthal number of the second state.
+    m3 : int
+        The azimuthal number of the combined state.
+
+    Returns
+    -------
+    float
+        The Clebsch-Gordon coefficient <l1,m1,l2,m2|l3,m3>.
+    """
+    assert isinstance(l1, int) and isinstance(l2, int) and isinstance(l3, int), "l1, l2, and l3 must be integers"
+    assert isinstance(m1, int) and isinstance(m2, int) and isinstance(m3, int), "m1, m2, and m3 must be integers"
+    return clebschCy(l1, l2, l3, m1, m2, m3)
 
 def w3j(l1, l2, l3, m1, m2, m3):
-    if m1 + m2 + m3 != 0:
-        return 0
-    elif abs(l1 - l2) > l3:
-        return 0
-    elif l1 + l2 < l3:
-        return 0
-    
-    if abs(m1) > l1:
-        return 0
-    elif abs(m2) > l2:
-        return 0
-    elif abs(m3) > l3:
-        return 0
-    
-    sumTerm = w3j_tsum(l1, l2, l3, m1, m2, m3)
-    if sumTerm == 0:
-        return 0
-    sumSign = np.sign(sumTerm)
-    tempLog = 0.5*(np.log(fac(l1 + m1)) + np.log(fac(l2 + m2)) + np.log(fac(l3 + m3)))
-    tempLog += 0.5*(np.log(fac(l1 - m1)) + np.log(fac(l2 - m2)) + np.log(fac(l3 - m3)))
-    tempLog += np.log(triangle_coeff(l1, l2, l3))
-    tempLog += np.log(abs(sumTerm))
-    
-    temp = sumSign*np.exp(tempLog)
-    temp *= (-1)**(l1-l2-m3)
-    
-    return temp
-    
-def w3j_tsum(l1, l2, l3, m1, m2, m3):
-    t_min_num = w3j_t_min(l1, l2, l3, m1, m2, m3)
-    t_max_num = w3j_t_max(l1, l2, l3, m1, m2, m3)
-    x = 0
-    if t_max_num < t_min_num:
-        t_max_num = t_min_num
-
-    for t in range(t_min_num - 1, t_max_num + 2):
-        term = (fac(t)*fac(l3 - l2 + m1 + t)*fac(l3 - l1 - m2 + t)
-            *fac(l1 + l2 - l3 - t)*fac(l1 - t - m1)*fac(l2 - t + m2))
-        if term > 0:
-            x += (-1)**t/term
-    
-    return x
-
-def w3j_t_min(l1, l2, l3, m1, m2, m3):
-    temp = 0
+    """
+    Compute the Wigner 3j-symbol
+        | l1  l2  l3 |
+        | m1  m2  m3 |
+
+    Parameters
+    ----------
+    l1 : int
+        The angular number of the first state. 
+    l2 : int
+        The angular number of the second state.
+    l3 : int
+        The angular number of the combined state.
+    m1 : int
+        The azimuthal number of the first state.
+    m2 : int
+        The azimuthal number of the second state.
+    m3 : int
+        The azimuthal number of the combined state.
+
+    Returns
+    -------
+    float
+        The Wigner 3j-symbol $ \begin{pmatrix} l1 & l2 & l3 \\ m1 & m2 & m3 \end{pmatrix} $
+    """
+    assert isinstance(l1, int) and isinstance(l2, int) and isinstance(l3, int), "l1, l2, and l3 must be integers"
+    assert isinstance(m1, int) and isinstance(m2, int) and isinstance(m3, int), "m1, m2, and m3 must be integers"
+    return w3jCy(l1, l2, l3, m1, m2, m3)
     
-    comp = l3 - l2 + m1
-    if temp + comp < 0:
-        temp = -comp
-    comp = l3 - l1 - m2
-    if temp + comp < 0:
-        temp = -comp
-        
-    return temp
-
-def w3j_t_max(l1, l2, l3, m1, m2, m3):
-    temp = 1
-    comp = l1 + l2 - l3
-    if comp - temp > 0:
-        temp = comp
-    comp = l1 - m1
-    if comp - temp > 0:
-        temp = comp
-    comp = l2 + m2
-    if comp - temp > 0:
-        temp = comp
-        
-    return temp;
-
-def triangle_coeff(l1, l2, l3):
-    return np.sqrt(fac(l1 + l2 - l3)*fac(l3 + l1 - l2)*fac(l2 + l3 - l1)/fac(l1 + l2 + l3 + 1))
-
 """
 SWSH Eigenvalue Functions
 """
@@ -200,7 +219,7 @@ def swsh_eigs(s, l, m, g, nmax=None, return_eigenvectors=True):
     kval = l - lmin
     
     if nmax is None:
-        buffer = round(20 + 2*g)
+        buffer = round(20 + 2*np.abs(g))
         Nmax = kval + buffer + 2
     else:
         if nmax < kval:
@@ -213,26 +232,53 @@ def swsh_eigs(s, l, m, g, nmax=None, return_eigenvectors=True):
     
     return out
 
-def Yslm_eigenvalue(s, l, *args):
-    return l*(l + 1.) - s*(s + 1.)
+def swsh_coeffs(s, l, m, g, th):
+    if g == 0.:
+        return Yslm(s, l, m, th)
+    
+    _, eig = swsh_eigs(s, l, m, g, nmax=None, return_eigenvectors=True)
+    if g.imag == 0.:
+        coeffs = np.real(eig[l - max(abs(s), abs(m))])
+    else:
+        coeffs = eig[l - max(abs(s), abs(m))]
+    return coeffs
 
 def swsh_eigenvalue(s, l, m, g, nmax=None):
+    """
+    Compute the eigenvalue of the spin-weighted spheroidal harmonic.
+    
+    Parameters
+    ----------
+    s : int
+        The spin weight of the harmonic.
+    l : int
+        The angular number of the harmonic.
+    m : int
+        The azimuthal number of the harmonic.
+    g : float or complex
+        The spheroidicity parameter.
+    nmax : int, optional
+        The maximum number of basis functions to use in the computation. If None, a default value is chosen.
+
+    Returns
+    -------
+    float or complex
+        The eigenvalue of the spin-weighted spheroidal harmonic.
+    """
     if g == 0.:
         return Yslm_eigenvalue(s, l)
     
     las = swsh_eigs(s, l, m, g, nmax=nmax, return_eigenvectors=False)
     
-    return np.real(las[::-1][l - max(abs(s), abs(m))])
-
-def swsh_coeffs(s, l, m, g, th):
-    if g == 0.:
-        return Yslm(s, l, m, th)
-    
-    _, eig = swsh_eigs(s, l, m, g, nmax=None, return_eigenvectors=True)
-    coeffs = np.real(eig[l - max(abs(s), abs(m))])
-    
-    return np.real(eig[l - max(abs(s), abs(m))])
-        
+    idx = l - max(abs(s), abs(m))
+    sorted_indices = np.argsort(np.real(las))
+    if idx < 0 or idx >= len(sorted_indices):
+        raise IndexError(f"Index {idx} out of bounds for eigenvalue array of length {len(sorted_indices)}")
+    if g.imag == 0.:
+        eigen = np.real(las)[sorted_indices[idx]]
+    else:
+        eigen = las[sorted_indices[idx]]
+    return eigen
 class SWSHBase:
     def __init__(self, *args):
         arg_num = np.array(args).shape[0]
@@ -247,7 +293,9 @@ class SWSHBase:
 
         if arg_num > 3:
             self.spheroidicity = args[3]
-            
+        if self.spheroidicity.imag == 0:
+            self.spheroidicity = np.real(self.spheroidicity)
+
 class SWSHSeriesBase(SWSHBase):
     def __init__(self, s, l, m, g):
         SWSHBase.__init__(self, s, l, m, g)
@@ -259,7 +307,7 @@ class SWSHSeriesBase(SWSHBase):
         kval = self.l - self.lmin
     
         if nmax is None:
-            buffer = round(20 + 2*self.spheroidicity)
+            buffer = round(20 + np.abs(2*self.spheroidicity))
             Nmax = kval + buffer + 2
         else:
             if nmax < kval:
@@ -283,45 +331,115 @@ class SWSHSeriesBase(SWSHBase):
         return scipy.sparse.linalg.eigs(mat, **kwargs)
     
     def generate_eigenvalue(self):
-        las = np.real(self.eigs(return_eigenvectors=False))
-        pos = np.argsort(las)[self.l - self.lmin]
+        if self.spheroidicity.imag == 0.:
+            las = np.real(self.eigs(return_eigenvectors=False))
+        else:
+            las = self.eigs(return_eigenvectors=False)
+        pos = np.argsort(np.real(las))[self.l - self.lmin]
         return las[pos]
-    
+
     def generate_eigs(self):
         las, eigs = self.eigs()
-        pos = np.argsort(np.real(las))[self.l - self.lmin]
-        eigs_temp = np.real(eigs[:, pos])
-        eigs_return = np.sign(eigs_temp[self.l - self.lmin])*eigs_temp
-        return (np.real(las[pos]), eigs_return)
+        pos_vec = np.argsort(np.real(las))
+        pos = pos_vec[self.l - self.lmin]
+        if self.spheroidicity.imag == 0.:
+            eigs_temp = np.real(eigs[:, pos])
+            eigs_return = np.sign(eigs_temp[self.l - self.lmin])*eigs_temp
+            eig = np.real(las[pos])
+        else:
+            eigs_temp = eigs[:, pos]
+            ref = eigs_temp[self.l - self.lmin]
+            eigs_temp = eigs_temp/ref
+            eigs_norm = np.linalg.norm(eigs_temp)
+            eigs_return = eigs_temp/eigs_norm
+            eig = las[pos]
+        return (eig, eigs_return)
+class SpinWeightedSpheroidalHarmonic(SWSHSeriesBase):
+    """
+    A class for generating a spin-weighted spheroidal harmonic.
+
+    Parameters
+    ----------
+    s : int
+        The spin weight of the harmonic.
+    l : int
+        The angular number of the harmonic.
+    m : int
+        The azimuthal number of the harmonic.
+    g : float or complex
+        The spheroidicity parameter.
+
+    Attributes
+    ----------
+    couplingcoefficients : array_like
+        The coupling coefficients between the spin-weighted spheroidal harmonic and the spin-weighted spherical  
     
-class SWSH(SWSHSeriesBase):
+    """
     def __init__(self, s, l, m, g):
         SWSHSeriesBase.__init__(self, s, l, m, g)
         if self.spheroidicity == 0.:
             self.eval = self.Yslm
             self.eigenvalue = Yslm_eigenvalue(self.s, self.l)
-            self.coeffs = np.zeros(self.l - self.lmin)
+            self.coeffs = np.zeros(self.l - self.lmin + 1)
             self.coeffs[-1] = 1.
         else:
             self.eval = self.Sslm
             self.eigenvalue, self.coeffs = self.generate_eigs()
-            
+
+    @property
+    def couplingcoefficients(self):
+        return self.coeffs
+
     def Yslm(self, l, th):
+        """
+        Evaluate the spin-weighted spherical harmonic $Y_{s}^{lm}(theta)$ at a given angle theta.
+
+        Parameters
+        ----------
+        l : int
+            The angular number of the spherical harmonic.
+        th : array_like
+            The polar angle(s) at which to evaluate the spherical harmonic.
+
+        Returns
+        -------
+        array_like
+            The values of the spherical harmonic at the specified angles.
+        """
         return Yslm(self.s, l, self.m, th)
     
     def Sslm(self, *args):
+        """
+        Evaluate the spin-weighted spheroidal harmonic $S_{s}^{lm}(theta)$ at a given angle theta.
+
+        Parameters
+        ----------
+        th : array_like
+            The polar angle(s) at which to evaluate the spheroidal harmonic.
+        
+        Returns
+        -------
+        array_like
+            The values of the spheroidal harmonic at the specified angles.
+        """
         th = args[-1]
         term_num = self.coeffs.shape[0]
-        pts_num = th.shape[0]
-        Yslm_array = np.empty((term_num, pts_num))
+        if isinstance(th, (int, float)):
+            Yslm_array = np.empty(term_num)
+        else:
+            pts_num = th.shape[0]
+            Yslm_array = np.empty((term_num, pts_num))
         for i in range(term_num):
             Yslm_array[i] = self.Yslm(self.lmin + i, th)
             
         return np.dot(self.coeffs, Yslm_array)
             
-    def __call__(self, th):
-        return self.eval(self.l, th)
-    
+    def __call__(self, th, ph = None):
+        out = self.eval(self.l, th)
+        if ph is not None:
+            out = out*np.exp(1.j*self.m*ph)
+        return out
+
 def muCoupling(s, l):
     """
     Eigenvalue for the spin-weighted spherical harmonic lowering operator
@@ -332,6 +450,25 @@ def muCoupling(s, l):
     return np.sqrt((l - s + 1.)*(l + s))
 
 def Asjlm(s, j, l, m):
+    """
+    Coupling coefficient between scalar and spin-weighted spherical harmonics
+    
+    Parameters
+    ----------
+    s : int
+        The spin weight of the harmonic.
+    j : int
+        The angular number of the scalar harmonic.
+    l : int
+        The angular number of the spin-weighted harmonic.
+    m : int
+        The azimuthal number of the harmonics. 
+
+    Returns
+    -------
+    float
+        The coupling coefficient $A_{s}^{jlm}$
+    """
     if s >= 0:
         return (-1.)**(m + s)*np.sqrt(4**s*fac(s)**2*(2*l + 1)*(2*j + 1)/fac(2*s))*w3j(s, l, j, 0, m, -m)*w3j(s, l, j, s, -s, 0)
     else:

pybhpt/teuk.py

@@ -194,52 +194,243 @@ class TeukolskyMode:
     Flips the spin-weight and frequency of the Teukolsky solutions from :math:`s \rightarrow -s` and :math:`\omega \rightarrow -\omega`
     """
     def flipspinweightandfrequency(self):
+        """
+        Flips the spin-weight and frequency of the Teukolsky solutions from :math:`s \rightarrow -s` and :math:`\omega \rightarrow -\omega`
+        """
         self.base.flip_spinweight_frequency()
 
-    """
-    Spherical-spheroidal mixing coefficient between a spherical harmonic :math:`l` mode with a spheroidal :math:`j` mode
-
-    :param l: spherical harmonic mode
-    :type l: int
-    """
     def couplingcoefficient(self, l):
+        """
+        Spherical-spheroidal mixing coefficient between a spherical harmonic $l$ mode with a spheroidal $j$ mode.
+        
+        Parameters
+        ----------
+        l : int
+            Spherical harmonic mode.
+
+        Returns
+        -------
+        float
+            The coupling coefficient between the spherical harmonic mode `l` and the spheroidal harmonic mode `j`.
+        """
         return self.base.couplingcoefficient(l)
 
     def radialpoint(self, pos):
+        """
+        The radial point for the given position `pos`.
+
+        Parameters
+        ----------
+        pos : int
+            The radial position.
+        
+        Returns
+        -------
+        float
+            The radial point at the given position `pos`.
+        """
         return self.base.radialpoint(pos)
     
     def radialsolution(self, bc, pos):
+        """
+        The extended homogeneous radial solution for the given boundary condition `bc` and position `pos`.
+
+        Parameters
+        ----------
+        bc : str
+            The boundary condition, either "In" for ingoing or "Up" for upgoing.
+        pos : int
+            The radial position.
+
+        Returns
+        -------
+        complex
+            The radial solution at the given boundary condition `bc` and position `pos`.
+        """
         return self.base.radialsolution(bc, pos)
     
     def radialderivative(self, bc, pos):
+        """
+        The derivative of the extended homogeneous radial solution for the given boundary condition `bc` and position `pos`.
+
+        Parameters
+        ----------
+        bc : str
+            The boundary condition, either "In" for ingoing or "Up" for upgoing.
+        pos : int
+            The radial position.
+
+        Returns
+        -------
+        complex
+            The radial derivative at the given boundary condition `bc` and position `pos`.
+        """
         return self.base.radialderivative(bc, pos)
     
     def radialderivative2(self, bc, pos):
+        """
+        The second derivative of the extended homogeneous radial solution for the given boundary condition `bc` and position `pos`.
+
+        Parameters
+        ----------
+        bc : str
+            The boundary condition, either "In" for ingoing or "Up" for upgoing.
+        pos : int
+            The radial position.
+
+        Returns
+        -------
+        complex
+            The radial second derivative at the given boundary condition `bc` and position `pos`.
+        """
         return self.base.radialderivative2(bc, pos)
     
     def homogeneousradialsolution(self, bc, pos):
+        """
+        The homogeneous radial solution for the given boundary condition `bc` and position `pos`.
+
+        Parameters
+        ----------
+        bc : str
+            The boundary condition, either "In" for ingoing or "Up" for upgoing.
+        pos : int
+            The radial position.
+
+        Returns
+        -------
+        complex
+            The radial solution at the given boundary condition `bc` and position `pos`.
+        """
         return self.base.homogeneousradialsolution(bc, pos)
     
     def homogeneousradialderivative(self, bc, pos):
+        """
+        The radial derivative of the homogeneous radial solution for the given boundary condition `bc` and position `pos`.
+
+        Parameters
+        ----------
+        bc : str
+            The boundary condition, either "In" for ingoing or "Up" for upgoing.
+        pos : int
+            The radial position.
+
+        Returns
+        -------
+        complex
+            The radial derivative at the given boundary condition `bc` and position `pos`.
+        """
         return self.base.homogeneousradialderivative(bc, pos)
     
     def homogeneousradialderivative2(self, bc, pos):
+        """
+        The second radial derivative of the homogeneous radial solution for the given boundary condition `bc` and position `pos`.
+
+        Parameters
+        ----------
+        bc : str
+            The boundary condition, either "In" for ingoing or "Up" for upgoing.
+        pos : int
+            The radial position.
+
+        Returns
+        -------
+        complex
+            The radial second derivative at the given boundary condition `bc` and position `pos`.
+        """
         return self.base.homogeneousradialderivative2(bc, pos)
     
     def polarpoint(self, pos):
+        """
+        The polar point for the given position `pos`.
+
+        Parameters
+        ----------
+        pos : int
+            The polar position.
+
+        Returns
+        -------
+        float
+            The polar point at the given position `pos`.
+        """
         return self.base.polarpoint(pos)
     
     def polarsolution(self, pos):
+        """
+        The polar solution for the given position `pos`.
+
+        Parameters
+        ----------
+        pos : int
+            The polar position.
+
+        Returns
+        -------
+        float
+            The polar solution at the given position `pos`.
+        """
         return self.base.polarsolution(pos)
     
     def polarderivative(self, pos):
+        """
+        The derivative of the polar solution for the given position `pos`.
+
+        Parameters
+        ----------
+        pos : int
+            The polar position.
+
+        Returns
+        -------
+        float
+            The polar derivative at the given position `pos`.
+        """
         return self.base.polarderivative(pos)
     
     def polarderivative2(self, pos):
+        """
+        The second derivative of the polar solution for the given position `pos`.
+
+        Parameters
+        ----------
+        pos : int
+            The polar position.
+        
+        Returns
+        -------
+        float
+            The polar second derivative at the given position `pos`.
+        """
         return self.base.polarderivative2(pos)
     
     def amplitude(self, bc):
+        """
+        The Teukolsky amplitude for the given boundary condition `bc`.
+
+        Parameters
+        ----------
+        bc : str
+            The boundary condition, either "In" for ingoing or "Up" for upgoing.
+
+        Returns
+        -------
+        complex
+            The Teukolsky amplitude at the given boundary condition `bc`.
+        """
         return self.base.teukolsky_amplitude(bc)
     
     def precision(self, bc):
+        """
+        The precision of the Teukolsky amplitude for the given boundary condition `bc`.
+
+        Parameters
+        ----------
+        bc : str
+            The boundary condition, either "In" for ingoing or "Up" for upgoing.
+
+        Returns
+        -------
+        float
+            The precision of the Teukolsky amplitude at the given boundary condition `bc`.
+        """
         return self.base.teukolsky_amplitude_precision(bc)

{pybhpt-0.9.4.dist-info → pybhpt-0.9.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: pybhpt
-Version: 0.9.4
+Version: 0.9.8
 Summary: Black Hole Perturbation Theory and Self-Force Algorithms in Python
 Author-Email: Zach Nasipak <znasipak@gmail.com>
 License: GPL
@@ -30,11 +30,11 @@ Description-Content-Type: text/markdown
 
 # pybhpt
 
-A python package for solving problems in black hole perturbation theory
+A python package for solving problems in black hole perturbation theory. 
 
 `pybhpt` is a collection of numerical tools for analyzing perturbations of Kerr spacetime, particularly the self-forces and metric-perturbations experienced by small bodies moving in a Kerr background. Subpackages include: 
 
-- `pybhpt.geodesic`: a module that generates bound timelike geodesics in Kerr spacetime
+- `pybhpt.geodesic`: a module that generates bound periodic timelike geodesics in Kerr spacetime
 - `pybhpt.radial`: a module that calculates homogeneous solutions of the radial Teukolsky equation
 - `pybhpt.swsh`: a module that constructs the spin-weighted spheroidal harmonics
 - `pybhpt.teuk`: a module that evaluates the inhomogeneous solutions (Teukolsky amplitudes) of the radial Teukolsky equation due to a point-particle on a bound timelike Kerr geodesic
@@ -43,9 +43,11 @@ A python package for solving problems in black hole perturbation theory
 - `pybhpt.metric`: a module that produces the coefficients needed to reconstruct the metric from the Hertz potentials
 - `pybhpt.redshift`: a module that computes the generalized Detweiler redshift invariant in a variety of gauges
 
+See the [Documentation](https://pybhpt.readthedocs.io/en/latest/) pages for more information about the package, including User Guides and API. References and author information can be found at the bottom of the README.
+
 ## Quick Installation
 
-Tagged releases of `pybhpt` are available as wheel packages for macOS and 64-bit Linux on [PyPI](https://pypi.org/project/matplotlib/). Install using `pip`:
+Tagged releases of `pybhpt` are available as wheel packages for macOS and 64-bit Linux on [PyPI](https://pypi.org/project/pybhpt). Install using `pip`:
 ```
 python3 -m pip install pybhpt
 ```
@@ -130,6 +132,14 @@ To include the necessary compiler on Linux:
 conda install gcc_linux-64 gxx_linux-64
 ```
 
+## References
+
+Theoretical background for the code and explanations of the numerical methods used within are summarized in the references below: 
+
+- Z. Nasipak, *Metric reconstruction and the Hamiltonian for eccentric, precessing binaries in the small-mass-ratio limit* (2025) [arXiv:2507.07746](https://arxiv.org/abs/2507.07746)
+- Z. Nasipak, *An adiabatic gravitational waveform model for compact objects undergoing quasi-circular inspirals into rotating massive black holes*, Phys. Rev. D 109, 044020 (2024) [arXiv:2310.19706](https://arxiv.org/abs/2310.19706)
+- Z. Nasipak, *Adiabatic evolution due to the conservative scalar self-force during orbital resonances*, Phys. Rev. D 106, 064042 (2022) [arXiv:2207.02224](https://arxiv.org/abs/2207.02224)
+
 ## Authors
 
 Zachary Nasipak

pybhpt-0.9.8.dist-info/RECORD

@@ -0,0 +1,16 @@
+cybhpt_full.cpython-314-darwin.so,sha256=T01VDZVSdS3LaK3jBmOUblHdJHSlZiis9Q88mK5s108,2336832
+pybhpt-0.9.8.dist-info/RECORD,,
+pybhpt-0.9.8.dist-info/WHEEL,sha256=v0AHjqCAlR6lLK4uHrc9lGGk6wkSGzsPHIgpnvL7sa0,142
+pybhpt-0.9.8.dist-info/METADATA,sha256=NIzqGzLYfDWkON7jWb24fRxC7DbZzIrcdMYBF2iOWlA,6367
+pybhpt-0.9.8.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+pybhpt/geo.py,sha256=VqbarbR1CC7ARD82FI8vmoNnklCZUoraRVJOii3vBlE,23803
+pybhpt/redshift.py,sha256=ozDDbkv34FQ_Op3FotmHJ-J5Vfy2oF4_Ri1HRujnzAY,791
+pybhpt/hertz.py,sha256=9atjscxbR7eszsY6BuJvcy0PqlgMFwYI23kUIn4mUwc,13565
+pybhpt/radial.py,sha256=t9Lx6Cyuprxqk2iowbvHMvsoL-6UO-YnZmO1G1wdyMU,15597
+pybhpt/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pybhpt/swsh.py,sha256=sQR0S-tHXYaAIuuW9kHK99U39htXt5j8oGWPZzIqwt0,14826
+pybhpt/metric.py,sha256=y8ip24rFto7m7rZb0-fuYMrYUmbCzInaWQVYJRI3m3o,11971
+pybhpt/teuk.py,sha256=8rZ-2fyzAfTbt9T4-lkUL8wUmPpORv0VkJCfkpEBssc,13616
+pybhpt/flux.py,sha256=2ahStjbsswsWMNPfDiOlQIrzulJZrhaqoDENC0bCLE4,4299
+pybhpt/.dylibs/libgsl.28.dylib,sha256=cJ5srjDdZDNLeRXrwhARDtAVaHDiePifPX1yaR5KPgc,2439680
+pybhpt/.dylibs/libgslcblas.0.dylib,sha256=xxE7gWPfCeMMkYxciiJ0-IcSJqLwdfHVayP70bOxWL0,272784

{pybhpt-0.9.4.dist-info → pybhpt-0.9.8.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: scikit-build-core 0.11.5
+Generator: scikit-build-core 0.11.6
 Root-Is-Purelib: false
 Tag: cp314-cp314-macosx_14_0_x86_64
 Generator: delocate 0.13.0

pybhpt-0.9.4.dist-info/RECORD

@@ -1,16 +0,0 @@
-cybhpt_full.cpython-314-darwin.so,sha256=P1p69eiqGqqM1Y5QwYo75PF3Qufss1y2524M_1Xhxko,2286784
-pybhpt/geo.py,sha256=QyiwlXF0cIYSpkV7wC9-ITd2bqIumvXiIt2_uNlhJMc,12237
-pybhpt/redshift.py,sha256=ozDDbkv34FQ_Op3FotmHJ-J5Vfy2oF4_Ri1HRujnzAY,791
-pybhpt/hertz.py,sha256=9atjscxbR7eszsY6BuJvcy0PqlgMFwYI23kUIn4mUwc,13565
-pybhpt/radial.py,sha256=2H3rH4XczAVCbKveHmPO2wt3w8ApPZYWCAwkwnxPnps,13995
-pybhpt/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pybhpt/swsh.py,sha256=WjtpHNZ6c7RVxuml1I6_cEu8D6cb4hD6aiHZVwD7AeA,10462
-pybhpt/metric.py,sha256=y8ip24rFto7m7rZb0-fuYMrYUmbCzInaWQVYJRI3m3o,11971
-pybhpt/teuk.py,sha256=w3tcidkaOGeywZPqjggacYhxaFxgsxXdMlJ2C7TwdMQ,8220
-pybhpt/flux.py,sha256=2ahStjbsswsWMNPfDiOlQIrzulJZrhaqoDENC0bCLE4,4299
-pybhpt/.dylibs/libgsl.28.dylib,sha256=cJ5srjDdZDNLeRXrwhARDtAVaHDiePifPX1yaR5KPgc,2439680
-pybhpt/.dylibs/libgslcblas.0.dylib,sha256=xxE7gWPfCeMMkYxciiJ0-IcSJqLwdfHVayP70bOxWL0,272784
-pybhpt-0.9.4.dist-info/RECORD,,
-pybhpt-0.9.4.dist-info/WHEEL,sha256=IyDInmnGNwPAk8ERKOFXaEfq-LcK0Q6JmkeYwroJxhI,142
-pybhpt-0.9.4.dist-info/METADATA,sha256=EMPVuX-dje_Xt0axnmQHVeuax7rV66-dPzXO0_92ehc,5386
-pybhpt-0.9.4.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149