# nlls_gram

> Metric-aware underdetermined Levenberg-Marquardt nonlinear least squares for JAX pytrees (residual count m << parameter count n). Per-step update(), a jitted solve() loop with resettable hyperparameters and callbacks, implicit differentiation with respect to external parameters p, and pluggable parameter-space metrics (kernel/RKHS).

## Docs

- [Tuning guide — read first for solver selection and hyperparameter heuristics](https://highdimensionaleconlab.github.io/nlls_gram/tuning_guide/)
- [Main docs — API contracts, math, linear solvers, performance notes](https://highdimensionaleconlab.github.io/nlls_gram/)
- [Callbacks and cookbook — solve-loop callback contract, resettable hyperparameters, recipes](https://highdimensionaleconlab.github.io/nlls_gram/callbacks/)
- [Multi-start — retry failed solves from fresh draws or race starts in parallel under vmap; draw/accept hooks, key schedule, winner-only implicit AD](https://highdimensionaleconlab.github.io/nlls_gram/multi_start/)
- [Metrics — Metric callback contract, cholesky helper, dense and matrix-free examples](https://highdimensionaleconlab.github.io/nlls_gram/metrics/)
- [Utilities — tridiagonal/state-space-Matérn/shifted-matvec/diagonal/block-diagonal metric constructors; Sherman-Morrison, Woodbury, identity, and randomized Nyström (FTU) preconditioners serving both required CG hooks; the iterate-adaptive PreconditionerFactory that rebuilds the dual preconditioner from the current iterate each step; the dual-only padded-residual helper; matrix-free LSMR (linear_solver="lsmr") for the whitened damped subproblem when the cg dual is ill-conditioned at small damping, with an optional WhitenedPreconditioner parameter-space right-preconditioner that clusters the LSMR spectrum; and Krylov recycling (RecycleConfig / deflated_pcg) that carries a harvested deflation basis across LM steps](https://highdimensionaleconlab.github.io/nlls_gram/utilities/)
- [Implicit differentiation — JVP/VJP with respect to p, minimum-norm tangents, geometry-aware implicit solvers (implicit_solver="dual_cholesky"/"dual_cg"/"primal_qr"/"primal_cholesky", aliases "cholesky"/"cg"; "auto" follows the forward solver's geometry, picking the n-wide primal QR rule for tall-or-square m >= n whitened solves), the Gauss-Newton linearization contract for nonzero residuals, aux outputs](https://highdimensionaleconlab.github.io/nlls_gram/implicit_ad/)
- [Metric Gauss-Newton — minimum-norm math and kernel metric choices](https://highdimensionaleconlab.github.io/nlls_gram/gauss_newton/)
