uniform_least_squares_problem
=============================

.. py:function:: t3toolbox.backend.uniform_fitting.uniform_least_squares_problem(geometry, kind_name, x0, sample, data, order = None, weight = None, regularizer = None, chunk_size = 100)

   .. code-block:: python

      def uniform_least_squares_problem(
              geometry:  str,        # 'manifold' / 'corewise'
              kind_name: str,        # 'apply' / 'entries' / 'probe' (+ '_derivatives')
              x0:        typ.Any,    # UniformTuckerTensorTrain -- MINIMAL-rank frame (see uniform_minimal); masks captured
              sample:    typ.Any,    # ww / index / (ww, pp) / (index, pp) -- ragged or packed (packed once here)
              data:      typ.Any,    # observed S(x_true): scalar array (apply/entries) or a d-list/packed (probe)
              order:     typ.Optional[int] = None,  # derivative kinds only (required)
              weight:    typ.Optional[typ.Any] = None,  # residual weight ω: per-mode (probe) or ω[mode,order] (derivatives)
              regularizer: typ.Any = None,          # optional backend.regularization.Regularizer (e.g. IdentityRegularizer(λ))
              chunk_size: typ.Optional[int] = 100,  # probe_derivatives only: W-chunk size for 𝒥ᵀ (docs/chunking.md)
      ) -> bopt.Problem:


   Assemble a fully-packed uniform least-squares :py:class:`~t3toolbox.backend.optimizers.Problem`.

   Builds the uniform geometry (:py:func:`uniform_geometry_ops`) + sampling kind
   (:py:func:`uniform_sampling_kind` / :py:func:`uniform_derivatives_kind`) at ``x0``'s fixed rank, packs
   the loop-invariant ``sample`` + ``data`` once, and returns the reused backend ``Problem``. The optimizer
   then runs on the bare supercore pair ``(x0.data[0], x0.data[1])`` -- e.g.
   ``backend.optimizers.newton_cg(problem, (x0.data[0], x0.data[1]))``.

   **``x0`` must have minimal ranks** -- call :py:func:`uniform_minimal` first if it might not. A
   non-minimal nominal rank is unrealizable and would desync the retraction from the held masks
   mid-optimization; this is checked (structurally, cheap) and rejected up front rather than crashing
   later.

   .. rubric:: Examples

   >>> import numpy as np
   >>> import t3toolbox.tucker_tensor_train as t3
   >>> import t3toolbox.uniform_tucker_tensor_train as ut3
   >>> import t3toolbox.backend.optimizers as bopt
   >>> import t3toolbox.backend.uniform_fitting as uf
   >>> from t3toolbox.backend import apply as bapply
   >>> np.random.seed(0)
   >>> ww = [np.random.randn(20, n) for n in (6, 6, 6)]
   >>> data = np.random.randn(20)

   A **non-minimal** frame -- here TT bond rank 3 is unrealizable for a 2x2x2 central Tucker core (its TT
   bonds are at most 2) -- is rejected up front with a clear error:

   >>> x0 = ut3.UniformTuckerTensorTrain.from_t3(t3.TuckerTensorTrain.randn((6, 6, 6), (2, 2, 2), (1, 3, 3, 1)))
   >>> uf.uniform_least_squares_problem('manifold', 'apply', x0, ww, data)   # doctest: +IGNORE_EXCEPTION_DETAIL
   Traceback (most recent call last):
   ValueError: uniform_least_squares_problem requires a minimal-rank frame x0 ...

   :py:func:`uniform_minimal` reduces it to minimal ranks (the SAME tensor), and then it works:

   >>> x0m = uf.uniform_minimal(x0)
   >>> print(bool(np.allclose(x0m.to_dense(), x0.to_dense())))   # same tensor, minimal ranks
   True
   >>> prob = uf.uniform_least_squares_problem('manifold', 'apply', x0m, ww, data)
   >>> x_opt, stats = bopt.gradient_descent(prob, (x0m.data[0], x0m.data[1]), n_iter=5)
   >>> print(bool(stats['losses'][-1] < stats['losses'][0]))     # it descends
   True