docs: LaTeX docstrings for all mass profile classes

autogalaxy/profiles/mass/abstract/cse.py

@@ -4,6 +4,36 @@
 
 
 class MassProfileCSE(ABC):
+    r"""
+    Cored Steep Ellipsoid (CSE) decomposition mixin for mass profiles.
+
+    Provides the machinery to decompose an arbitrary projected convergence profile into
+    a sum of cored steep ellipsoid (CSE) basis functions, enabling analytic deflection
+    angle evaluation via Oguri (2021).
+
+    The 1-D CSE convergence basis function (Oguri 2021 Eq. 14) is:
+
+    .. math::
+
+        \kappa_{\rm CSE}(r; s) = \frac{1}{2(s^2 + r^2)^{3/2}}
+
+    where :math:`s` is the CSE core radius.  An arbitrary convergence profile
+    :math:`\kappa(r)` is approximated as:
+
+    .. math::
+
+        \kappa(r) \approx \sum_{j} A_j \, \kappa_{\rm CSE}(r; s_j)
+
+    The amplitudes :math:`A_j` and core radii :math:`s_j` are found by linear least
+    squares on a log-spaced radial grid.  The deflection angles of each CSE component
+    are computed analytically from Oguri (2021) Eq. 19–20, and the total deflection is
+    their sum.
+
+    References
+    ----------
+    - Oguri 2021, PASP, 133, 074504  (arXiv:2106.11464)
+    """
+
     @staticmethod
     def convergence_cse_1d_from(
         grid_radii: np.ndarray, core_radius: float, xp=np

autogalaxy/profiles/mass/abstract/mge.py

@@ -5,11 +5,31 @@
 
 
 class MGEDecomposer:
-    """
-    This class speeds up deflection angle calculations of certain mass profiles by decompositing them into many
-    Gaussians.
+    r"""
+    Multi-Gaussian Expansion (MGE) decomposer for arbitrary mass profiles.
+
+    Accelerates deflection-angle and convergence calculations by decomposing a mass
+    profile's projected convergence (or 3-D density) into a sum of Gaussian components,
+    each of which has an analytic deflection-angle formula via the Faddeeva (scaled
+    complementary error) function.
+
+    The decomposition of an arbitrary radial function :math:`f(\sigma)` into Gaussians
+    with amplitudes :math:`A_j` and widths :math:`\sigma_j` follows the numerical
+    contour-integration quadrature of Shajib (2019) Eq. 6:
+
+    .. math::
+
+        f(\sigma) \approx \sum_{j} A_j \exp\!\left(-\frac{r^2}{2\sigma_j^2}\right)
+
+    The deflection angles of each Gaussian component are then evaluated analytically via
+    the complex Faddeeva function :math:`w(z) = e^{-z^2}\,\mathrm{erfc}(-iz)`.
+
+    Supported ellipticity conventions for the scale-parameter :math:`\sigma` are
+    ``'major'``, ``'circularised'``, and ``'minor'`` (see :meth:`sigmas_factor_from`).
 
-    This follows the method of Shajib 2019 - https://academic.oup.com/mnras/article/488/1/1387/5526256
+    References
+    ----------
+    - Shajib 2019, MNRAS, 488, 1387  (arXiv:1906.08263)
     """
 
     def __init__(

autogalaxy/profiles/mass/dark/abstract.py

@@ -15,6 +15,36 @@ class DarkProfile:
 
 
 class AbstractgNFW(MassProfile, DarkProfile):
+    r"""
+    Abstract base class for generalised NFW (gNFW) dark matter halo profiles.
+
+    The three-dimensional density profile of the gNFW family is:
+
+    .. math::
+
+        \rho(r) = \frac{\rho_s}{(r/r_s)^{\gamma}(1 + r/r_s)^{3-\gamma}}
+
+    where :math:`\gamma` is the inner logarithmic slope (``inner_slope``), :math:`r_s` is
+    the scale radius, and :math:`\rho_s` is the characteristic density related to the
+    dimensionless convergence normalisation :math:`\kappa_s` via:
+
+    .. math::
+
+        \kappa_s = \frac{\rho_s \, r_s}{\Sigma_{\rm crit}}
+
+    The projected convergence is computed from this 3-D density via line-of-sight integration
+    using the auxiliary coordinate functions :math:`f(x)`, :math:`g(x)`, and :math:`h(x)`,
+    where :math:`x = \xi / r_s` and :math:`\xi` is the elliptical radius.
+
+    The standard NFW profile (:class:`NFW`) is recovered for :math:`\gamma = 1`.
+
+    References
+    ----------
+    - Navarro, Frenk & White 1996, ApJ, 462, 563
+    - Navarro, Frenk & White 1997, ApJ, 490, 493
+    - Wyithe, Turner & Spergel 2001, ApJ, 555, 504
+    """
+
     epsrel = 1.49e-5
 
     def __init__(

autogalaxy/profiles/mass/dark/cnfw.py

@@ -9,6 +9,29 @@
 
 
 class cNFW(AbstractgNFW):
+    r"""
+    Elliptical cored NFW (cNFW) dark matter halo profile.
+
+    The three-dimensional density profile introduces a constant-density core of
+    radius :math:`r_c` that suppresses the central cusp of the standard NFW profile:
+
+    .. math::
+
+        \rho(r) = \frac{\rho_0 \, r_s^3}{(r + r_c)(r + r_s)^2}
+
+    where :math:`r_c` is the core radius (``core_radius``) and :math:`r_s` is the
+    scale radius (``scale_radius``).  In the limit :math:`r_c \to 0` the profile
+    approaches the standard NFW density.
+
+    The convergence and deflection angles are computed via a Multi-Gaussian
+    Expansion (MGE) decomposition following Shajib (2019).
+
+    References
+    ----------
+    - Read, Agertz & Collins 2016, MNRAS, 459, 2573
+    - Shajib 2019, MNRAS, 488, 1387  (arXiv:1906.08263)
+    """
+
     def __init__(
             self,
             centre: Tuple[float, float] = (0.0, 0.0),
@@ -17,9 +40,7 @@ def __init__(
             scale_radius: float = 1.0,
             core_radius: float = 0.01,
     ):
-        """
-        Represents a cored NFW density distribution
-
+        r"""
         Parameters
         ----------
         centre
@@ -28,11 +49,11 @@ def __init__(
             The first and second ellipticity components of the elliptical coordinate system.
         kappa_s
             The overall normalization of the dark matter halo
-            (kappa_s = (rho_0 * D_d * scale_radius)/lensing_critical_density)
+            (:math:`\kappa_s = \rho_0 D_d r_s / \Sigma_{\rm crit}`).
         scale_radius
-            The cored NFW scale radius `theta_s`, as an angle on the sky in arcseconds.
+            The cored NFW scale radius :math:`r_s`, as an angle on the sky in arcseconds.
         core_radius
-            The cored NFW core radius `theta_c`, as an angle on the sky in arcseconds.
+            The cored NFW core radius :math:`r_c`, as an angle on the sky in arcseconds.
         """
 
         super().__init__(centre=centre, ell_comps=ell_comps)
@@ -103,27 +124,41 @@ def potential_2d_from(self, grid: aa.type.Grid2DLike, xp=np, **kwargs):
 
 
 class cNFWSph(cNFW):
+    r"""
+    Spherical cored NFW (cNFW) dark matter halo profile.
+
+    A special case of :class:`cNFW` with no ellipticity (:math:`q = 1`).  The 3-D
+    density and projected convergence follow the same cored-NFW expressions with
+    an analytic deflection-angle formula available for the spherical case:
+
+    .. math::
+
+        \rho(r) = \frac{\rho_0 \, r_s^3}{(r + r_c)(r + r_s)^2}
+
+    References
+    ----------
+    - Read, Agertz & Collins 2016, MNRAS, 459, 2573
+    """
+
     def __init__(
         self,
         centre: Tuple[float, float] = (0.0, 0.0),
         kappa_s: float = 0.05,
         scale_radius: float = 1.0,
         core_radius: float = 0.01,
     ):
-        """
-        Represents a spherical cored NFW density distribution
-
+        r"""
         Parameters
         ----------
         centre
             The (y,x) arc-second coordinates of the profile centre.
         kappa_s
             The overall normalization of the dark matter halo
-            (kappa_s = (rho_0 * D_d * scale_radius)/lensing_critical_density)
+            (:math:`\kappa_s = \rho_0 D_d r_s / \Sigma_{\rm crit}`).
         scale_radius
-            The cored NFW scale radius `theta_s`, as an angle on the sky in arcseconds.
+            The cored NFW scale radius :math:`r_s`, as an angle on the sky in arcseconds.
         core_radius
-            The cored NFW core radius `theta_c`, as an angle on the sky in arcseconds.
+            The cored NFW core radius :math:`r_c`, as an angle on the sky in arcseconds.
         """
 
         super().__init__(centre=centre, ell_comps=(0.0, 0.0))

autogalaxy/profiles/mass/dark/gnfw.py

@@ -8,6 +8,38 @@
 
 
 class gNFW(AbstractgNFW):
+    r"""
+    Elliptical generalised NFW (gNFW) dark matter halo profile with a free inner slope.
+
+    The three-dimensional density profile is:
+
+    .. math::
+
+        \rho(r) = \frac{\rho_s}{(r/r_s)^{\gamma}(1 + r/r_s)^{3-\gamma}}
+
+    where :math:`\gamma` is the inner logarithmic slope (``inner_slope``).  For
+    :math:`\gamma = 1` this reduces to the standard :class:`NFW` profile.
+
+    The projected convergence is computed by numerical line-of-sight integration:
+
+    .. math::
+
+        \kappa(\xi) = 2 \kappa_s \, (\xi/r_s)^{1-\gamma}
+        \left[
+            (1 + \xi/r_s)^{\gamma-3}
+            + (3 - \gamma) \int_0^1 \frac{(y + \xi/r_s)^{\gamma-4}
+            \left(1 - \sqrt{1 - y^2}\right)}{1} \, \mathrm{d}y
+        \right]
+
+    Deflection angles are computed via a Multi-Gaussian Expansion (MGE) decomposition
+    following Shajib (2019).
+
+    References
+    ----------
+    - Wyithe, Turner & Spergel 2001, ApJ, 555, 504
+    - Shajib 2019, MNRAS, 488, 1387  (arXiv:1906.08263)
+    """
+
     def deflections_yx_2d_from(self, grid: aa.type.Grid2DLike, xp=np, **kwargs):
         return self.deflections_2d_via_mge_from(grid=grid, xp=xp, **kwargs)
 
@@ -60,28 +92,41 @@ def integral_y(y, eta):
 
 
 class gNFWSph(gNFW):
+    r"""
+    Spherical generalised NFW (gNFW) dark matter halo profile with a free inner slope.
+
+    A special case of :class:`gNFW` with no ellipticity (:math:`q = 1`).  The 3-D
+    density and projected convergence follow the same gNFW expressions as the
+    elliptical variant but evaluated on a circular radial grid.
+
+    .. math::
+
+        \rho(r) = \frac{\rho_s}{(r/r_s)^{\gamma}(1 + r/r_s)^{3-\gamma}}
+
+    References
+    ----------
+    - Wyithe, Turner & Spergel 2001, ApJ, 555, 504
+    """
+
     def __init__(
         self,
         centre: Tuple[float, float] = (0.0, 0.0),
         kappa_s: float = 0.05,
         inner_slope: float = 1.0,
         scale_radius: float = 1.0,
     ):
-        """
-        The spherical NFW profiles, used to fit the dark matter halo of the lens.
-
+        r"""
         Parameters
         ----------
         centre
             The (y,x) arc-second coordinates of the profile centre.
         kappa_s
-            The overall normalization of the dark matter halo \
-            (kappa_s = (rho_s * scale_radius)/lensing_critical_density)
+            The overall normalization of the dark matter halo
+            (:math:`\kappa_s = \rho_s r_s / \Sigma_{\rm crit}`).
         inner_slope
-            The inner slope of the dark matter halo.
+            The inner logarithmic slope :math:`\gamma` of the dark matter density profile.
         scale_radius
-            The arc-second radius where the average density within this radius is 200 times the critical density of \
-            the Universe..
+            The NFW scale radius :math:`r_s`, as an angle on the sky in arcseconds.
         """
 
         super().__init__(