optimizers
==========


.. py:module:: t3toolbox.backend.optimizers

.. autoapi-nested-parse::

   Backend-first optimization algorithms for fixed-rank T3 least-squares fitting.

   These operate on **raw cores / tangent tuples** via backend functions only -- no frontend imports
   (no ``TuckerTensorTrain`` / ``T3Tangent`` / ``GaussNewtonModel`` / geometry classes). A raw-``.data``
   user can call them directly; the frontend ``optimizers.py`` is a thin adapter that validates the input
   once and assembles the ``Problem`` oracle from the same backend functions (design:
   ``dev/archive/optimizers_plan.md``).

   Because the numerical safety preconditions live only in the frontend, this layer is **check-free** of
   them (structural shape guards inside the backend functions remain, and are jit-safe). So ``jit`` needs no
   ``unsafe()`` wrapping; the ``use_jit`` machinery is a thin jax-only layer on top of the ordinary
   numpy/jax dispatch (the per-step kernels jit via ``_maybe_jit``; the inner CG runs as a
   ``lax.while_loop`` -- eager-vs-jit agreement is covered in ``tests/backend/test_optimizers.py``).

   The oracle:

   * ``Problem``     -- (geometry ops, sampling kind, sample, data); builds per-point ``LocalModel``
     objects and retracts.
   * ``LocalModel``  -- the GN model linearized at a point (``.gradient`` / ``.objective`` /
     ``.hvp`` / ``.gn_quadratic`` / ``.retract``), the backend twin of ``fitting.GaussNewtonModel``.
   * ``GeometryOps`` -- (frame, project, retract) on raw data; ``MANIFOLD_OPS`` / ``COREWISE_OPS``
     singletons.

   Tangent vectors are raw ``(tucker_var, tt_var)`` tuples; vector arithmetic is the ``corewise`` ops.



Attributes
----------

.. autoapisummary::

   t3toolbox.backend.optimizers.COREWISE_OPS
   t3toolbox.backend.optimizers.MANIFOLD_OPS


Classes
-------

.. toctree::
   :hidden:

   /autoapi/t3toolbox/backend/optimizers/GeometryOps
   /autoapi/t3toolbox/backend/optimizers/LocalModel
   /autoapi/t3toolbox/backend/optimizers/Problem
   /autoapi/t3toolbox/backend/optimizers/NewtonInfo

.. autoapisummary::

   t3toolbox.backend.optimizers.GeometryOps
   t3toolbox.backend.optimizers.LocalModel
   t3toolbox.backend.optimizers.Problem
   t3toolbox.backend.optimizers.NewtonInfo


Functions
---------

.. toctree::
   :hidden:

   /autoapi/t3toolbox/backend/optimizers/least_squares_problem
   /autoapi/t3toolbox/backend/optimizers/flat_draw
   /autoapi/t3toolbox/backend/optimizers/gradient_descent
   /autoapi/t3toolbox/backend/optimizers/mc_sgd
   /autoapi/t3toolbox/backend/optimizers/adam
   /autoapi/t3toolbox/backend/optimizers/newton_cg

.. autoapisummary::

   t3toolbox.backend.optimizers.least_squares_problem
   t3toolbox.backend.optimizers.flat_draw
   t3toolbox.backend.optimizers.gradient_descent
   t3toolbox.backend.optimizers.mc_sgd
   t3toolbox.backend.optimizers.adam
   t3toolbox.backend.optimizers.newton_cg


Module Contents
---------------

.. py:data:: COREWISE_OPS

.. py:data:: MANIFOLD_OPS