pybhpt 0.9.4__tar.gz → 0.9.5__tar.gz

pybhpt-0.9.5/.readthedocs.yml

@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.9"
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+sphinx:
+  configuration: docs/conf.py

{pybhpt-0.9.4 → pybhpt-0.9.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: pybhpt
-Version: 0.9.4
+Version: 0.9.5
 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.4 → pybhpt-0.9.5}/README.md

@@ -1,10 +1,10 @@
 # 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
@@ -13,9 +13,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
 ```
@@ -100,6 +102,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.4 → pybhpt-0.9.5}/build_gsl.sh

@@ -12,12 +12,15 @@ else
     CORES=$(sysctl -n hw.ncpu)
 fi
 
-# Download source
+# Download source (use mirror redirector + retries)
 mkdir -p /tmp/gsl-src
 cd /tmp/gsl-src
-curl -LO https://ftp.gnu.org/gnu/gsl/gsl-${GSL_VERSION}.tar.gz
-tar -xzf gsl-${GSL_VERSION}.tar.gz
-cd gsl-${GSL_VERSION}
+curl --fail --location --retry 5 --retry-delay 5 \
+    "https://ftpmirror.gnu.org/gsl/gsl-${GSL_VERSION}.tar.gz" \
+    -o "gsl-${GSL_VERSION}.tar.gz"
+
+tar -xzf "gsl-${GSL_VERSION}.tar.gz"
+cd "gsl-${GSL_VERSION}"
 
 # Build & install
 echo "Configuring GSL ${GSL_VERSION}..."

{pybhpt-0.9.4 → pybhpt-0.9.5}/cpp/include/swsh.hpp

@@ -86,7 +86,6 @@ int spectral_matrix(const int &s, const int &lmin, const int &m, const double &g
 int spectral_matrix_sparse_init(const int &s, const int &lmin, const int &m, const double &g, gsl_spmatrix* mat);
 int spectral_matrix_sparse(const int &s, const int &lmin, const int &m, const double &g, gsl_spmatrix* mat, const size_t &nmax);
 
-
 // Solve eigensystem of spectral matrix
 int spectral_solver(const int &s, const int &l, const int &m, const double &g, double& la, Vector& bvec);
 

{pybhpt-0.9.4 → pybhpt-0.9.5}/cpp/src/swsh.cpp

@@ -718,6 +718,7 @@ Complex Yslm(const int &s, const int &l, const int &m, const double &th, const d
 
 double Yslm(const int &s, const int &l, const int &m, const double &th){
 	if( s == 0 ) return Ylm(l, m, th);
+	if( th == 0.) return pow(-1, s)*Yslm(0, l, 0, 0.);
 
 	int lmin = std::max(std::abs(m), l - std::abs(s));
 	int lmax = l + std::abs(s);

pybhpt-0.9.5/cython/swsh_wrap.pyx

@@ -0,0 +1,70 @@
+from libcpp.vector cimport vector
+from libcpp.complex cimport complex as cpp_complex
+import numpy as np
+cimport numpy as np
+
+cdef extern from "gsl/gsl_errno.h":
+  void gsl_set_error_handler_off()
+
+# If you need to disable GSL error handling, do so in a targeted way within specific functions.
+# gsl_set_error_handler_off()  # Removed global call to avoid masking numerical errors.
+
+cdef extern from "swsh.hpp":
+    cdef cppclass SpinWeightedHarmonic:
+        SpinWeightedHarmonic(int s, int L, int m, double gamma, vector[double]& theta)
+
+        int getSpinWeight()
+        int getSpheroidalModeNumber()
+        int getAzimuthalModeNumber()
+        double getSpheroidicity()
+        double getEigenvalue()
+        vector[double] getCouplingCoefficient()
+        double getCouplingCoefficient(int l)
+        int getMinCouplingModeNumber()
+        int getMaxCouplingModeNumber()
+
+        int generateSolutionsAndDerivatives()
+        int generateCouplingCoefficients()
+        int generateSolutions()
+        int generateDerivatives()
+
+        vector[double] getArguments()
+        vector[double] getSolution()
+        vector[double] getDerivative()
+        vector[double] getSecondDerivative()
+
+        double getArguments(int pos)
+        double getSolution(int pos)
+        double getDerivative(int pos)
+        double getSecondDerivative(int pos)
+
+    double Asljm(int &s, int &l, int &j, int &m)
+    double dAsljm(int &s, int &l, int &j, int &m)
+
+    double clebsch(int &j1, int &j2, int &j, int &m1, int &m2, int &m)
+    double w3j(int &j1, int &j2, int &j, int &m1, int &m2, int &m)
+
+    cpp_complex[double] Sslm(int &s, int &l, int &m, double &g, double &th, double &ph)
+    double Sslm(int &s, int &l, int &m, double &g, double &th)
+
+    double Sslm(int &s, int &l, int &m, double &g, vector[double]& bvec, double &th)
+    double Sslm_derivative(int &s, int &l, int &m, double &g, vector[double]& bvec, double &th)
+    double Sslm_secondDerivative(int &s, int &l, int &m, double &g, double& la, double &th, double &Slm, double &SlmP)
+
+    double swsh_eigenvalue(int &s, int &l, int &m, double &g)
+
+    cpp_complex[double] Yslm(int &s, int &l, int &m, double &th, double &ph)
+    double Yslm(int &s, int &l, int &m, double &th) except +
+    double Yslm_derivative(int &s, int &l, int &m, double &th)
+
+def YslmCy(int s, int l, int m, double theta):
+  return Yslm(s, l, m, theta)
+
+def YslmCy_derivative(int s, int l, int m, double theta):
+  return Yslm_derivative(s, l, m, theta)
+
+def clebschCy(int j1, int j2, int j, int m1, int m2, int m):
+  return clebsch(j1, j2, j, m1, m2, m)
+
+def w3jCy(int j1, int j2, int j, int m1, int m2, int m):
+  return w3j(j1, j2, j, m1, m2, m)

{pybhpt-0.9.4 → pybhpt-0.9.5}/cython/teukolsky_wrap.pyx

@@ -7,6 +7,7 @@ cimport numpy as np
 # from geo_wrap cimport GeodesicSource
 include "geo_wrap.pyx"
 include "radialsolver_wrap.pyx"
+include "swsh_wrap.pyx"
 
 cdef extern from "teukolsky.hpp":
     cdef cppclass SpinWeightedHarmonic:

pybhpt-0.9.5/docs/Makefile

@@ -0,0 +1,12 @@
+# Clean target to remove build directory
+clean:
+	rm -rf _build
+# Minimal Sphinx Makefile
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+.PHONY: html
+html:
+	$(SPHINXBUILD) -b html $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS)

pybhpt-0.9.5/docs/about.md

@@ -0,0 +1,26 @@
+# About
+
+`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
+- [`pybhpt.geo`](pybhpt.geo): generates bound periodic timelike geodesics in Kerr spacetime
+- [`pybhpt.radial`](pybhpt.radial): calculates homogeneous solutions of the radial Teukolsky equation
+- [`pybhpt.swsh`](pybhpt.swsh): constructs the spin-weighted spheroidal harmonics
+- [`pybhpt.teuk`](pybhpt.teuk): evaluates inhomogeneous solutions (Teukolsky amplitudes) of the radial Teukolsky equation due to a point-particle on a bound timelike Kerr geodesic
+- [`pybhpt.flux`](pybhpt.flux): produces gravitational wave fluxes sourced by a point-particle on a generic bound timelike Kerr geodesic
+- [`pybhpt.hertz`](pybhpt.hertz): solves for the Hertz potentials for the CCK and AAB metric reconstruction procedures
+- [`pybhpt.metric`](pybhpt.metric): produces coefficients needed to reconstruct the metric from the Hertz potentials
+- [`pybhpt.redshift`](pybhpt.redshift): computes the generalized Detweiler redshift invariant in a variety of gauges
+
+One can find out more information about each module by exploring the User Guides or clicking on the subpackages, which are linked to the API.
+
+## 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.5/docs/background/geo.md

