refactor(light): split multipole module + add ag.lp_linear variants

Refactors the multipole light profile module added in #420:

- autogalaxy/profiles/light/standard/multipole.py is split into per-class
  modules:
  - _multipole_mixin.py — private, holds the shared
    _LightProfileMultipoleMixin
  - sersic_multipole.py — SersicMultipole
  - gaussian_multipole.py — GaussianMultipole
- test_autogalaxy/profiles/light/standard/test_multipole.py is split into
  test_sersic_multipole.py + test_gaussian_multipole.py
- standard/__init__.py updated to the two new imports

Adds linear-light-profile counterparts:

- autogalaxy/profiles/light/linear/sersic_multipole.py
  ag.lp_linear.SersicMultipole(lp.SersicMultipole, LightProfileLinear)
  hardcodes intensity=1.0 (solved via inversion) and drops intensity from
  the constructor signature.
- autogalaxy/profiles/light/linear/gaussian_multipole.py — same pattern.
- linear/__init__.py exports both.
- test_autogalaxy/profiles/light/linear/test_sersic_multipole.py and
  test_gaussian_multipole.py cover: class identity (LightProfileLinear +
  the standard subclass), intensity-not-a-constructor-parameter,
  multipole_*_comps propagation, parity with the linear base profile at
  zero perturbation, and image parity with the standard variant at
  intensity=1.0.

Docs:
- docs/api/light.rst Linear [ag.lp_linear] section now lists
  SersicMultipole and GaussianMultipole.

895 unit tests pass. Follows up #418.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 2 people

autogalaxy/profiles/light/linear/__init__.py

@@ -6,6 +6,8 @@
 from .dev_vaucouleurs import DevVaucouleurs, DevVaucouleursSph
 from .sersic_core import SersicCore, SersicCoreSph
 from .exponential_core import ExponentialCore, ExponentialCoreSph
+from .sersic_multipole import SersicMultipole
+from .gaussian_multipole import GaussianMultipole
 from .shapelets.polar import ShapeletPolarSph, ShapeletPolar
 from .shapelets.cartesian import ShapeletCartesianSph, ShapeletCartesian
 from .shapelets.exponential import ShapeletExponentialSph, ShapeletExponential

autogalaxy/profiles/light/linear/gaussian_multipole.py

@@ -0,0 +1,53 @@
+"""
+Linear elliptical Gaussian light profile with m=3 and m=4 Fourier multipole
+perturbations on the eccentric radius.
+
+This is the linear-light-profile counterpart of ``autogalaxy.lp.GaussianMultipole``:
+``intensity`` is hardcoded to 1.0 in the constructor because it is solved
+analytically via the linear inversion at fit time.
+"""
+
+from typing import Tuple
+
+from autogalaxy.profiles.light.linear.abstract import LightProfileLinear
+
+from autogalaxy.profiles.light import standard as lp
+
+
+class GaussianMultipole(lp.GaussianMultipole, LightProfileLinear):
+    def __init__(
+        self,
+        centre: Tuple[float, float] = (0.0, 0.0),
+        ell_comps: Tuple[float, float] = (0.0, 0.0),
+        sigma: float = 1.0,
+        multipole_3_comps: Tuple[float, float] = (0.0, 0.0),
+        multipole_4_comps: Tuple[float, float] = (0.0, 0.0),
+    ):
+        """
+        The linear elliptical Gaussian light profile with m=3 and m=4 Fourier multipole
+        perturbations on the eccentric radius.
+
+        Parameters
+        ----------
+        centre
+            The (y,x) arc-second coordinates of the profile centre.
+        ell_comps
+            The first and second ellipticity components of the elliptical coordinate
+            system.
+        sigma
+            The sigma value of the Gaussian.
+        multipole_3_comps
+            The ``(cos, sin)`` components of the m=3 Fourier perturbation. Defaults to
+            ``(0.0, 0.0)`` which reduces the profile to ``lp_linear.Gaussian``.
+        multipole_4_comps
+            The ``(cos, sin)`` components of the m=4 Fourier perturbation. Defaults to
+            ``(0.0, 0.0)`` which reduces the profile to ``lp_linear.Gaussian``.
+        """
+        super().__init__(
+            centre=centre,
+            ell_comps=ell_comps,
+            intensity=1.0,
+            sigma=sigma,
+            multipole_3_comps=multipole_3_comps,
+            multipole_4_comps=multipole_4_comps,
+        )

autogalaxy/profiles/light/linear/sersic_multipole.py

