require_unstacked_for_regularizer#

t3toolbox.backend.regularization.require_unstacked_for_regularizer(stack_shape, who)#
def require_unstacked_for_regularizer(
        stack_shape:  typ.Tuple[int, ...],   # C, from geom.stack_shape(x) / frame.stack_shape
        who:          str,                   # the calling operation, for the message
) -> None:

Structural guard: a regularized fit of a STACKED point is not implemented – raise, do not silently mis-weight.

The data misfit keeps the frame stack C (kind.sumsq returns one value per stack element) while every regularizer scalar collapses it – point_norm_sq and inner sum every axis. So objective = misfit + rho would broadcast the WHOLE-STACK regularization total onto each element, inflating the effective lambda by about |C| and doing it unevenly (the smallest-norm element takes the largest relative penalty). The regularizer gradient is per-element correct, which is what makes the inconsistency easy to miss.

Structural (a shape question), so it raises in both safety modes and is jit-safe – shapes are concrete at trace time. Unstacked fits, the overwhelmingly common case, are unaffected.

Parameters:

  • stack_shape (Tuple[int, ...])

  • who (str)

Return type:

None