optimizers#

Frontend adapter for the geometry-agnostic optimizers.

A thin wrapper over 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 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 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#

`gradient_descent`(geometry, kind, sample, data, x0[, ...])	Fit `x` to `data` by steepest descent (Cauchy step + Armijo line search) on `geometry`.
`mc_sgd`(geometry, kind, sample, data, x0, rng, batch[, ...])	Manifold Cauchy SGD -- minibatched, tuning-free Cauchy step. Ragged or uniform `x0` (see
`adam`(geometry, kind, sample, data, x0, rng, batch[, ...])	Adam over the cores -- the dependency-free first-order method for the corewise geometry. Ragged or
`newton_cg`(geometry, kind, sample, data, x0[, order, ...])	Inexact Riemannian Newton-CG with an Armijo line search -- the manifold workhorse. Ragged or uniform