@@ -0,0 +1,76 @@
+# Geodesics in Kerr
+
+We work in a Kerr background with angular momentum and mass parameters $(J, M)$ and use Boyer-Lindquist coordinates $(t, r, \theta, \phi)$.
+
+Bound periodic timelike geodesics in Kerr spacetime are defined in terms of the turning points of the motion:
+
+- $r_\mathrm{min}$ : minimum Boyer-Lindquist radius
+- $r_\mathrm{max}$ : maximum Boyer-Lindquist radius
+- $\theta_\mathrm{min}$ : minimum Boyer-Lindquist polar angle
+- $\pi-\theta_\mathrm{min}$ : maximum Boyer-Lindquist polar angle
+
+From these we parametrize the geodesic in terms of the generalized Keplerian parameters:
+
+- $a$ : the dimensionless Kerr spin parameter
+- $p$ : the dimensionless semilatus rectum
+- $e$ : the orbital eccentricty
+- $x$ : cosine of the orbital inclination
+
+where $a = J/M^2$, $pM = 2r_\mathrm{max}r_\mathrm{min}/(r_\mathrm{min}+r_\mathrm{max})$ and $e = (r_\mathrm{max}-r_\mathrm{min})/(r_\mathrm{min}+r_\mathrm{max})$. The motion can also be described in terms of the conserved orbital constants:
+
+- $E$ : the specific orbital energy
+- $L_z$ : the specific orbital angular momentum
+- $Q$ : the Carter constant
+
+which have units $\{1, M, M^2\}$, respectively, along with the mass of the small body $\mu$.
+
+With these conserved quantities, we obtain four first-order ordinary differential equations (ODEs) for $x_p^\mu$, which decouple when parametrized in terms of the Mino(-Carter) time parameter $\lambda$,
+$$\begin{align}
+    \frac{dt_p}{d\lambda} &= V_{tr}(r_p) + V_{t\theta}(\theta_p),
+    \\
+    \frac{dr_p}{d\lambda} &= \pm \sqrt{V_r(r_p)},
+    \\ 
+    \frac{d\theta_p}{d\lambda} &= \pm \sqrt{V_\theta(\theta_p)},
+    \\
+    \frac{d\phi_p}{d\lambda} &= V_{\phi r}(r_p) + V_{\phi \theta}(\theta_p),
+\end{align}$$
+where $d\lambda = \Sigma^{-1} d\tau$, and the potential functions are given by
+$$\begin{align} 
+    V_{r}(r) &= { P^2(r) - \Delta\left(r^2 + {K} \right),} 
+    &
+    V_{\theta}(\theta) &= {{Q} - {L}_z^2 \cot^2\theta - a^2 (1 -{E}^2)\cos^2\theta,}
+    \\
+    V_{tr}(r) &= \frac{r^2+a^2}{\Delta}P(r), 
+    &
+    V_{t\theta}(\theta) &= a{L}_z - a^2 {E} \sin^2\theta, 
+    \\
+    V_{\phi r}(r) &= \frac{a}{\Delta}P(r), 
+    &
+    V_{\phi \theta}(\theta) &= {L}_z \csc^2\theta - a {E},
+\end{align}$$
+
+with $P(r) = (r^2+a^2){E} - a {L}_z$.
+
+The resulting bound solutions can be separated into terms that are periodic with respect to the Mino time radial and polar frequencies $\Upsilon_r$ and $\Upsilon_\theta$ and terms that grow secularly with the Mino time rates $\Upsilon_t$ and $\Upsilon_\phi$.
+Therefore, the fundamental coordinate time frequencies are given by
+$$\begin{align}
+    \Omega_r &= \frac{\Upsilon_r}{\Upsilon_t},
+    &
+    \Omega_\theta &= \frac{\Upsilon_\theta}{\Upsilon_t},
+    &
+    \Omega_\phi &= \frac{\Upsilon_\phi}{\Upsilon_t}.
+\end{align}$$
+
+We then represent the radial and polar motion by
+$$\begin{align}
+    r_p(\lambda) &= \Delta r^{(r)}(\Upsilon_r\lambda) = \Delta r^{(r)}(\Upsilon_r\lambda + 2\pi),
+    \\
+    \theta_p(\lambda) &= \Delta \theta^{(\theta)}(\Upsilon_\theta\lambda) = \Delta \theta^{(\theta)}(\Upsilon_\theta\lambda + 2\pi),
+\end{align}$$
+while time and azimuthal angle grow as
+$$\begin{align}
+    t_p(\lambda) &= \Upsilon_t \lambda + \Delta t^{(r)}(\Upsilon_r\lambda) + \Delta t^{(\theta)}(\Upsilon_\theta\lambda),
+    \\ 
+    \phi_p(\lambda) &= \Upsilon_\phi \lambda + \Delta \phi^{(r)}(\Upsilon_r\lambda) + \Delta \phi^{(\theta)}(\Upsilon_\theta\lambda),
+\end{align}$$
+where $\Delta t^{(r)}$, $\Delta \phi^{(r)}$, $\Delta t^{(\theta)}$, and $\Delta \phi^{(\theta)}$ are $2\pi$-periodic odd functions.

