fv_tied_variations_residual
===========================

.. py:function:: t3toolbox.backend.sharing.fv_tied_variations_residual(variations, shared_data, rcond = None)

   .. code-block:: python

      def fv_tied_variations_residual(
              variations:     typ.Tuple[
                  typ.Sequence[NDArray],  # tucker_variations. len=d, elm_shape=K+C+(nDi, Ni)
                  typ.Sequence[NDArray],  # tt_variations.     len=d, elm_shape=K+C+(rLi, nUi, rR(i+1))
              ],
              shared_data:    'SharedFrameData',  # the frame's companion (fv_shared_frame_data)
              rcond:          typ.Optional[float] = None,  # relative clip on the group spectrum; None -> dtype eps
      ) -> NDArray:  # shape = K + C; relative deviation per stack element (0 == already tied)


   How far a tangent's coordinates are from the TIED tangent subspace, per stack element.

   One **global Frobenius** ratio: ``||Pi_sh(V) - V||_F / ||V||_F``, with both norms taken over all
   ``d`` Tucker variation cores at once (sum of squares, then one square root) and the stack axes
   ``K + C`` kept. Only the Tucker variations can be untied -- the TT variations are unrestricted --
   so they alone enter the norm. Zero reference with a nonzero deviation gives ``inf``, branch-free,
   matching :py:func:`t3_sharing_residual`.

   This is the non-enforcing checker behind the shared geometry's TIED-tangent precondition. It costs
   one tied projection, which is strictly cheaper than the retraction it guards.

   .. rubric:: Examples

   >>> import numpy as np
   >>> import t3toolbox.tucker_tensor_train as t3
   >>> import t3toolbox.manifold as t3m
   >>> import t3toolbox.shared_geometry as sg
   >>> import t3toolbox.backend.sharing as sharing
   >>> np.random.seed(0)
   >>> sh = (0, 0, 1)
   >>> x = t3.TuckerTensorTrain.randn((6, 6, 5), (2, 2, 2), (1, 2, 2, 1)).share(sh)
   >>> geom = sg.shared_manifold(sh)
   >>> frame = geom.frame(x)
   >>> companion = geom.shared_frame_data(frame)

   A tangent produced by the shared geometry is already tied; a raw one from the base geometry is not:

   >>> tied = geom.randn(frame)
   >>> print(bool(sharing.fv_tied_variations_residual(tied.variations.data, companion) < 1e-12))
   True
   >>> raw = t3m.MANIFOLD.randn(frame)
   >>> print(bool(sharing.fv_tied_variations_residual(raw.variations.data, companion) > 0.1))
   True