T3Weights
=========

.. toctree::
   :hidden:

   /autoapi/t3toolbox/tucker_tensor_train/T3Weights.validate
   /autoapi/t3toolbox/tucker_tensor_train/T3Weights.__post_init__
   /autoapi/t3toolbox/tucker_tensor_train/T3Weights.is_consistent_with
   /autoapi/t3toolbox/tucker_tensor_train/T3Weights.reciprocal
   /autoapi/t3toolbox/tucker_tensor_train/T3Weights.sqrt
   /autoapi/t3toolbox/tucker_tensor_train/T3Weights.reverse
   /autoapi/t3toolbox/tucker_tensor_train/T3Weights.concatenate
   /autoapi/t3toolbox/tucker_tensor_train/T3Weights.kronecker
   /autoapi/t3toolbox/tucker_tensor_train/T3Weights.unstack
   /autoapi/t3toolbox/tucker_tensor_train/T3Weights.stack
   /autoapi/t3toolbox/tucker_tensor_train/T3Weights.from_t3svd

.. py:class:: t3toolbox.tucker_tensor_train.T3Weights

   Diagonal weights on the internal edges of a :py:class:`TuckerTensorTrain` -- one vector per edge.

   A weight is a diagonal matrix inserted on a network edge (stored as its diagonal vector). Two edge
   families: **Tucker-rank** edges ``nᵢ`` (between each Tucker factor and its TT core, ``len=d``) and
   **TT-bond** edges ``rᵢ`` (between neighbouring TT cores, ``len=d+1``, ends ``r₀=r_d=1``). The
   represented tensor is ``absorb_weights(x, W).to_dense()``; the plain (unweighted) network norm squares
   the inserted diagonal, so ``diag(1/σ)`` penalises by ``1/σ²``. Batching mirrors ``TuckerTensorTrain``:
   every vector is ``stack_shape + (rank,)`` (the frame/core stack ``C``); one object holds a stack of
   weights.

   .. rubric:: Examples

   >>> import numpy as np
   >>> import t3toolbox.tucker_tensor_train as t3
   >>> np.random.seed(0)
   >>> x = t3.TuckerTensorTrain.randn((6, 7, 8), (2, 2, 2), (1, 2, 2, 1))   # minimal ranks
   >>> W = t3.T3Weights.from_t3svd(x)          # the singular values are the canonical weight object
   >>> print(W.tucker_ranks, W.tt_ranks)
   (2, 2, 2) (1, 2, 2, 1)
   >>> print(W.is_consistent_with(x))
   True
   >>> xw = t3.t3_absorb_weights(x, W)            # shape-preserving; ranks unchanged
   >>> print(xw.ranks == x.ranks)
   True


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


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


   .. py:property:: data
      :type: Tuple[Tuple[t3toolbox.backend.common.NDArray, Ellipsis], Tuple[t3toolbox.backend.common.NDArray, Ellipsis]]



   .. py:property:: d
      :type: int



   .. py:property:: tucker_ranks
      :type: Tuple[int, Ellipsis]



   .. py:property:: tt_ranks
      :type: Tuple[int, Ellipsis]



   .. py:property:: stack_shape
      :type: Tuple[int, Ellipsis]


Methods
-------

.. autoapisummary::

   t3toolbox.tucker_tensor_train.T3Weights.validate
   t3toolbox.tucker_tensor_train.T3Weights.__post_init__
   t3toolbox.tucker_tensor_train.T3Weights.is_consistent_with
   t3toolbox.tucker_tensor_train.T3Weights.reciprocal
   t3toolbox.tucker_tensor_train.T3Weights.sqrt
   t3toolbox.tucker_tensor_train.T3Weights.reverse
   t3toolbox.tucker_tensor_train.T3Weights.concatenate
   t3toolbox.tucker_tensor_train.T3Weights.kronecker
   t3toolbox.tucker_tensor_train.T3Weights.unstack
   t3toolbox.tucker_tensor_train.T3Weights.stack
   t3toolbox.tucker_tensor_train.T3Weights.from_t3svd