pybhpt-0.9.5/docs/background/radial.md

@@ -0,0 +1,38 @@
+# Radial Teukolsky equation
+
+The radial Teukolsky equation for spin-weight $s$, harmonic numbers $(j,m)$, frequency $\omega$, and $a$ the dimensionless Kerr spin parameter is given by
+$$\left[\Delta^{-s} \frac{d}{dr} \left(\Delta^{s+1} \frac{d }{dr}  \right) + \left(\frac{K^2-2is(r-M)K}{\Delta}+4is\omega r - \lambda_{sjm\omega} \right)\right]R_{sjm\omega} = T_{slm\omega},$$
+where $\Delta=r^2-2Mr+a^2$, $K=(r^2+a^2)\omega-ma$, $\lambda_{sjm\omega}$ is the spheroidal eigenvalue (separation constant), and $T_{slm\omega}$ is the radial decomposition of the source.
+
+## Homogeneous solutions
+
+For $T_{slm\omega} = 0$, we construct the homogeneous solutions $R^\mathrm{In}_{sjm\omega}$ and $R^\mathrm{Up}_{sjm\omega}$, which correspond to the asymptotic boundary conditions
+$$\begin{align}
+    R^\mathrm{In}_{sjm\omega} (r \rightarrow r_+) &\sim A^\mathrm{trans}_s \Delta^{-s} e^{-i k r_*},
+    \\
+    R^\mathrm{In}_{sjm\omega} (r \rightarrow \infty) &\sim A^\mathrm{ref}_s r^{-(2s+1)} e^{i\omega r_*}
+    + A^\mathrm{inc}_s r^{-1} e^{-i\omega r_*},
+    \\
+    R^\mathrm{Up}_{sjm\omega} (r \rightarrow r_+) &\sim B^\mathrm{ref}_s \Delta^{-s} e^{-i k r_*}
+    + B^\mathrm{inc}_s e^{i k r_*},
+    \\
+    R^\mathrm{Up}_{sjm\omega} (r \rightarrow \infty) &\sim 
+    B^\mathrm{trans}_s r^{-(2s+1)} e^{i\omega r_*},
+\end{align}$$
+where $k = \omega - m \omega_+$, $\omega_+ = a/(2Mr_+)$, and the tortoise coordinate is given by the differential relation $dr_{*}/dr = (r^2+a^2)/\Delta$, which can be immediately integrated, leading to
+$$r_* = r + \frac{r_+}{\kappa} \ln \frac{r-r_+}{2M} - \frac{r_-}{\kappa} \ln \frac{r-r_-}{2M},$$
+where $\kappa = \sqrt{1 - q^2}$ and $q = a/M$.
+
+## Inhomogeneous solutions
+
+Rather than constructing the full inhomogeneous solutions, we can instead construct the so-called *extended homogeneous solutions* for a point-particle source on a bound periodic geodesic,
+$$\begin{align}
+    \Psi_s &= \Psi_s^+ \Theta(r-r_p) + \Psi_s^- \Theta(r_p-r),
+    \\
+    \Psi_s^\pm &= \sum_{jmkn}\Psi^\pm_{sjmkn}(r)S_{sj\gamma_{mkn}}(\theta)e^{im\phi}e^{-i\omega_{mkn}t},
+\end{align}$$
+where we have the mode frequencies $\omega_{mkn} = m\Omega_\phi + k \Omega_\theta + n \Omega_r$, the discrete spheroidicity $\gamma_{mkn} = a\omega_{mkn}$, and the extended homogeneous radial solutions
+$$
+    \Psi^\pm_{sjmkn}(r) = Z^{\mathrm{Up/In}}_{sjmkn} R^{\mathrm{Up/In}}_{sjmkn}(r),
+$$
+with Teukolsky amplitudes $Z^{\mathrm{Up/In}}_{sjmkn}$.

