probe_model
===========

.. py:function:: t3toolbox.fitting.probe_model(geometry, x, ww, residual, weight = None, regularizer = None)

   .. code-block:: python

      def probe_model(
              geometry,                            # MANIFOLD / COREWISE (or the UNIFORM_* twin for a uniform x)
              x:          typ.Union[t3.TuckerTensorTrain, ut3.UniformTuckerTensorTrain],   # the current point
              ww:         typ.Sequence[NDArray],   # probe vectors, len=d, elm_shape=W+(Ni,)
              residual:   typ.Sequence[NDArray],   # r = probe(x) − y, len=d, elm_shape=W+C+(Ni,)
              weight:     typ.Optional[typ.Any] = None,   # per-mode residual weight ω, 1-D (d,); None = 1 (unweighted)
              regularizer: typ.Any = None,         # optional regularizer, e.g. optimizers.IdentityRegularizer(λ)
      ) -> typ.Union[GaussNewtonModel, UniformGaussNewtonModel]:


   The Gauss-Newton model of a ``probe`` least-squares objective at ``x``, on ``geometry``.

   Like :py:func:`apply_model` but the measurements are **probes** -- vector-valued (one free mode each),
   so ``residual`` is a sequence of ``d`` arrays (``elm_shape = W+C+(Ni,)``). Optionally **per-mode**
   weighted: the objective is ``½ Σ_i ‖ω_i r_i‖²`` over the ``d`` per-mode probe residuals, so a 1-D
   weight ``ω`` of shape ``(d,)`` up- or down-weights each mode's data (e.g. inverse-scale / inverse-noise
   balancing). Plain probe has no order axis, so ``weight`` is a **1-D** per-mode vector (a 2-D ``(d, 1)``
   is rejected); for per-order weighting use :py:func:`probe_derivatives_model`.

   .. rubric:: Examples

   >>> import numpy as np
   >>> import t3toolbox.tucker_tensor_train as t3
   >>> import t3toolbox.manifold as t3m
   >>> import t3toolbox.fitting as fitting
   >>> np.random.seed(0)
   >>> x = t3.TuckerTensorTrain.randn((6, 7, 8), (2, 3, 2), (1, 2, 2, 1))
   >>> ww = [np.random.randn(15, N) for N in (6, 7, 8)]
   >>> r = [np.random.randn(15, N) for N in (6, 7, 8)]     # per-mode probe residual (a list of d)

   A per-mode weight down-weights mode 0 and up-weights mode 2 in the objective ``½ Σ_i ‖ω_i r_i‖²``:

   >>> model = fitting.probe_model(t3m.MANIFOLD, x, ww, r, weight=[0.5, 1.0, 2.0])
   >>> print(model.gradient.is_gauged())
   True
   >>> p = t3m.MANIFOLD.randn(model.frame)
   >>> bool(np.allclose(float(model.gn_quadratic(p)), float(p.corewise_inner(model.gn_hessian(p)))))
   True

   A 2-D weight is rejected -- plain probe has no order axis:

   >>> fitting.probe_model(t3m.MANIFOLD, x, ww, r, weight=[[0.5], [1.0], [2.0]])   # doctest: +IGNORE_EXCEPTION_DETAIL
   Traceback (most recent call last):
   ValueError: plain probe takes a 1-D per-mode residual weight of shape (d,)