@@ -0,0 +1,57 @@
+"""
+Linear elliptical Sersic light profile with m=3 and m=4 Fourier multipole
+perturbations on the eccentric radius.
+
+This is the linear-light-profile counterpart of ``autogalaxy.lp.SersicMultipole``:
+``intensity`` is hardcoded to 1.0 in the constructor because it is solved
+analytically via the linear inversion at fit time.
+"""
+
+from typing import Tuple
+
+from autogalaxy.profiles.light.linear.abstract import LightProfileLinear
+
+from autogalaxy.profiles.light import standard as lp
+
+
+class SersicMultipole(lp.SersicMultipole, LightProfileLinear):
+    def __init__(
+        self,
+        centre: Tuple[float, float] = (0.0, 0.0),
+        ell_comps: Tuple[float, float] = (0.0, 0.0),
+        effective_radius: float = 0.6,
+        sersic_index: float = 4.0,
+        multipole_3_comps: Tuple[float, float] = (0.0, 0.0),
+        multipole_4_comps: Tuple[float, float] = (0.0, 0.0),
+    ):
+        """
+        The linear elliptical Sersic light profile with m=3 and m=4 Fourier multipole
+        perturbations on the eccentric radius.
+
+        Parameters
+        ----------
+        centre
+            The (y,x) arc-second coordinates of the profile centre.
+        ell_comps
+            The first and second ellipticity components of the elliptical coordinate
+            system.
+        effective_radius
+            The circular radius containing half the light of this profile.
+        sersic_index
+            Controls the concentration of the profile.
+        multipole_3_comps
+            The ``(cos, sin)`` components of the m=3 Fourier perturbation. Defaults to
+            ``(0.0, 0.0)`` which reduces the profile to ``lp_linear.Sersic``.
+        multipole_4_comps
+            The ``(cos, sin)`` components of the m=4 Fourier perturbation. Defaults to
+            ``(0.0, 0.0)`` which reduces the profile to ``lp_linear.Sersic``.
+        """
+        super().__init__(
+            centre=centre,
+            ell_comps=ell_comps,
+            intensity=1.0,
+            effective_radius=effective_radius,
+            sersic_index=sersic_index,
+            multipole_3_comps=multipole_3_comps,
+            multipole_4_comps=multipole_4_comps,
+        )

autogalaxy/profiles/light/standard/__init__.py

@@ -13,7 +13,8 @@
     ElsonFreeFall,
     ElsonFreeFallSph,
 )
-from .multipole import SersicMultipole, GaussianMultipole
+from .sersic_multipole import SersicMultipole
+from .gaussian_multipole import GaussianMultipole
 from .shapelets.polar import ShapeletPolarSph, ShapeletPolar
 from .shapelets.cartesian import ShapeletCartesianSph, ShapeletCartesian
 from .shapelets.exponential import ShapeletExponentialSph, ShapeletExponential

autogalaxy/profiles/light/standard/_multipole_mixin.py

@@ -0,0 +1,68 @@
+"""
+Shared helper for light profiles with m=3 and m=4 Fourier perturbations on the
+eccentric radius.
+
+Used by ``SersicMultipole`` (``sersic_multipole.py``) and ``GaussianMultipole``
+(``gaussian_multipole.py``). The leading underscore signals "implementation
+detail" — when the future generalisation lands (a single wrapper-style multipole
+that perturbs any radial profile, unified with the ellipse-fitting API), this
+module will be replaced rather than evolved in-place.
+"""
+
+from typing import Tuple
+
+import numpy as np
+
+import autoarray as aa
+
+
+class _LightProfileMultipoleMixin:
+    """
+    Provides ``perturbed_radii_from`` to light profiles that:
+
+    - set ``multipole_3_comps`` and ``multipole_4_comps`` on ``self`` in ``__init__``
+    - inherit from a base profile providing ``eccentric_radii_grid_from``
+    """
+
+    multipole_3_comps: Tuple[float, float]
+    multipole_4_comps: Tuple[float, float]
+
+    def perturbed_radii_from(
+        self,
+        grid: aa.type.Grid2DLike,
+        xp=np,
+        **kwargs,
+    ) -> np.ndarray:
+        """
+        Returns the eccentric radii of ``grid`` perturbed by the m=3 and m=4 Fourier
+        multipoles, as a raw backend array (numpy or jax.numpy).
+
+        The perturbation is
+
+            r' = r * (1 + c_3 cos(3 theta) + s_3 sin(3 theta)
+                        + c_4 cos(4 theta) + s_4 sin(4 theta))
+
+        where ``theta = arctan2(y, x)`` is the polar angle in the profile's
+        elliptical reference frame (the grid is already in that frame after the
+        ``@aa.decorators.transform`` decorator on the caller's ``image_2d_from``).
+
+        Result is floored at 1e-8 to keep ``r ** (1/n)`` evaluations finite when a
+        large multipole component drives the radius through zero.
+        """
+        grid_radii = self.eccentric_radii_grid_from(grid=grid, xp=xp, **kwargs)
+        grid_radii_array = (
+            grid_radii.array if hasattr(grid_radii, "array") else grid_radii
+        )
+        y = grid.array[:, 0]
+        x = grid.array[:, 1]
+        theta = xp.arctan2(y, x)
+        c3, s3 = self.multipole_3_comps
+        c4, s4 = self.multipole_4_comps
+        perturbation = (
+            1.0
+            + c3 * xp.cos(3.0 * theta)
+            + s3 * xp.sin(3.0 * theta)
+            + c4 * xp.cos(4.0 * theta)
+            + s4 * xp.sin(4.0 * theta)
+        )
+        return xp.maximum(xp.multiply(grid_radii_array, perturbation), 1e-8)

