utv_operations
==============


.. py:module:: t3toolbox.backend.utv_operations

.. autoapi-nested-parse::

   Stateless tangent-stack reshuffles for the uniform tangent layer (UT3Tangent), uniform-fix 3b-1b.

   The uniform mirror of the ragged ``tv_operations`` stack/unstack helpers, for the ``.data`` layout
   ``(*supercores, shape, masks)`` with a leading mode index ``d`` and the stack at axes ``1 ..``. A uniform
   tangent's variations carry the full ``K + C`` stack (tangent stack ``K`` outermost, frame stack ``C``
   inner); the frame carries only ``C``. These functions split that stack into a Python tree of per-element
   objects and recombine -- a tree<->array conversion, NOT an axis permutation of the supercores. They are
   the backend the UT3Tangent ``unstack_tangents`` / ``unstack_frame`` / ``stack_tangents`` / ``stack_frame``
   / ``sum_tangents`` methods delegate to.

   Varying ranks across the frame ``C`` stack are first-class here (the rank-sweep use case): the per-element
   masks may differ, and ``utv_stack_frame_stack`` stacks frames of different ranks into one batch (the masks just
   ride along). Uniform rank is required only across ``K`` (one shared frame = one tangent space), which
   ``utv_stack_tangent_stack`` gets for free (the leaves share a frame). See
   ``docs/uniform_ranks_and_varieties.md``.



Functions
---------

.. toctree::
   :hidden:

   /autoapi/t3toolbox/backend/utv_operations/utv_unstack_tangent_stack
   /autoapi/t3toolbox/backend/utv_operations/utv_stack_tangent_stack
   /autoapi/t3toolbox/backend/utv_operations/utv_unstack_frame_stack
   /autoapi/t3toolbox/backend/utv_operations/utv_stack_frame_stack
   /autoapi/t3toolbox/backend/utv_operations/utv_sum_tangent_stack
   /autoapi/t3toolbox/backend/utv_operations/utv_to_ut3
   /autoapi/t3toolbox/backend/utv_operations/utv_retract
   /autoapi/t3toolbox/backend/utv_operations/utv_corewise_retract
   /autoapi/t3toolbox/backend/utv_operations/utv_corewise_inner
   /autoapi/t3toolbox/backend/utv_operations/utv_orthogonal_gauge_projection
   /autoapi/t3toolbox/backend/utv_operations/utv_oblique_gauge_projection
   /autoapi/t3toolbox/backend/utv_operations/utv_gauge_residual
   /autoapi/t3toolbox/backend/utv_operations/utv_project_ut3_onto_tangent_space
   /autoapi/t3toolbox/backend/utv_operations/utv_weighted_norm
   /autoapi/t3toolbox/backend/utv_operations/utv_weighted_inner

.. autoapisummary::

   t3toolbox.backend.utv_operations.utv_unstack_tangent_stack
   t3toolbox.backend.utv_operations.utv_stack_tangent_stack
   t3toolbox.backend.utv_operations.utv_unstack_frame_stack
   t3toolbox.backend.utv_operations.utv_stack_frame_stack
   t3toolbox.backend.utv_operations.utv_sum_tangent_stack
   t3toolbox.backend.utv_operations.utv_to_ut3
   t3toolbox.backend.utv_operations.utv_retract
   t3toolbox.backend.utv_operations.utv_corewise_retract
   t3toolbox.backend.utv_operations.utv_corewise_inner
   t3toolbox.backend.utv_operations.utv_orthogonal_gauge_projection
   t3toolbox.backend.utv_operations.utv_oblique_gauge_projection
   t3toolbox.backend.utv_operations.utv_gauge_residual
   t3toolbox.backend.utv_operations.utv_project_ut3_onto_tangent_space
   t3toolbox.backend.utv_operations.utv_weighted_norm
   t3toolbox.backend.utv_operations.utv_weighted_inner