pybhpt-0.9.5/docs/background/swsh.md

@@ -0,0 +1,42 @@
+# Angular Teukolsky equation
+
+The spin-weighted spheroidal harmonics $S_{sjm\gamma}(\theta)$ satisfy the equation
+$$
+	\left[\frac{1}{\sin\theta}\frac{d}{d\theta}\left(\sin\theta \frac{d}{d\theta} \right)
+	- \left(\gamma^2\sin^2\theta+\frac{(m+s\cos\theta)^2}{\sin^2\theta}
+	+2\gamma s\cos\theta-s-2m\gamma-\lambda_{sjm\gamma} \right)\right]S_{sjm\gamma} = 0,
+$$
+with eigenvalues $\lambda_{sjm\gamma}$ and spheroidicity $\gamma$. For the Teukolsky equation, $\gamma = a\omega$.
+
+The spheroidal harmonics can be expressed as rapidly convergent sums of spin-weighted spherical harmonics,
+$$
+    S_{sjm\gamma}(\theta)e^{im\phi} = \sum_{\ell = \ell_\mathrm{min}}^\infty b^{\ell}_{sjm\gamma} Y_{s\ell m}(\theta,\phi),
+$$
+where $\ell_\mathrm{min} = \mathrm{max}[|m|, |s|]$ and the coupling coefficients $b^{\ell}_{sjm\gamma}$ satisfy a five-term recursion relation. Similarly we can represent spin-weighted spherical harmonics as finite series of *scalar* spherical harmonics $Y_{lm}=Y_{0lm}$
+$$
+    Y_{s\ell m}(\theta)
+    = \sin^{-|s|}\theta \sum_{l=|m|}^\infty \mathcal{A}^l_{s\ell m} 
+    Y_{lm}(\theta),
+$$
+where the coefficients are given analytically in terms of the Wigner $3j$ symbol,
+$$\begin{align}
+	\mathcal{A}^l_{s\ell m} &= 
+	(-1)^{m+s(1+\mathrm{sgn}(s))/2} \mathcal{C}_{|s|\ell l}
+		\left(
+			\begin{array}{ccc}
+				|s| & \ell & l
+				\\
+				0 & m & -m
+			\end{array}
+		\right)
+		\left(
+			\begin{array}{ccc}
+				|s| & \ell & l
+				\\
+				s & -s & 0
+			\end{array}
+		\right),
+  \\
+  \mathcal{C}_{s\ell l}  &= \sqrt{\frac{4^{s} (s!)^2 (2\ell+1)(2l+1)}{(2s)!}}.
+\end{align}$$
+The selection rules of the $3j$-symbol mean that the coefficients vanish unless $\ell - |s| \leq l \leq \ell + |s|$.

