fix: reject invalid constructor inputs (#333 — B5-B8, B13) (#440)

Closes #333. Phase 2 (PyAutoArray half) of the @rhayes777 API audit epic #415.

Five findings that were silently accepted now raise at construction, guarded at
chokepoints so coverage exceeds the five reported sites:

- B6 pixel_scales of 0.0 / negative / nan -> geometry_util.convert_pixel_scales_{1d,2d}
- B8 shape_native with a zero-length axis -> Mask2D.__init__
- B7 annulus with inner >= outer -> circular_annular and elliptical_annular
- B5 noise_map shape disagreeing with data -> AbstractDataset
- B13 negative regularization coefficient -> all 14 schemes, not only Constant

B13 closed a real leak: regularization_matrix_from squares the coefficient and
hides the sign, but regularization_weights_from returns it unsquared, so a
negative value fed negative regularization weights downstream.

The shared helper lives in autoarray/validate.py — the home decision this task
owned, which unblocks the PyAutoGalaxy#440 and PyAutoLens#532 siblings.

Guards are tracer-safe: gated on is_concrete_scalar, verified against real JAX
(construction under jax.jit works, jax.grad flows, concrete negatives rejected).

980 passed, +44 new tests, zero regressions.

Author: Jammy2211

autoarray/dataset/abstract/dataset.py

@@ -119,6 +119,25 @@ def __init__(
                     """
                 ) from e
 
+        # Guarding on the base class covers `Imaging`, `Interferometer` and every other
+        # dataset subclass. Array shapes are static under JAX, so no tracer gate is
+        # needed here (unlike the scalar guards in `autoarray.validate`).
+        data_shape = getattr(data, "shape_native", None)
+        noise_map_shape = getattr(noise_map, "shape_native", None)
+
+        if (
+            data_shape is not None
+            and noise_map_shape is not None
+            and tuple(data_shape) != tuple(noise_map_shape)
+        ):
+            raise exc.DatasetException(
+                f"noise_map must have the same shape as data; got data with "
+                f"shape_native {tuple(data_shape)!r} and noise_map with shape_native "
+                f"{tuple(noise_map_shape)!r}. Every fit quantity pairs a data value "
+                f"with its noise value pixel-by-pixel, so a mismatch has no "
+                f"well-defined meaning"
+            )
+
         self.noise_map = noise_map
 
         self.over_sample_size_lp = (

autoarray/geometry/geometry_util.py

@@ -2,6 +2,7 @@
 from typing import Tuple, Union
 
 from autoarray import type as ty
+from autoarray import validate
 
 
 def convert_shape_native_1d(shape_native: Union[int, Tuple[int]]) -> Tuple[int]:
@@ -46,8 +47,15 @@ def convert_pixel_scales_1d(pixel_scales: ty.PixelScales) -> Tuple[float]:
     -------
     Tuple[float]
         The pixel scale as a 1-element tuple `(float,)`.
+
+    Raises
+    ------
+    ValueError
+        If any entry is a concrete scalar which is not finite and above zero.
     """
 
+    validate.validate_pixel_scales(pixel_scales=pixel_scales)
+
     if type(pixel_scales) is float:
         pixel_scales = (pixel_scales,)
 
@@ -205,8 +213,21 @@ def convert_pixel_scales_2d(pixel_scales: ty.PixelScales) -> Tuple[float, float]
     -------
     Tuple[float, float]
         The pixel scale as a 2-element tuple `(float, float)`.
+
+    Raises
+    ------
+    ValueError
+        If any entry is a concrete scalar which is not finite and above zero.
+
+    Notes
+    -----
+    This is the single chokepoint every ``Mask2D`` factory and ``Grid2D.uniform``
+    funnel their ``pixel_scales`` through, so validating here covers them all rather
+    than repeating a guard at each construction site.
     """
 
+    validate.validate_pixel_scales(pixel_scales=pixel_scales)
+
     if type(pixel_scales) is float:
         pixel_scales = (pixel_scales, pixel_scales)
 

autoarray/inversion/regularization/abstract.py

@@ -2,10 +2,48 @@
 import numpy as np
 from typing import Optional, TYPE_CHECKING
 
+from autoarray import validate
+
 if TYPE_CHECKING:
     from autoarray.inversion.linear_obj.linear_obj import LinearObj
 
 
+def validate_coefficient(coefficient, name: str = "coefficient"):
+    """
+    Raise if a regularization coefficient is a concrete scalar which is negative or
+    non-finite.
+
+    Every regularization scheme calls this from its constructor, so the message for
+    this class of mistake is written once here rather than per scheme.
+
+    Zero is permitted: it is a degenerate but meaningful request for no regularization.
+    Negative is not, and is **not** inert despite appearances — see the note below.
+
+    Coefficients are free model parameters, so under a JAX-traced fit this receives a
+    tracer rather than a number. `autoarray.validate` gates on concreteness before
+    comparing, so the guard costs nothing inside a trace.
+
+    Parameters
+    ----------
+    coefficient
+        The regularization coefficient to validate.
+    name
+        The parameter's name, used in the error message (schemes with more than one
+        coefficient pass their own, e.g. ``inner_coefficient``).
+    """
+    validate.validate_non_negative_finite(
+        value=coefficient,
+        name=name,
+        extra=(
+            "A regularization coefficient sets the strength of the smoothing applied "
+            "to the reconstruction, which cannot be negative. A negative value is not "
+            "inert: `regularization_matrix_from` squares it, which hides the sign, but "
+            "`regularization_weights_from` returns it unsquared and so leaks negative "
+            "regularization weights into every consumer of that method"
+        ),
+    )
+
+
 class AbstractRegularization:
     is_split_regularization = False
     """

autoarray/inversion/regularization/adapt.py

@@ -6,6 +6,7 @@
     from autoarray.inversion.linear_obj.linear_obj import LinearObj
 
 from autoarray.inversion.regularization.abstract import AbstractRegularization
+from autoarray.inversion.regularization.abstract import validate_coefficient
 
 
 def adapt_regularization_weights_from(
@@ -193,7 +194,9 @@ def __init__(
 
         super().__init__()
 
+        validate_coefficient(coefficient=inner_coefficient, name="inner_coefficient")
         self.inner_coefficient = inner_coefficient
+        validate_coefficient(coefficient=outer_coefficient, name="outer_coefficient")
         self.outer_coefficient = outer_coefficient
         self.signal_scale = signal_scale
 

autoarray/inversion/regularization/adapt_split_zeroth.py

@@ -8,10 +8,12 @@
 from autoarray.inversion.regularization.adapt import Adapt
 from autoarray.inversion.regularization.brightness_zeroth import BrightnessZeroth
 from autoarray.inversion.regularization import regularization_util
+from autoarray.inversion.regularization.abstract import validate_coefficient
 
 
 class AdaptSplitZeroth(Adapt):
     is_split_regularization = True
+
     def __init__(
         self,
         zeroth_coefficient: float = 1.0,
@@ -77,6 +79,7 @@ def __init__(
             low signal regions.
         """
 
+        validate_coefficient(coefficient=zeroth_coefficient, name="zeroth_coefficient")
         self.zeroth_coefficient = zeroth_coefficient
         self.zeroth_signal_scale = zeroth_signal_scale
 

autoarray/inversion/regularization/brightness_zeroth.py

@@ -6,6 +6,7 @@
     from autoarray.inversion.linear_obj.linear_obj import LinearObj
 
 from autoarray.inversion.regularization.abstract import AbstractRegularization
+from autoarray.inversion.regularization.abstract import validate_coefficient
 
 
 def brightness_zeroth_regularization_weights_from(
@@ -104,6 +105,7 @@ def __init__(
 
         super().__init__()
 
+        validate_coefficient(coefficient=coefficient)
         self.coefficient = coefficient
         self.signal_scale = signal_scale
 

autoarray/inversion/regularization/constant.py

@@ -6,6 +6,7 @@
     from autoarray.inversion.linear_obj.linear_obj import LinearObj
 
 from autoarray.inversion.regularization.abstract import AbstractRegularization
+from autoarray.inversion.regularization.abstract import validate_coefficient
 
 
 def constant_regularization_matrix_from(
@@ -101,6 +102,7 @@ def __init__(self, coefficient: float = 1.0):
             The regularization coefficient which controls the degree of smooth of the inversion reconstruction.
         """
 
+        validate_coefficient(coefficient=coefficient)
         self.coefficient = coefficient
 
         super().__init__()

autoarray/inversion/regularization/constant_zeroth.py

@@ -6,6 +6,7 @@
     from autoarray.inversion.linear_obj.linear_obj import LinearObj
 
 from autoarray.inversion.regularization.abstract import AbstractRegularization
+from autoarray.inversion.regularization.abstract import validate_coefficient
 
 
 def constant_zeroth_regularization_matrix_from(
@@ -76,7 +77,11 @@ class ConstantZeroth(AbstractRegularization):
     def __init__(self, coefficient_neighbor=1.0, coefficient_zeroth=1.0):
         super().__init__()
 
+        validate_coefficient(
+            coefficient=coefficient_neighbor, name="coefficient_neighbor"
+        )
         self.coefficient_neighbor = coefficient_neighbor
+        validate_coefficient(coefficient=coefficient_zeroth, name="coefficient_zeroth")
         self.coefficient_zeroth = coefficient_zeroth
 
     def regularization_weights_from(self, linear_obj: LinearObj, xp=np) -> np.ndarray:

autoarray/inversion/regularization/curvature_mask.py

@@ -7,6 +7,7 @@
 
 from autoarray.inversion.regularization.abstract import AbstractRegularization
 from autoarray.operators import derivative_util
+from autoarray.inversion.regularization.abstract import validate_coefficient
 
 
 def curvature_reg_matrix_via_mask_from(mask, pixel_scale: float = 1.0) -> np.ndarray:
@@ -71,6 +72,7 @@ def __init__(self, coefficient: float = 1.0):
             The regularization coefficient which multiplies the matrix,
             setting the strength of the smoothing.
         """
+        validate_coefficient(coefficient=coefficient)
         self.coefficient = coefficient
 
         super().__init__()

autoarray/inversion/regularization/exponential_kernel.py

@@ -6,6 +6,7 @@
     from autoarray.inversion.linear_obj.linear_obj import LinearObj
 
 from autoarray.inversion.regularization.abstract import AbstractRegularization
+from autoarray.inversion.regularization.abstract import validate_coefficient
 
 
 def exp_cov_matrix_from(
@@ -110,6 +111,7 @@ def __init__(
             convention assumes ``C_ii ~ 1``, which holds for this unweighted kernel but not
             for the adaptive one; see :func:`apply_jitter` for why and when to switch.
         """
+        validate_coefficient(coefficient=coefficient)
         self.coefficient = coefficient
         self.scale = scale
         self.jitter = jitter