autogalaxy/profiles/light/standard/gaussian_multipole.py

@@ -0,0 +1,96 @@
+"""
+Elliptical Gaussian light profile with m=3 and m=4 Fourier multipole perturbations
+applied to the eccentric radius before evaluating the Gaussian profile.
+
+With both ``multipole_*_comps`` set to ``(0.0, 0.0)`` (the default), the profile
+reduces exactly to ``Gaussian``.
+"""
+
+from typing import Optional, Tuple
+
+import numpy as np
+
+import autoarray as aa
+
+from autogalaxy.profiles.light.decorators import check_operated_only
+from autogalaxy.profiles.light.standard._multipole_mixin import (
+    _LightProfileMultipoleMixin,
+)
+from autogalaxy.profiles.light.standard.gaussian import Gaussian
+
+
+class GaussianMultipole(_LightProfileMultipoleMixin, Gaussian):
+    def __init__(
+        self,
+        centre: Tuple[float, float] = (0.0, 0.0),
+        ell_comps: Tuple[float, float] = (0.0, 0.0),
+        intensity: float = 0.1,
+        sigma: float = 1.0,
+        multipole_3_comps: Tuple[float, float] = (0.0, 0.0),
+        multipole_4_comps: Tuple[float, float] = (0.0, 0.0),
+    ):
+        """
+        The elliptical Gaussian light profile with m=3 and m=4 Fourier multipole
+        perturbations on the eccentric radius.
+
+        Parameters
+        ----------
+        centre
+            The (y,x) arc-second coordinates of the profile centre.
+        ell_comps
+            The first and second ellipticity components of the elliptical coordinate
+            system. The multipole perturbation is applied to the eccentric radius and
+            therefore follows this ellipticity.
+        intensity
+            Overall intensity normalisation of the light profile.
+        sigma
+            The sigma value of the Gaussian.
+        multipole_3_comps
+            The ``(cos, sin)`` components of the m=3 Fourier perturbation. Defaults to
+            ``(0.0, 0.0)`` which reduces the profile to ``Gaussian``.
+        multipole_4_comps
+            The ``(cos, sin)`` components of the m=4 Fourier perturbation. Defaults to
+            ``(0.0, 0.0)`` which reduces the profile to ``Gaussian``.
+        """
+        super().__init__(
+            centre=centre, ell_comps=ell_comps, intensity=intensity, sigma=sigma
+        )
+        self.multipole_3_comps = multipole_3_comps
+        self.multipole_4_comps = multipole_4_comps
+
+    def image_2d_via_radii_from(
+        self, grid_radii: np.ndarray, xp=np, **kwargs
+    ) -> np.ndarray:
+        """
+        Returns the 2D Gaussian image evaluated at the input radial values.
+
+        Unlike ``Gaussian.image_2d_via_radii_from``, this override accepts a raw backend
+        array (the output of ``perturbed_radii_from``) rather than an autoarray-wrapped
+        grid, since the perturbation step strips the wrapper.
+        """
+        return xp.multiply(
+            self._intensity,
+            xp.exp(
+                -0.5
+                * xp.square(
+                    xp.divide(grid_radii, self.sigma / xp.sqrt(self.axis_ratio(xp)))
+                )
+            ),
+        )
+
+    @aa.over_sample
+    @aa.decorators.to_array
+    @check_operated_only
+    @aa.decorators.transform
+    def image_2d_from(
+        self,
+        grid: aa.type.Grid2DLike,
+        xp=np,
+        operated_only: Optional[bool] = None,
+        **kwargs,
+    ) -> aa.Array2D:
+        """
+        Returns the 2D image of the multipole-perturbed Gaussian profile.
+        """
+        perturbed_radii = self.perturbed_radii_from(grid=grid, xp=xp, **kwargs)
+        return self.image_2d_via_radii_from(grid_radii=perturbed_radii, xp=xp, **kwargs)