pybhpt-0.9.5/docs/background/teuk.md

@@ -0,0 +1,42 @@
+# Teukolsky equation
+
+In Boyer-Lindquist coordinates $(t,r,\theta,\phi)$, the Teukolsky equation takes the form
+$$\begin{align}
+    \mathcal{O}^T_s \Psi_s = -4\pi \zeta\bar{\zeta} T_s,
+\end{align}$$
+where $\zeta=r-ia\cos\theta$, $T_s$ is the (tetrad-projected) source, and the spin-weighted Teukolsky operator is given by,
+$$\begin{align}
+    \mathcal{O}^T_s &:=-\left(\frac{(r^2+a^2)^2}{\Delta} - a^2 \sin^2\theta\right)\partial_t^2 - \frac{4 M a r}{\Delta} \partial_t \partial_\phi - \left(\frac{a^2}{\Delta} - \frac{1}{\sin^2\theta}\right)\partial_\phi^2
+    \\ 
+    & \qquad \qquad + \Delta^{-s}\partial_r\left(\Delta^{s+1} \partial_r\right) + \frac{1}{\sin\theta}\partial_\theta\left({\sin\theta}\partial_\theta \right) + 2s\left(\frac{M(r^2-a^2)}{\Delta} - r-ia\cos\theta \right)\partial_t
+    \\ \notag
+    & \qquad \qquad \qquad \qquad +2 s\left(\frac{a(r-M)}{\Delta}  - \frac{i\cos\theta}{\sin^2\theta} \right)\partial_\phi - s\left(\frac{s\cos^2\theta}{\sin^2\theta} - 1\right),
+\end{align}$$
+with $\Delta = r^2-2Mr+a^2$, and $\Psi_{0}=\Phi$ for scalar perturbations; $\Psi_{+1}=\phi_0$ and $\Psi_{-1}=\zeta^2\phi_2$ ; and $\Psi_{+2}=\psi_0$ and $\Psi_{-2}=\zeta^4\psi_4$ for gravitational perturbations.
+
+Transforming to the frequency domain, the fields and sources can be mode-decomposed into
+$$\begin{align}
+    \Psi_s = \int d\omega \sum_{jm} \Psi_{sjm\omega}(r) S_{sjm\gamma}(\theta) e^{im\phi} e^{-i\omega t},
+    \\
+    T_s = \int d\omega \sum_{jm} T_{sjm\omega}(r) S_{sjm\gamma}(\theta) e^{im\phi} e^{-i\omega t},
+\end{align}$$
+with $\gamma = a\omega$, leading to separated ODEs
+$$\left[\Delta^{-s} \frac{d}{dr} \left(\Delta^{s+1} \frac{d }{dr}  \right) + \left(\frac{K^2-2is(r-M)K}{\Delta}+4is\omega r - \lambda_{sjm\omega} \right)\right]R_{sjm\omega} = T_{slm\omega},$$
+and
+$$
+	\left[\frac{1}{\sin\theta}\frac{d}{d\theta}\left(\sin\theta \frac{d}{d\theta} \right)
+	- \left(\gamma^2\sin^2\theta+\frac{(m+s\cos\theta)^2}{\sin^2\theta}
+	+2\gamma s\cos\theta-s-2m\gamma-\lambda_{sjm\gamma} \right)\right]S_{sjm\gamma} = 0,
+$$
+with eigenvalues $\lambda_{sjm\gamma}$ and spheroidicity $\gamma$.
+
+The time-averaged rate of change of the orbital energy $\langle \dot{E}\rangle$, angular momentum $\langle \dot{L}_z\rangle$, and Carter constant $\langle \dot{Q}\rangle$ can then be expressed in terms of the Teukolsky amplitudes $Z^\mathrm{Up/In}_{sjmkn}$,
+$$ 
+\begin{align}
+\langle \dot{\mathcal{J}} \rangle & = \langle \dot{\mathcal{J}} \rangle^\mathrm{inf} + \langle \dot{\mathcal{J}} \rangle^\mathrm{hor},
+\\
+&= \sum_{jmkn} \langle \dot{\mathcal{J}} \rangle^\mathrm{inf/hor}_{jmkn},
+\\ 
+&= \sum_{jmkn} \alpha_{sjmkn}^{(\mathcal{J})\mathrm{inf/hor}}\left| Z^\mathrm{Up/In}_{sjmkn} \right|^2,
+\end{align}$$
+where $\mathcal{J} = (E, L_z, Q)$, $\alpha_{sjmkn}^{(\mathcal{J})\mathrm{inf}/\mathrm{hor}}$ are known coefficients, and $s=0, \pm 2$ produce either scalar or gravitational fluxes, respectively. 

