autoarray.inversion.regularization.Adapt#

Bases: AbstractRegularization

Regularization which uses the neighbors of the mesh (e.g. shared Delaunay vertexes) and values adaptred to the data being fitted to smooth an inversion’s solution.

For the weighted regularization scheme, each pixel is given an ‘effective regularization weight’, which is applied when each set of pixel neighbors are regularized with one another. The motivation of this is that different regions of a pixelization’s mesh require different levels of regularization (e.g., high smoothing where the no signal is present and less smoothing where it is, see (Nightingale, Dye and Massey 2018)).

Unlike Constant regularization, neighboring pixels must now be regularized with one another in both directions (e.g. if pixel 0 regularizes pixel 1, pixel 1 must also regularize pixel 0). For example:

B = [-1, 1] [0->1]: [-1, -1] 1 now also regularizes 0

For Constant regularization this would NOT produce a positive-definite matrix. However, for the weighted scheme, it does!

The regularize weight_list change the B matrix as shown below - we simply multiply each pixel’s effective regularization weight by each row of B it has a -1 in, so:

regularization_weights = [1, 2, 3, 4]

B = [-1, 1, 0 ,0] # [0->1]: [0, -2, 2 ,0] # [1->2] [0, 0, -3 ,3] # [2->3] [4, 0, 0 ,-4] # [3->0]

If our -1’s werent down the diagonal this would look like:

B = [4, 0, 0 ,-4] # [3->0]: [0, -2, 2 ,0] # [1->2] [-1, 1, 0 ,0] # [0->1] [0, 0, -3 ,3] # [2->3] This is valid!

A full description of regularization and this matrix can be found in the parent AbstractRegularization class.

JAX & gradient support (2026-07 gradient sweep): as for Constant — JAX-differentiable and FD-certified on the rectangular mesh family (this is the rectangular production scheme), but raises TracerArrayConversionError on the Delaunay mesh family, whose neighbors come from a direct scipy call on the traced mesh grid (use AdaptSplit there). Note the defaults inner_coefficient == outer_coefficient == 1.0 make the weighting uniform — but not numerically identical to Constant(coefficient=1.0); see the coefficient-convention note below.

Coefficient convention (legacy, ``lambda^4``). The coefficients are squared twice before they reach the regularization matrix – once by adapt_regularization_weights_from and once by the matrix builder – so the matrix scales as the fourth power of the coefficient, while Constant scales as the second. Both carry the same LogUniform(1e-6, 1e6) prior, so this scheme explores a far wider effective smoothing range and reaches a numerically non positive-definite matrix from c ~ 1e4 where Constant survives to c ~ 1e6.

It is also 2x ``Constant``, not equal to it. The matrix builder scatters every mesh edge in both directions, and the neighbor list already holds each unordered edge twice, so each edge lands four times where Constant lands it twice. Adapt(inner_coefficient=1.0, outer_coefficient=1.0) is therefore exactly 2 x Constant(coefficient=1.0).

This behaviour is preserved deliberately: changing it would alter the coefficient scale of every adaptive fit ever run. New work should prefer ``AdaptPower``, which takes a power argument (default 1.0, giving the Constant-matching lambda^2 convention) and scatters each edge once, so AdaptPower(inner=outer=c) equals Constant(c) exactly and is more robust to gradient / NaN pathologies. The migration is c_new = c_old ** 2, and AdaptPower(power=2.0) reproduces this class’s coefficient scaling exactly.

Parameters:

coefficients – The regularization coefficients which controls the degree of smoothing of the inversion reconstruction in high and low signal regions of the reconstruction.
signal_scale (float) – A factor which controls how rapidly the smoothness of regularization varies from high signal regions to low signal regions.

Methods

`log_det_regularization_matrix_term_from`	Returns `log det H` of this scheme's regularization matrix computed from a factorization the scheme itself knows about, or `None` when no such shortcut exists (the default).
`regularization_matrix_from`	Returns the regularization matrix with shape [pixels, pixels].
`regularization_term_from`	Returns this scheme's contribution to the regularization term `s^T H s` computed from a factorization the scheme itself knows about, or `None` when no such shortcut exists (the default).
`regularization_weights_from`	Returns the regularization weights of this regularization scheme.

Attributes

is_split_regularization

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.

regularization_weights_from(linear_obj, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautolens/envs/latest/lib/python3.12/site-packages/numpy/__init__.py'>)[source]#

Returns the regularization weights of this regularization scheme.

The regularization weights define the level of regularization applied to each parameter in the linear object (e.g. the pixels in a Mapper).

For standard regularization (e.g. Constant) are weights are equal, however for adaptive schemes (e.g. Adapt) they vary to adapt to the data being reconstructed.

Parameters:: linear_obj (LinearObj) – The linear object (e.g. a Mapper) which uses these weights when performing regularization.
Return type:: The regularization weights.

regularization_matrix_from(linear_obj, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautolens/envs/latest/lib/python3.12/site-packages/numpy/__init__.py'>)[source]#

Returns the regularization matrix with shape [pixels, pixels].

Parameters:: linear_obj (LinearObj) – The linear object (e.g. a Mapper) which uses this matrix to perform regularization.
Return type:: The regularization matrix.