tv_gauge_residual#

t3toolbox.backend.tv_operations.tv_gauge_residual(frame, variations)#
def tv_gauge_residual(
        frame: typ.Tuple[
            typ.Sequence[NDArray],  # up_tucker_cores
            typ.Sequence[NDArray],  # down_tt_cores
            typ.Sequence[NDArray],  # left_tt_cores
            typ.Sequence[NDArray],  # right_tt_cores
        ],
        variations: typ.Tuple[
            typ.Sequence[NDArray],  # tucker_variations
            typ.Sequence[NDArray],  # tt_variations
        ],
) -> NDArray:  # shape = variation stack_shape (K+C); per stack element (scalar/0-d when unstacked)

Max violation of the gauge conditions for a tangent vector, per stack element.

The gauged tangent space requires each tucker variation orthogonal to its up-core, and each left-interior tt variation orthogonal to its left-core (see tv_orthogonal_gauge_projection()). Relative: the gauge grams U^T V / L^T H are divided by the coordinate norm of the WHOLE tangent (all variation cores, per stack element; U / L are orthonormal, so the ratio is in [0, 1], a zero tangent is trivially gauged, and a single vanishing core – e.g. the first TT variation at a rank-1 bond – does not divide noise by noise). Returns the max over the checks, reduced over the non-stack axes (shape = the variation stack K+C); a caller thresholds it against a RELATIVE tolerance. (Until 2026-08-22 this was the absolute max|U^T V|, which scales with the tangent: a correctly gauged tangent of norm >~1e8 – or >~50 on jax float32 – failed the safe-mode check, and a tiny ungauged one passed.)

Parameters:

  • frame (t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.typ.Sequence[NDArray], t3toolbox.backend.common.typ.Sequence[NDArray], t3toolbox.backend.common.typ.Sequence[NDArray], t3toolbox.backend.common.typ.Sequence[NDArray]])

  • variations (t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.typ.Sequence[NDArray], t3toolbox.backend.common.typ.Sequence[NDArray]])

Return type:

NDArray