pybhpt-0.9.5/docs/conf.py

@@ -0,0 +1,51 @@
+import os
+import sys
+import toml
+sys.path.insert(0, os.path.abspath('..'))
+
+project = 'pybhpt'
+copyright = '2025, znasipak'
+author = 'znasipak'
+
+# Read version from pyproject.toml
+pyproject_path = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', 'pyproject.toml'))
+with open(pyproject_path, 'r') as f:
+    pyproject = toml.load(f)
+release = pyproject['project']['version']
+
+extensions = ['sphinx.ext.autodoc',
+              'sphinx.ext.autosummary',
+              'myst_nb',
+              'sphinx.ext.viewcode',
+              'sphinx.ext.napoleon',]
+napoleon_use_ivar = True
+myst_enable_extensions = ["dollarmath", "amsmath"]
+nb_execution_mode = "off"
+autosummary_generate = True
+myst_dmath_double_inline = True
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+autodoc_default_options = {
+    'members': True,
+    'member-order': 'bysource',
+    'special-members': '__call__',
+    'undoc-members': True,
+    'exclude-members': '__weakref__'
+}
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_book_theme'
+html_static_path = ['_static']
+html_theme_options = {
+    "repository_url": "https://github.com/znasipak/pybhpt",
+    "use_repository_button": True,
+    "navbar_end": ["navbar-icon-links"],
+}
+html_title = "pybhpt"
+html_context = {
+    "default_mode": "light"
+}

