ut3_constructors
================


.. py:module:: t3toolbox.backend.ut3_constructors

.. autoapi-nested-parse::

   Constructors and file IO for uniform Tucker tensor trains (UT3), on the raw ``.data`` tuple.

   ``ut3_zeros`` / ``ut3_ones`` / ``ut3_corewise_randn`` build the padded supercores + masks **directly** (the
   uniform feature ragged round-tripping cannot express: ranks may vary per stack element -- the
   determinantal variety, ``docs/uniform_ranks_and_varieties.md``). ``ut3_save`` / ``ut3_load`` share
   ``common.save_core_families`` (2 supercores + 2 rank masks + the shape ints).

   There are deliberately **no** ``ut3_from_canonical`` / ``ut3_from_tensor_train`` / ``ut3_to_tensor_train``
   round-trips: they would take *ragged* CP/TT data and round-trip through ``TuckerTensorTrain``, which is
   ambiguous (ragged vs uniform input) and trivially composable from the existing ragged ops +
   ``UniformTuckerTensorTrain.from_t3`` / ``.to_t3``. Be explicit at the boundary instead.

   Following the layer-wide rule (``docs/contributor/uniform_pytree_composition.md``): **supercores (data) ->
   ``xnp``/``use_jax``; masks (structure) -> ``np`` (host)**. The pure constructors keep a ``use_jax``
   flag for the supercores (there is no array input to infer from). ``ut3_load`` keeps ``use_jax`` for the
   supercores but always returns numpy (host) bool masks.



Functions
---------

.. toctree::
   :hidden:

   /autoapi/t3toolbox/backend/ut3_constructors/ut3_zeros
   /autoapi/t3toolbox/backend/ut3_constructors/ut3_ones
   /autoapi/t3toolbox/backend/ut3_constructors/ut3_corewise_randn
   /autoapi/t3toolbox/backend/ut3_constructors/ut3_save
   /autoapi/t3toolbox/backend/ut3_constructors/ut3_load

.. autoapisummary::

   t3toolbox.backend.ut3_constructors.ut3_zeros
   t3toolbox.backend.ut3_constructors.ut3_ones
   t3toolbox.backend.ut3_constructors.ut3_corewise_randn
   t3toolbox.backend.ut3_constructors.ut3_save
   t3toolbox.backend.ut3_constructors.ut3_load