T3FrameWeights
==============

.. toctree::
   :hidden:

   /autoapi/t3toolbox/frame_variations_format/T3FrameWeights.data
   /autoapi/t3toolbox/frame_variations_format/T3FrameWeights.d
   /autoapi/t3toolbox/frame_variations_format/T3FrameWeights.up_ranks
   /autoapi/t3toolbox/frame_variations_format/T3FrameWeights.down_ranks
   /autoapi/t3toolbox/frame_variations_format/T3FrameWeights.left_ranks
   /autoapi/t3toolbox/frame_variations_format/T3FrameWeights.right_ranks
   /autoapi/t3toolbox/frame_variations_format/T3FrameWeights.stack_shape
   /autoapi/t3toolbox/frame_variations_format/T3FrameWeights.validate
   /autoapi/t3toolbox/frame_variations_format/T3FrameWeights.__post_init__
   /autoapi/t3toolbox/frame_variations_format/T3FrameWeights.is_consistent_with
   /autoapi/t3toolbox/frame_variations_format/T3FrameWeights.reciprocal
   /autoapi/t3toolbox/frame_variations_format/T3FrameWeights.sqrt
   /autoapi/t3toolbox/frame_variations_format/T3FrameWeights.reverse
   /autoapi/t3toolbox/frame_variations_format/T3FrameWeights.concatenate
   /autoapi/t3toolbox/frame_variations_format/T3FrameWeights.kronecker
   /autoapi/t3toolbox/frame_variations_format/T3FrameWeights.unstack
   /autoapi/t3toolbox/frame_variations_format/T3FrameWeights.stack
   /autoapi/t3toolbox/frame_variations_format/T3FrameWeights.from_t3weights

.. py:class:: t3toolbox.frame_variations_format.T3FrameWeights

   Diagonal weights defining a **metric on the tangent coordinates** -- a Grasedyck-Kramer-style
   reweighting of the ``d`` variation directions (penalise poorly-informed ones with e.g. ``1/sigma``).

   Four families, each ``len=d`` (one per variation core, Approach-1 / metric-on-variations):
   ``up`` (on ``H``'s ``nU`` leg), ``down`` (on ``V``'s ``nD`` leg), ``left`` (``H``'s ``rL``),
   ``right`` (``H``'s ``rR``). :py:meth:`T3Tangent.weighted_norm` / :py:meth:`~T3Tangent.weighted_inner`
   absorb these into the variation cores and take the coordinate norm/inner -- the frame stays orthonormal
   and untouched.

   **Batching: a weight is FRAME-like** (it is *absorbed into* the variations, but it *batches with* the
   frame -- do not conflate the two). Every vector is ``stack_shape + (rank,)``, and that stack is the frame
   stack ``C``, like :py:class:`T3Frame` -- **not** the variations' ``K + C``: a weight is one metric per
   base point, shared by all ``K`` tangent vectors at that frame, and it broadcasts over ``K`` for free
   (``C`` is innermost). Pairing with variations alone follows the same trailing-stack rule as
   :py:func:`check_fv_pair` (the weight's stack is the trailing/inner part of the variation stack); at the
   tangent level, where the frame is present too, :py:func:`check_fw_pair` enforces the exact
   ``weights.stack_shape == frame.stack_shape``.


   .. py:attribute:: up_weights
      :type:  t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.NDArray, Ellipsis]


   .. py:attribute:: down_weights
      :type:  t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.NDArray, Ellipsis]


   .. py:attribute:: left_weights
      :type:  t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.NDArray, Ellipsis]


   .. py:attribute:: right_weights
      :type:  t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.NDArray, Ellipsis]

Methods
-------

.. autoapisummary::

   t3toolbox.frame_variations_format.T3FrameWeights.data
   t3toolbox.frame_variations_format.T3FrameWeights.d
   t3toolbox.frame_variations_format.T3FrameWeights.up_ranks
   t3toolbox.frame_variations_format.T3FrameWeights.down_ranks
   t3toolbox.frame_variations_format.T3FrameWeights.left_ranks
   t3toolbox.frame_variations_format.T3FrameWeights.right_ranks
   t3toolbox.frame_variations_format.T3FrameWeights.stack_shape
   t3toolbox.frame_variations_format.T3FrameWeights.validate
   t3toolbox.frame_variations_format.T3FrameWeights.__post_init__
   t3toolbox.frame_variations_format.T3FrameWeights.is_consistent_with
   t3toolbox.frame_variations_format.T3FrameWeights.reciprocal
   t3toolbox.frame_variations_format.T3FrameWeights.sqrt
   t3toolbox.frame_variations_format.T3FrameWeights.reverse
   t3toolbox.frame_variations_format.T3FrameWeights.concatenate
   t3toolbox.frame_variations_format.T3FrameWeights.kronecker
   t3toolbox.frame_variations_format.T3FrameWeights.unstack
   t3toolbox.frame_variations_format.T3FrameWeights.stack
   t3toolbox.frame_variations_format.T3FrameWeights.from_t3weights