pybhpt-0.9.5/docs/index.md

@@ -0,0 +1,67 @@
+# Welcome to pybhpt's documentation
+
+`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
+- [`pybhpt.geo`](pybhpt.geo): generates bound periodic timelike geodesics in Kerr spacetime
+- [`pybhpt.radial`](pybhpt.radial): calculates homogeneous solutions of the radial Teukolsky equation
+- [`pybhpt.swsh`](pybhpt.swsh): constructs the spin-weighted spheroidal harmonics
+- [`pybhpt.teuk`](pybhpt.teuk): evaluates inhomogeneous solutions (Teukolsky amplitudes) of the radial Teukolsky equation due to a point-particle on a bound timelike Kerr geodesic
+- [`pybhpt.flux`](pybhpt.flux): produces gravitational wave fluxes sourced by a point-particle on a generic bound timelike Kerr geodesic
+- [`pybhpt.hertz`](pybhpt.hertz): solves for the Hertz potentials for the CCK and AAB metric reconstruction procedures
+- [`pybhpt.metric`](pybhpt.metric): produces coefficients needed to reconstruct the metric from the Hertz potentials
+- [`pybhpt.redshift`](pybhpt.redshift): computes the generalized Detweiler redshift invariant in a variety of gauges
+
+One can find out more information about each module by exploring the [User Guides](#contents) or clicking on the subpackages, which are linked to the API. References and author information are provided in the [About](about) section.
+
+## Quick Installation
+
+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
+```
+Developers can compile from source using the instructions in [Installation](installation). User guides and documentation are provided below.
+
+## Contents
+
+```{toctree}
+:maxdepth: 1
+:caption: User Guides
+
+about
+installation
+notebooks/geodesics.ipynb
+notebooks/radial.ipynb
+notebooks/swsh.ipynb
+notebooks/teuk.ipynb
+notebooks/fluxes.ipynb
+notebooks/waveform.ipynb
+notebooks/tutorial.ipynb
+```
+
+```{toctree}
+:maxdepth: 1
+:caption: Background
+
+background/geo
+background/teuk
+background/radial
+background/swsh
+```
+
+```{toctree}
+:maxdepth: 1
+:caption: API Reference
+
+pybhpt.geo
+pybhpt.radial
+pybhpt.swsh
+pybhpt.teuk
+pybhpt.hertz
+pybhpt.flux
+pybhpt.metric
+pybhpt.redshift
+```
+
+## Authors
+Zachary Nasipak