optimizers
==========


.. py:module:: t3toolbox.optimizers

.. autoapi-nested-parse::

   Frontend adapter for the geometry-agnostic optimizers.

   A thin wrapper over :py:mod:`t3toolbox.backend.optimizers` (where the algorithms live -- check-free, so a
   raw-``.data`` user can call them directly). This layer (1) maps the frontend geometry singletons and the
   sampling-kind name to the backend ``GeometryOps`` / ``SamplingKind``, (2) calls the backend optimizer on the
   raw cores, and (3) re-wraps the result. Design: ``dev/archive/optimizers_plan.md``.

   **Two representations, inferred from** ``x0`` (the library-wide ragged/uniform dispatch; ``_setup``):

   * a **ragged** ``TuckerTensorTrain`` x0 with a ragged geometry (``manifold.MANIFOLD`` / ``COREWISE``) --
     the optimizer runs on the raw cores; the frame is re-orthogonalized internally each step.
   * a **uniform** ``UniformTuckerTensorTrain`` x0 with a uniform geometry
     (``uniform_manifold.UNIFORM_MANIFOLD`` / ``UNIFORM_COREWISE``) -- the optimizer runs on the packed
     supercore pair (``lax.scan`` over the mode axis; the speed path). The uniform path requires a
     **minimal-rank frame**; it calls :py:func:`~t3toolbox.backend.uniform_fitting.uniform_minimal`
     transparently so a frontend user never meets that requirement.

   The geometry must match ``x0``'s representation (a uniform x0 with a ragged geometry, or vice versa, is a
   structural error). The result is returned in the same representation as ``x0``.

   **``use_jit=True``** (an explicit kwarg on ``mc_sgd`` / ``adam`` / ``newton_cg``) opts into jax: the
   optimizer **auto-converts** ``x0`` / ``sample`` / ``data`` onto jax and jit-compiles, so the result comes
   back **jax-backed** in jax's default float32 (enable jax x64 for float64); it **raises** if jax is not
   installed rather than silently running eager. See :py:func:`t3toolbox.backend.optimizers.newton_cg`.

       >>> # x_opt, stats = optimizers.gradient_descent(MANIFOLD, 'probe', ww, data, x0)           # ragged
       >>> # x_opt, stats = optimizers.newton_cg(UNIFORM_MANIFOLD, 'probe', ww, data, ux0)         # uniform



Functions
---------

.. toctree::
   :hidden:

   /autoapi/t3toolbox/optimizers/gradient_descent
   /autoapi/t3toolbox/optimizers/mc_sgd
   /autoapi/t3toolbox/optimizers/adam
   /autoapi/t3toolbox/optimizers/newton_cg

.. autoapisummary::

   t3toolbox.optimizers.gradient_descent
   t3toolbox.optimizers.mc_sgd
   t3toolbox.optimizers.adam
   t3toolbox.optimizers.newton_cg