UT3FrameWeights
===============

.. toctree::
   :hidden:

   /autoapi/t3toolbox/uniform_frame_variations_format/UT3FrameWeights.supercores
   /autoapi/t3toolbox/uniform_frame_variations_format/UT3FrameWeights.data
   /autoapi/t3toolbox/uniform_frame_variations_format/UT3FrameWeights.d
   /autoapi/t3toolbox/uniform_frame_variations_format/UT3FrameWeights.nU
   /autoapi/t3toolbox/uniform_frame_variations_format/UT3FrameWeights.nD
   /autoapi/t3toolbox/uniform_frame_variations_format/UT3FrameWeights.rL
   /autoapi/t3toolbox/uniform_frame_variations_format/UT3FrameWeights.rR
   /autoapi/t3toolbox/uniform_frame_variations_format/UT3FrameWeights.stack_shape
   /autoapi/t3toolbox/uniform_frame_variations_format/UT3FrameWeights.up_ranks
   /autoapi/t3toolbox/uniform_frame_variations_format/UT3FrameWeights.down_ranks
   /autoapi/t3toolbox/uniform_frame_variations_format/UT3FrameWeights.left_ranks
   /autoapi/t3toolbox/uniform_frame_variations_format/UT3FrameWeights.right_ranks
   /autoapi/t3toolbox/uniform_frame_variations_format/UT3FrameWeights.validate
   /autoapi/t3toolbox/uniform_frame_variations_format/UT3FrameWeights.__post_init__
   /autoapi/t3toolbox/uniform_frame_variations_format/UT3FrameWeights.__repr__
   /autoapi/t3toolbox/uniform_frame_variations_format/UT3FrameWeights.is_consistent_with
   /autoapi/t3toolbox/uniform_frame_variations_format/UT3FrameWeights.reciprocal
   /autoapi/t3toolbox/uniform_frame_variations_format/UT3FrameWeights.sqrt
   /autoapi/t3toolbox/uniform_frame_variations_format/UT3FrameWeights.concatenate
   /autoapi/t3toolbox/uniform_frame_variations_format/UT3FrameWeights.kronecker
   /autoapi/t3toolbox/uniform_frame_variations_format/UT3FrameWeights.from_ut3weights
   /autoapi/t3toolbox/uniform_frame_variations_format/UT3FrameWeights.from_t3frameweights
   /autoapi/t3toolbox/uniform_frame_variations_format/UT3FrameWeights.to_t3frameweights

.. py:class:: t3toolbox.uniform_frame_variations_format.UT3FrameWeights

   Diagonal weights defining a **metric on the tangent coordinates** of a :py:class:`UT3Frame` -- the
   uniform twin of :py:class:`~t3toolbox.frame_variations_format.T3FrameWeights`.

   Four families, each ``len=d`` (one per variation core), packed into supercores + a
   :py:class:`UT3VariationsMasks` holder: ``up`` (on ``H``'s ``nU`` leg), ``down`` (on ``V``'s ``nD``
   leg), ``left`` (``H``'s ``rL``), ``right`` (``H``'s ``rR``). Absorbed into the **variation**
   supercores, leaving the frame orthonormal and untouched -- so it is ``O(ranks)``.

   **Batching: a weight is FRAME-like** (it is *absorbed into* the variations, but it *batches with* the
   frame -- do not conflate the two). Every supercore is ``(d,) + C + (size,)`` where ``C`` is the
   **frame** stack, not the variations' ``K + C``: one metric per base point, shared by all ``K`` tangent
   vectors at that frame, broadcast over ``K`` for free (``C`` is innermost). There is no ``shape``
   field: weights live only on internal edges.

   .. rubric:: Examples

   >>> import numpy as np
   >>> import t3toolbox.tucker_tensor_train as t3
   >>> import t3toolbox.uniform_tucker_tensor_train as ut3
   >>> import t3toolbox.uniform_frame_variations_format as ubvf
   >>> import t3toolbox.uniform_manifold as ut3m
   >>> np.random.seed(0)
   >>> x  = t3.TuckerTensorTrain.randn((6, 7, 8), (2, 2, 2), (1, 2, 2, 1), stack_shape=(2,))
   >>> ux = ut3.UniformTuckerTensorTrain.from_t3(x)
   >>> frame, _ = ubvf.ut3_orthogonal_representations(ux)
   >>> v = ut3m.UNIFORM_COREWISE.randn(frame, stack_shape=(3,))   # 3 tangents at each of 2 base points
   >>> print(frame.stack_shape, v.stack_shape)            # C, then K + C
   (2,) (3, 2)

   The metric is built from the base point's singular values, so it carries ``C`` -- and pairs directly
   with the ``K``-stack of tangents there:

   >>> W = ubvf.UT3FrameWeights.from_ut3weights(ut3.UT3Weights.from_ut3svd(ux)).reciprocal()
   >>> print(W.stack_shape)                               # C, NOT K + C
   (2,)
   >>> print(np.asarray(v.weighted_norm(W)).shape)        # one norm per stacked tangent
   (3, 2)


   .. py:attribute:: up_weight_supercore
      :type:  t3toolbox.backend.common.NDArray


   .. py:attribute:: down_weight_supercore
      :type:  t3toolbox.backend.common.NDArray


   .. py:attribute:: left_weight_supercore
      :type:  t3toolbox.backend.common.NDArray


   .. py:attribute:: right_weight_supercore
      :type:  t3toolbox.backend.common.NDArray


   .. py:attribute:: masks
      :type:  UT3VariationsMasks

Methods
-------

.. autoapisummary::

   t3toolbox.uniform_frame_variations_format.UT3FrameWeights.supercores
   t3toolbox.uniform_frame_variations_format.UT3FrameWeights.data
   t3toolbox.uniform_frame_variations_format.UT3FrameWeights.d
   t3toolbox.uniform_frame_variations_format.UT3FrameWeights.nU
   t3toolbox.uniform_frame_variations_format.UT3FrameWeights.nD
   t3toolbox.uniform_frame_variations_format.UT3FrameWeights.rL
   t3toolbox.uniform_frame_variations_format.UT3FrameWeights.rR
   t3toolbox.uniform_frame_variations_format.UT3FrameWeights.stack_shape
   t3toolbox.uniform_frame_variations_format.UT3FrameWeights.up_ranks
   t3toolbox.uniform_frame_variations_format.UT3FrameWeights.down_ranks
   t3toolbox.uniform_frame_variations_format.UT3FrameWeights.left_ranks
   t3toolbox.uniform_frame_variations_format.UT3FrameWeights.right_ranks
   t3toolbox.uniform_frame_variations_format.UT3FrameWeights.validate
   t3toolbox.uniform_frame_variations_format.UT3FrameWeights.__post_init__
   t3toolbox.uniform_frame_variations_format.UT3FrameWeights.__repr__
   t3toolbox.uniform_frame_variations_format.UT3FrameWeights.is_consistent_with
   t3toolbox.uniform_frame_variations_format.UT3FrameWeights.reciprocal
   t3toolbox.uniform_frame_variations_format.UT3FrameWeights.sqrt
   t3toolbox.uniform_frame_variations_format.UT3FrameWeights.concatenate
   t3toolbox.uniform_frame_variations_format.UT3FrameWeights.kronecker
   t3toolbox.uniform_frame_variations_format.UT3FrameWeights.from_ut3weights
   t3toolbox.uniform_frame_variations_format.UT3FrameWeights.from_t3frameweights
   t3toolbox.uniform_frame_variations_format.UT3FrameWeights.to_t3frameweights