fix: reject split regularization on rectangular meshes at construction (#417)

Rectangular meshes do not support split regularization -- their interpolators
provide no split-cross mappings. This was already documented in the workspace
prose ('Rectangular meshes use `Adapt`, not `AdaptSplit`') but never enforced,
so the combination failed deep inside the inversion in two different ways:

  RectangularUniform      -> AttributeError: 'InterpolatorRectangularUniform'
                             has no attribute '_mappings_sizes_weights_split'
  RectangularAdaptDensity -> IndexError: index 4 is out of bounds for axis 0
  RectangularAdaptImage      with size 4

Nine combinations were affected (3 rectangular meshes x 3 split schemes), not
the one reported.

`Pixelization` now rejects the pairing at construction, naming both the mesh
and the regularization, via two capability flags:
`AbstractMesh.supports_split_regularization` and
`AbstractRegularization.is_split_regularization`.

Also removes `InterpolatorRectangular._mappings_sizes_weights_split`, which
returned the plain 4-corner mappings on the reasoning that bilinear
interpolation already covers the neighbourhood. That was not correct --
`reg_split_from` expects the split-cross structure, which is what produced the
IndexError one frame later.

The exception is `autoarray.exc.PixelizationException`, deliberately NOT a
`FitException`: autogalaxy's same-named subclass IS one, and `fitness.py`
converts those into resample-rejects, which would make a search silently
discard every sample instead of reporting the misconfiguration.

Reported by @rhayes777 in #332. Phase 1 of #416 (epic #415).

Co-authored-by: Jammy2211 <JNightingale2211@gmail.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: 3 people

autoarray/inversion/mesh/interpolator/rectangular.py

@@ -456,9 +456,13 @@ def _mappings_sizes_weights(self):
 
         return mappings, sizes, weights
 
-    @cached_property
-    def _mappings_sizes_weights_split(self):
-        # Rectangular pixelizations use bilinear interpolation which already factors
-        # in the 4-corner neighbourhood, so no separate split-cross calculation is
-        # needed — split regularization reuses the same mappings.
-        return self._mappings_sizes_weights
+    # NOTE: `_mappings_sizes_weights_split` is deliberately NOT implemented here.
+    #
+    # It previously returned `self._mappings_sizes_weights` unchanged, on the reasoning that
+    # bilinear interpolation already factors in the 4-corner neighbourhood. That was not correct:
+    # `reg_split_from` expects the split-cross structure, so the pass-through raised
+    # `IndexError: index 4 is out of bounds for axis 0 with size 4` one frame later.
+    #
+    # Rectangular meshes do not support split regularization. The combination is now rejected at
+    # `Pixelization` construction via `AbstractMesh.supports_split_regularization`, which names
+    # both the mesh and the regularization instead of failing deep inside the inversion.

autoarray/inversion/mesh/mesh/abstract.py

@@ -9,6 +9,17 @@
 
 
 class AbstractMesh:
+    supports_split_regularization = True
+    """
+    Whether this mesh supports "split" regularization schemes (e.g. ``ConstantSplit``, ``AdaptSplit``,
+    ``AdaptSplitZeroth``).
+
+    Split schemes regularize using a split-cross calculation, which requires the mesh's interpolator to
+    provide ``_mappings_sizes_weights_split``. The adaptive meshes (``Delaunay``, ``KNNBarycentric``)
+    compute this; the rectangular meshes do not, and set this to ``False`` so that ``Pixelization``
+    rejects the combination at construction rather than failing deep inside the inversion.
+    """
+
     def __eq__(self, other):
         return self.__dict__ == other.__dict__ and self.__class__ is other.__class__
 

autoarray/inversion/mesh/mesh/rectangular_adapt_density.py

@@ -62,6 +62,10 @@ def overlay_grid_from(
 
 
 class RectangularAdaptDensity(AbstractMesh):
+    # Rectangular meshes do not support split regularization -- their interpolators provide no
+    # split-cross mappings. Inherited by `RectangularUniform` and `RectangularAdaptImage`.
+    supports_split_regularization = False
+
     def __init__(
         self,
         shape: Tuple[int, int] = (3, 3),

autoarray/inversion/pixelization.py

@@ -152,6 +152,30 @@ def __init__(
             model = af.Collection(galaxies=af.Collection(galaxy=galaxy))
         """
 
+        if (
+            regularization is not None
+            and getattr(regularization, "is_split_regularization", False)
+            and not getattr(mesh, "supports_split_regularization", True)
+        ):
+            raise exc.PixelizationException(
+                f"""
+                The regularization scheme `{type(regularization).__name__}` is a split regularization
+                scheme, which is not supported by the mesh `{type(mesh).__name__}`.
+
+                Split regularization regularizes using a cross of four points around each pixel centre,
+                which requires the mesh to provide split-cross mappings. The rectangular meshes
+                (`RectangularUniform`, `RectangularAdaptDensity`, `RectangularAdaptImage`) do not
+                provide them.
+
+                Use either:
+
+                - an adaptive mesh which supports split regularization, e.g. `Delaunay` or
+                  `KNNBarycentric`, with `{type(regularization).__name__}`; or
+                - a non-split regularization scheme with `{type(mesh).__name__}`, e.g. `Constant`
+                  instead of `ConstantSplit`, or `Adapt` instead of `AdaptSplit`.
+                """
+            )
+
         self.mesh = mesh
         self.regularization = regularization
 

autoarray/inversion/regularization/abstract.py

@@ -7,6 +7,17 @@
 
 
 class AbstractRegularization:
+    is_split_regularization = False
+    """
+    Whether this scheme is a "split" regularization variant, which regularizes using a split-cross
+    calculation of the mesh's mappings rather than the mappings themselves.
+
+    Split schemes require the mesh's interpolator to provide `_mappings_sizes_weights_split`, which
+    only the adaptive meshes (e.g. ``Delaunay``, ``KNNBarycentric``) do. ``Pixelization`` uses this
+    flag together with ``AbstractMesh.supports_split_regularization`` to reject unsupported
+    combinations at construction.
+    """
+
     def __init__(self):
         """
         Abstract base class for a regularization-scheme, which is applied to a pixelization to enforce a \

autoarray/inversion/regularization/adapt_split.py

@@ -11,6 +11,7 @@
 
 
 class AdaptSplit(Adapt):
+    is_split_regularization = True
     def __init__(
         self,
         inner_coefficient: float = 1.0,

autoarray/inversion/regularization/adapt_split_zeroth.py

@@ -11,6 +11,7 @@
 
 
 class AdaptSplitZeroth(Adapt):
+    is_split_regularization = True
     def __init__(
         self,
         zeroth_coefficient: float = 1.0,

autoarray/inversion/regularization/constant_split.py

@@ -11,6 +11,7 @@
 
 
 class ConstantSplit(Constant):
+    is_split_regularization = True
     def __init__(self, coefficient: float = 1.0):
         """
         Regularization which uses the derivatives at a cross of four points around each pixel centre and a single

test_autoarray/inversion/pixelization/test_split_regularization_support.py

@@ -0,0 +1,141 @@
+"""
+Regression tests for @rhayes777's audit finding in PyAutoArray#332.
+
+Rectangular meshes do not support split regularization -- their interpolators provide no
+split-cross mappings. Before the fix this surfaced two different ways, both deep inside the
+inversion and neither naming the real cause:
+
+- ``RectangularUniform``  -> ``AttributeError: 'InterpolatorRectangularUniform' object has no
+                              attribute '_mappings_sizes_weights_split'``
+- ``RectangularAdaptDensity`` / ``RectangularAdaptImage``
+                          -> ``IndexError: index 4 is out of bounds for axis 0 with size 4``
+                             (``InterpolatorRectangular`` returned the plain 4-corner mappings
+                             from a pass-through that claimed split "reuses the same mappings")
+
+``Pixelization`` now rejects the combination at construction. These tests assert the *clear
+failure*, not a successful fit -- the capability is deliberately absent.
+"""
+
+import pytest
+
+import autoarray as aa
+from autoarray import exc
+
+
+RECTANGULAR_MESHES = [
+    aa.mesh.RectangularUniform,
+    aa.mesh.RectangularAdaptDensity,
+    aa.mesh.RectangularAdaptImage,
+]
+
+SPLIT_REGULARIZATIONS = [
+    aa.reg.ConstantSplit,
+    aa.reg.AdaptSplit,
+    aa.reg.AdaptSplitZeroth,
+]
+
+ADAPTIVE_MESHES = [
+    aa.mesh.Delaunay,
+    aa.mesh.KNNBarycentric,
+]
+
+
+@pytest.mark.parametrize("mesh_cls", RECTANGULAR_MESHES)
+@pytest.mark.parametrize("regularization_cls", SPLIT_REGULARIZATIONS)
+def test__rectangular_mesh_with_split_regularization__raises(mesh_cls, regularization_cls):
+    """All 9 rectangular-mesh x split-regularization combinations are rejected."""
+
+    with pytest.raises(exc.PixelizationException) as error:
+        aa.Pixelization(
+            mesh=mesh_cls(shape=(15, 15)),
+            regularization=regularization_cls(),
+        )
+
+    message = str(error.value)
+
+    # the message must name both sides, so the user can act on it without a traceback
+    assert mesh_cls.__name__ in message
+    assert regularization_cls.__name__ in message
+
+
+@pytest.mark.parametrize("mesh_cls", RECTANGULAR_MESHES)
+def test__rectangular_mesh_with_non_split_regularization__is_allowed(mesh_cls):
+    """The guard is specific to split schemes; `Constant` on the same meshes still builds."""
+
+    pixelization = aa.Pixelization(
+        mesh=mesh_cls(shape=(15, 15)),
+        regularization=aa.reg.Constant(coefficient=1.0),
+    )
+
+    assert isinstance(pixelization.mesh, mesh_cls)
+
+
+@pytest.mark.parametrize("mesh_cls", ADAPTIVE_MESHES)
+@pytest.mark.parametrize("regularization_cls", SPLIT_REGULARIZATIONS)
+def test__adaptive_mesh_with_split_regularization__is_allowed(mesh_cls, regularization_cls):
+    """Split regularization remains supported on the meshes that implement it."""
+
+    pixelization = aa.Pixelization(
+        mesh=mesh_cls(pixels=100),
+        regularization=regularization_cls(),
+    )
+
+    assert isinstance(pixelization.mesh, mesh_cls)
+
+
+@pytest.mark.parametrize("mesh_cls", RECTANGULAR_MESHES)
+def test__rectangular_mesh_without_regularization__is_allowed(mesh_cls):
+    """`regularization` is optional; a `None` value must not trip the guard."""
+
+    pixelization = aa.Pixelization(mesh=mesh_cls(shape=(15, 15)))
+
+    assert pixelization.regularization is None
+
+
+def test__capability_flags():
+    """The flags the guard reads, asserted directly so a future mesh can't silently regress."""
+
+    assert aa.mesh.RectangularUniform(shape=(15, 15)).supports_split_regularization is False
+    assert aa.mesh.RectangularAdaptDensity(shape=(15, 15)).supports_split_regularization is False
+    assert aa.mesh.RectangularAdaptImage(shape=(15, 15)).supports_split_regularization is False
+    assert aa.mesh.Delaunay(pixels=100).supports_split_regularization is True
+    assert aa.mesh.KNNBarycentric(pixels=100).supports_split_regularization is True
+
+    assert aa.reg.ConstantSplit().is_split_regularization is True
+    assert aa.reg.AdaptSplit().is_split_regularization is True
+    assert aa.reg.AdaptSplitZeroth().is_split_regularization is True
+    assert aa.reg.Constant().is_split_regularization is False
+    assert aa.reg.Adapt().is_split_regularization is False
+
+
+def test__interpolator_rectangular_has_no_split_mappings():
+    """
+    The pass-through that produced the `IndexError` is gone and must stay gone -- restoring it
+    would reintroduce a silent-looking API that fails one frame later.
+    """
+
+    from autoarray.inversion.mesh.interpolator.rectangular import InterpolatorRectangular
+    from autoarray.inversion.mesh.interpolator.rectangular_uniform import (
+        InterpolatorRectangularUniform,
+    )
+    from autoarray.inversion.mesh.interpolator.delaunay import InterpolatorDelaunay
+
+    assert not hasattr(InterpolatorRectangular, "_mappings_sizes_weights_split")
+    assert not hasattr(InterpolatorRectangularUniform, "_mappings_sizes_weights_split")
+    assert hasattr(InterpolatorDelaunay, "_mappings_sizes_weights_split")
+
+
+def test__pixelization_exception_is_not_a_fit_exception():
+    """
+    An unsupported combination is a configuration error, not a bad model sample.
+
+    `autogalaxy.exc.PixelizationException` subclasses `af.exc.FitException`, which
+    `fitness.py` converts into a resample-reject. If the exception raised here were a
+    `FitException`, a search would silently reject every sample instead of reporting the
+    misconfiguration. `autoarray`'s own `PixelizationException` must stay a plain `Exception`.
+    """
+
+    assert issubclass(exc.PixelizationException, Exception)
+
+    af = pytest.importorskip("autofit")
+    assert not issubclass(exc.PixelizationException, af.exc.FitException)