Chart LM API
The chart-rows contract and the stack's one Levenberg–Marquardt (NLLSsolver, through one adapter): its stop settings (LmStops, with the damping strategy and the data's residual resolution), the chart, robust and multi-block solves (lmsolve_chart!, LmProblem), the one success rule, and the device LM (static_lm, StaticLmStops).
Chart Rows and the LM Core
VisualGeometryToolkitCore.RowsWorkspace — Type
RowsWorkspace{D, C}
RowsWorkspace{D, C}(n)The whitened residual rows of a D-dof chart with codimension-C residuals for n points: the stacked rows r and their Jacobian J (C·n × D, row-contiguous), the per-point residual norms rn (the codim-2 currency), the per-iteration participation mask valid and a unit √weight vector onev for the row kernels. rows_workspace builds one per (task, size).
VisualGeometryToolkitCore.lift_init — Function
The chart at the model model (a provider's starting anchor).
VisualGeometryToolkitCore.lift_jacobian! — Function
Fill the provider's rows' Jacobian at the chart ch.
VisualGeometryToolkitCore.lift_model — Function
The model at the chart ch.
VisualGeometryToolkitCore.lift_refresh! — Function
Fill the provider's rows (and, at codimension 2, the per-point norms) at the chart ch.
VisualGeometryToolkitCore.lift_residuals — Function
The provider's residual currency: the rows at codimension 1, the per-point norms at 2.
VisualGeometryToolkitCore.lift_retract — Function
The chart re-anchored at the tangent step Δθ from ch.
VisualGeometryToolkitCore.lift_rows — Function
The provider's rows, a RowsWorkspace.
VisualGeometryToolkitCore.lift_size — Function
The provider's point count.
VisualGeometryToolkitCore.lift_valid — Method
The provider's per-iteration participation mask, or nothing (every point participates).
VisualGeometryToolkitCore.point_norms! — Method
point_norms!(rn, r, n, d) -> rnPer-point norms of d-row residual groups: rn[i] = ‖r[d(i−1)+1 : d·i]‖.
VisualGeometryToolkitCore.rows_provider — Function
rows_provider(problem) -> provThe chart-rows provider of a chart problem for one local-optimization call (see the contract at the head of this file). The problem's owner implements it.
VisualGeometryToolkitCore.rows_workspace — Method
rows_workspace(::Val{D}, ::Val{C}, n) -> RowsWorkspace{D, C}The rows of n points under the one reuse policy (task_buffers).
VisualGeometryToolkitCore.task_buffers — Method
task_buffers(alloc, key)The buffer set stored under key in the current task's local storage, built by alloc() on first use. A workspace keyed by its type and sizes is then built once per (task, size) and reused by every later call of that size on that task — task-local, so threaded callers (Threads.@threads bodies are tasks) never share one. The one memo every per-call scratch workspace of the stack draws from.
VisualGeometryToolkitCore.task_buffers — Method
task_buffers(::Type{V}, alloc, key) -> VThe typed form: the buffer set of type V stored under key (a tuple of sizes, any isbits value) in the current task, built by alloc() on first use. Allocation-free on reuse: the task's storage is keyed by a singleton per (V, typeof(key)) and holds a Dict{typeof(key), V}, so no key is boxed. The form every per-call scratch with a size in its key uses.
VisualGeometryToolkitCore.Eliminable — Type
Eliminable{E}(value)An NLLSsolver variable — a Core Manifold, an SVector, any value with NLLSsolver's nvars/update — that the solver may ELIMINATE (E = true): the Schur-complement linear system eliminates every such variable (a bundle's structure points, a rotation bundle's track directions) before it solves for the rest. nvars and update forward to value (an update re-wraps the updated value); iseliminable is declared only where the installed NLLSsolver has the Schur system (nlls_features().schur), and Eliminable{false} is the same variable left in the full sparse LDL — what a solver without the Schur system takes, and a fallback test forces.
VisualGeometryToolkitCore.LevenbergDamping — Type
MarquardtDamping()
LevenbergDamping()The damping of the host Levenberg–Marquardt step, a strategy TYPE of LmStops and LmProblem (dispatch, not a flag), each NLLSsolver's own public iterator:
MarquardtDamping()(the default): λ·DᵀD, DᵀD the running maximum of diag(JᵀJ) floored at 1e-8 of its largest entry — NLLSsolver's:levenbergmarquardt_dtd; Core 0.10's damping, bit for bit;LevenbergDamping(): λ·I — NLLSsolver's:levenbergmarquardt(RadiometricCamera 0.8.0's).
Measured (Core 0.10.2, 2026-11-14, six iterations of RC's fisheye, Tamron and grid refinements and a non-central origin fit): neither wins everywhere. λ·DᵀD reaches a lower cost on the fisheye case (1711 against 1776), while λ·I converges where DᵀD's weak columns stall (the non-central fit: a cost ratio of 1.7e-18 against DᵀD's 1.2e-8 after 25 iterations, 9.0e-9 after 125), and on the Tamron and grid cases it reaches a slightly lower cost 1.6–1.8× faster (λ·DᵀD rejects more candidate steps). An UNFLOORED running max (Moré's scaling, NLLSsolver's DᵀD without its floor) was measured and rejected: a column whose diag(JᵀJ) is zero leaves H + λDᵀD singular (the grid and non-central factorizations fail), and it is no faster than the floored DᵀD.
VisualGeometryToolkitCore.LmDamping — Type
MarquardtDamping()
LevenbergDamping()The damping of the host Levenberg–Marquardt step, a strategy TYPE of LmStops and LmProblem (dispatch, not a flag), each NLLSsolver's own public iterator:
MarquardtDamping()(the default): λ·DᵀD, DᵀD the running maximum of diag(JᵀJ) floored at 1e-8 of its largest entry — NLLSsolver's:levenbergmarquardt_dtd; Core 0.10's damping, bit for bit;LevenbergDamping(): λ·I — NLLSsolver's:levenbergmarquardt(RadiometricCamera 0.8.0's).
Measured (Core 0.10.2, 2026-11-14, six iterations of RC's fisheye, Tamron and grid refinements and a non-central origin fit): neither wins everywhere. λ·DᵀD reaches a lower cost on the fisheye case (1711 against 1776), while λ·I converges where DᵀD's weak columns stall (the non-central fit: a cost ratio of 1.7e-18 against DᵀD's 1.2e-8 after 25 iterations, 9.0e-9 after 125), and on the Tamron and grid cases it reaches a slightly lower cost 1.6–1.8× faster (λ·DᵀD rejects more candidate steps). An UNFLOORED running max (Moré's scaling, NLLSsolver's DᵀD without its floor) was measured and rejected: a column whose diag(JᵀJ) is zero leaves H + λDᵀD singular (the grid and non-central factorizations fail), and it is no faster than the floored DᵀD.
VisualGeometryToolkitCore.LmProblem — Type
LmProblem(variables::AbstractVector, blocks::AbstractVector; fixed = nothing, damping = MarquardtDamping())An NLLSsolver problem as the stack's one LM adapter (lmsolve_chart!) solves it: variables (any NLLSsolver variables — Core Manifolds, SVectors, Eliminables — of one type or several) and the residual blocks (NLLSsolver AbstractResiduals, of one type or several, each with its own varindices and its robustkernel: NLLSsolver.NoRobust(), or a frozen loss through loss_robustifier). The problem is built once, with NLLSsolver's typed OptimizeCache (the linear system's layout — the Schur system where the variables allow it), and kept: a later solve on the same structure (a RANSAC refit's bundle) rebuilds neither.
p.variables is the problem's variable vector: set the start in place before a solve, read the solution after it (NLLSsolver swaps its buffers, so read it through p, never through a saved reference). p.blocks are the blocks; the residual statistics of a solve are nlls_rows_and_jacobian(p.blocks, p.variables).
fixed holds variables: the indices into variables (an Integer or a collection of them) of those the solve keeps as constants the blocks read (NLLSsolver's unfixed mask); the stationarity postcondition reads the free variables' columns only. nothing (the default) holds none, the problem as without the keyword, bit for bit. An index outside variables, or every variable held, is an ArgumentError.
damping (MarquardtDamping, the default, or LevenbergDamping) is THE problem's damping (its one owner, Core 0.10.4: p.damping), the one its kept NLLSsolver cache is built for: lmsolve_chart!'s default stops take it, and an explicitly supplied stops of another damping is refused (ArgumentError, naming both), the problem left as it was.
VisualGeometryToolkitCore.LmStops — Type
LmStops(; max_iter, ftol, xtol, xtol_rel, stationarity_tol, max_time = nothing, damping = MarquardtDamping(), residual_resolution = 0)THE stop settings of every host Levenberg–Marquardt fit of the stack — the one owner of its knobs, which lmsolve_chart! maps onto NLLSsolver's options in one place. Every keyword defaults to Core's configuration of record (configs/default.toml [lm]); a fit overrides one only from its own configuration table.
| knob | meaning | NLLSsolver |
|---|---|---|
max_iter | the iteration cap ([lm] 1000) | maxiters: outer iterations, one ACCEPTED step each; an iteration's damping loop may reject ~8–10 candidate steps first, so the cap bounds accepted steps, not work |
ftol | relative cost tolerance ([lm] 1e-10): stop once a step lowers the cost by less than ftol·F (a relative tolerance: never the exact-fit test, whose threshold is the final point's rounding, _exact_fit_threshold) | reldcost |
xtol | step tolerance ([lm] 1e-10) | dstep: ABSOLUTE, the step's max-norm in chart units (max|pᵢ| < xtol) |
xtol_rel | RELATIVE step tolerance ([lm] 0: none), Ceres' parameter tolerance: stop once ‖Δx‖ ≤ xtol_rel·(‖x‖ + xtol_rel), Euclidean norms of the step and of the free variables before it (a Euclidean coordinate its value, a chart coordinate one chart unit: the exact-fit threshold's operand units, _operand_unit). A step-size stop like xtol's (IncrementSize: converged, Success) | — (the stack's own test, _RelativeIncrementStop, in NLLSsolver's callback slot: a callback's flag 2¹⁵ is Core's own) |
stationarity_tol | the stationarity postcondition's column cosine ([lm] 0.05). Read by is_stationary, and by the host verdict only at a stop of no tolerance: the rejection cap (unreachable through NLLSsolver 5.3's LM) and the stop one iteration after a cost disagreement (NLLSsolver's bit 10 alone, Core 0.11.1); a tolerance stop is converged without it (0.11.0) | — (the stack's own test, is_stationary) |
max_time | wall-clock cap in seconds; nothing (the default) or Inf: none | maxtime |
residual_resolution | read by is_stationary, and by the host verdict only where stationarity_tol is; the residual-vector NORM the DATA resolve (0, the default: the final point's rounding alone; √m·q over m residuals of a per-sample linear_quantum q). The success rule's exact-fit test reads it, F < max(rounding floor, residual_resolution²) — a cost below its square is zero to what the data resolve, where the rows' rounding points in no direction and the cosine says nothing — and nothing else: the iteration's stops are unchanged. A caller states it DERIVED (the data's noise in the residual's units), never tuned | — (the stack's own test; StaticLmStops' residual_resolution) |
damping | the step's damping, a strategy type: MarquardtDamping (the default, λ·DᵀD) or LevenbergDamping (λ·I) | iterator: :levenbergmarquardt_dtd / :levenbergmarquardt |
| — | absolute cost decrease | absdcost = 0: the stack has no such knob |
| — | consecutive failed iterations | maxfails = 3, NLLSsolver's default |
The initial λ is NLLSsolver's (1e-6), not a knob. Single-threaded (numthreads = 1): a fit runs inside the caller's threads. There is no gradient tolerance: a tolerance stop is converged, and the stationarity postcondition judges the rejection cap and the stop after a cost disagreement (lmsolve_chart!).
VisualGeometryToolkitCore.ManifoldLmWorkspace — Type
ManifoldLmWorkspace{N}
ManifoldLmWorkspace(n, N)The buffers of the chart LM (lmsolve_chart!) at n residual rows and an N-dimensional chart: the per-row √weights the caller's refit fills, the residual and n × N Jacobian buffers the rows are evaluated into, the stall postcondition's scratch, and the NLLSsolver problem the adapter builds on first use (and keeps, with NLLSsolver's internal data, for every later refit on a linearization state of the same type) — allocated once per problem instead of per LM iteration. N is the model manifold's tangent size (essential 5, fundamental 7, homography 8 in VisualGeometryToolkitEstimation). The residual SEMANTICS come entirely from the caller's linearization state — Sampson distance for E/F, whitened transfer error for H, calibrated reprojection for P3P — which is why the type is named for the manifold, not the distance.
VisualGeometryToolkitCore.MarquardtDamping — Type
MarquardtDamping()
LevenbergDamping()The damping of the host Levenberg–Marquardt step, a strategy TYPE of LmStops and LmProblem (dispatch, not a flag), each NLLSsolver's own public iterator:
MarquardtDamping()(the default): λ·DᵀD, DᵀD the running maximum of diag(JᵀJ) floored at 1e-8 of its largest entry — NLLSsolver's:levenbergmarquardt_dtd; Core 0.10's damping, bit for bit;LevenbergDamping(): λ·I — NLLSsolver's:levenbergmarquardt(RadiometricCamera 0.8.0's).
Measured (Core 0.10.2, 2026-11-14, six iterations of RC's fisheye, Tamron and grid refinements and a non-central origin fit): neither wins everywhere. λ·DᵀD reaches a lower cost on the fisheye case (1711 against 1776), while λ·I converges where DᵀD's weak columns stall (the non-central fit: a cost ratio of 1.7e-18 against DᵀD's 1.2e-8 after 25 iterations, 9.0e-9 after 125), and on the Tamron and grid cases it reaches a slightly lower cost 1.6–1.8× faster (λ·DᵀD rejects more candidate steps). An UNFLOORED running max (Moré's scaling, NLLSsolver's DᵀD without its floor) was measured and rejected: a column whose diag(JᵀJ) is zero leaves H + λDᵀD singular (the grid and non-central factorizations fail), and it is no faster than the floored DᵀD.
VisualGeometryToolkitCore.StaticLmStops — Type
StaticLmStops(scale::SVector{N, T}; acceptance = Inf, residual_scale = 1, cost_floor = 0, residual_resolution = 0, max_iter, stationarity_tol)THE stop settings of the device LM static_lm (isbits: a kernel takes it as an argument), owned with the host LM's (LmStops): every keyword has a default of record — max_iter configs/default.toml [lm] device_max_iter, acceptance[lm] device_acceptance, stationarity_tol[lm] stationarity_tol (the stationarity postcondition's cosine, the host's), and the floors' neutral values.
scale: the problem's unit per coordinate, in which the step tolerance (1e-10·(eps(T)/eps(Float64)) ./ scale, RELATIVE to the coordinate) and the DᵀD clamp ([1e-12, 1e16]·scale²) are read.acceptance: the cost a solution must be below, F <acceptance— a root-finding caller's residual bound; by default[lm] device_acceptance,Inf: success by the stationarity rule alone.residual_scale: the residual's operand scalefs(S, with S² = Σᵢ sᵢ² over the residuals' operand magnitudes), so the absolute cost and gradient floors are whatTresolves of it,(16 eps(T) fs)²— THE exact-fit threshold's rounding floor, the host LM's (lmsolve_chart!): a residual of operands of size s is rounded to 16·eps(T)·s.cost_floor: the absolute floor under those (0: resolved to rounding; the spline lenses' reference routine stops ateps(Float64)).residual_resolution: the residual-vector NORM the DATA resolve, when they carry less precision thanT(a Float32 ray or Float32 controls in a Float64 solve:16 eps(Float32)of a unit residual). The success rule's exact-fit test reads it — a cost below its square is zero to what the data resolve, where the rows' rounding points in no direction and the cosine says nothing — and nothing else: the iteration's stops stayT's.
VisualGeometryToolkitCore.finite_cost — Method
finite_cost(c::Float64) -> Float64A cost as the stack's NLLSsolver fits read it: c when finite, +Inf otherwise. NLLSsolver (≥ 5.3.1) accepts a trial at a step below xtol whatever its cost and asserts cost == cost_ per iteration, which NaN fails; +Inf compares equal and is rejected like NaN everywhere else. Every NLLSsolver residual block of the stack returns its cost through it.
VisualGeometryToolkitCore.is_stationary — Method
is_stationary(J::AbstractMatrix, f::AbstractVector; tol, ftol) -> BoolThe stall postcondition of lmsolve_chart! for a fit the chart LM does not run (a block-structured NLLSsolver problem, nlls_termination's postcondition): whether the point at which the residual f and its Jacobian J were evaluated is a stationary point of F = ‖f‖² — F < ftol (an exact fit, whose residual points in no particular direction), or every column Jⱼ numerically orthogonal to f, max_j |Jⱼᵀ f| / (‖Jⱼ‖ ‖f‖) ≤ tol (scale-invariant in the residuals and in each unknown; an all-zero column is skipped, a NaN fails). A rejection-cap stop at which this fails stopped where its damping grew, not at a minimizer: its retcode is :stalled (a tolerance stop is converged without it, Core 0.11.0).
VisualGeometryToolkitCore.is_stationary — Method
is_stationary(blocks, variables, free::AbstractVector{Bool}; tol, ftol) -> BoolThe same stall postcondition for an NLLSsolver problem's residual blocks at its variables, in the chart coordinates of the variables free marks (a held variable's columns are left out, as the solver held them): the cost NLLSsolver minimizes, F = Σₖ ρ(‖rₖ‖²) (ρ each block's robustkernel, the identity for a plain block), is stationary when Σₖ ‖rₖ‖² < ftol (or Σₖ ρ′ₖ‖rₖ‖² < ftol with some ρ′ₖ > 0), or when every free column of the √ρ′-weighted system is numerically orthogonal to its rows, max_j |gⱼ| / (√wⱼ ‖√ρ′ r‖) ≤ tol with gⱼ = Σₖ ρ′ₖ Jₖⱼᵀ rₖ and wⱼ = Σₖ ρ′ₖ ‖Jₖⱼ‖² — the test the matrix method above makes of the stacked rows √ρ′ₖ rₖ and Jacobian √ρ′ₖ Jₖ, and exactly the robust chart LM's (lmsolve_chart!): ρ′ clamped at 0, the unweighted cost below ftol an exact fit, and a plateau (every block past a redescending loss's cutoff, ρ′ = 0 throughout) NOT stationary. The rows and their Jacobian (NLLSsolver.computeresjac of each block with all its variables, as nlls_rows_and_jacobian evaluates them, a held variable's columns skipped) are accumulated block by block into g, w and F: the problem's Jacobian is never held.
VisualGeometryToolkitCore.is_stationary — Method
is_stationary(ews::ManifoldLmWorkspace, lm, x, stops::LmStops) -> BoolThe chart LM's stationarity postcondition for the state lm at the chart point x (an SVector{N}, the chart coordinates lmsolve_chart! returns), under stops' stationarity_tol and residual_resolution: the cost is zero by the exact-fit test (below the final point's rounding, floored by residual_resolution²), or every column of the rows' Jacobian is numerically orthogonal to the rows (the column cosine at most stationarity_tol). It reads the state's reduction at x (residual_normal_equations!) into ews's buffers.
The host LM converges a tolerance stop at a finite step without this test (Core 0.11.0); a caller whose own validity gate needs a stationary point (VisualGeometryToolkitEstimation's optical axis) runs it at the solution. stops is required (LmStops() for the configuration of record): a 3-argument form would be ambiguous with the block form is_stationary(blocks, variables, free).
VisualGeometryToolkitCore.lmsolve_chart! — Method
lmsolve_chart!(ews::ManifoldLmWorkspace{N}, lm, stops::LmStops = LmStops())
-> (x::SVector{N}, F, converged, iterations, (code, rule))
lmsolve_chart!(ews::ManifoldLmWorkspace{N}, lm, robustifier, ::Val{C}, stops::LmStops = LmStops())
-> (x::SVector{N}, F, converged, iterations, (code, rule))
lmsolve_chart!(p::LmProblem, stops::LmStops = LmStops(; damping = p.damping); callback = nothing)
-> (; code::ReturnCode.T, rule::StopRule, iterations::Int, cost::Float64)THE stack's host Levenberg–Marquardt: NLLSsolver (Marquardt's DᵀD damping) under the stop settings stops (LmStops, the one owner of the knobs), on a kept problem and NLLSsolver cache, with ONE success rule.
- THE CHART LM minimizes
‖r(x)‖²,rtheresidual_rows!of the linearization statelm(its Jacobianresidual_jacobian_rows!, both read through the state's two reductions), from the chart originx = 0. - THE ROBUSTIFIED CHART LM minimizes
Σᵢ ρ(‖rᵢ(x)‖²)from the chart origin,rᵢdatumi'sCconsecutive rows (Cthe codimension) andρthe NLLSsolverrobustifier— a stack loss throughloss_robustifier(shape, loss_width), applied per datum (NLLSsolver's robustified Hessian), so one solve is the robust M-estimate.FisΣᵢ ρ(‖rᵢ‖²)atx; on return the workspace'srholds the unweighted rows atx. - THE MULTI-BLOCK LM solves an
LmProblem— heterogeneous variables and residual blocks, each block with its own robustifier — in place inp.variables;costisΣₖ ρ(‖rₖ‖²)(‖r‖² without robustifiers),callbackan NLLSsolver iteration callback (nothing: none). An indefinite or singular normal system in NLLSsolver's step solve (PosDefException,SingularException,ZeroPivotException,LAPACKException) is a failed solve,(ReturnCode.Failure, NonFinite), the variables as the solver left them.
The chart forms keep the problem and NLLSsolver's OptimizeCache in the workspace (one caching path, plain and robust alike), so a refit rebuilds neither. x is the solution chart vector, F the final cost, converged the stop code (nlls_stop_code's, or -2 for a stop the postcondition fails), iterations NLLSsolver's count (one accepted step each; a start at a stationary point takes one zero step, and only a start whose cost or gradient is not finite stops at 0, :solve_failed), and (code, rule) the termination record, a ReturnCode and a StopRule (nlls_termination's decode).
THE SUCCESS RULE (owner ruling, Core 0.11.0). A stop on a TOLERANCE is converged, ReturnCode.Success: the relative cost decrease (ftol, CostDecrease) and the step size (xtol absolute or xtol_rel relative, IncrementSize), whatever the gradient at the returned point — whether a tolerance is too loose is the configuration's question, not the termination record's. A FINITE step only: a step-size stop whose last trial was non-finite (a NaN wall, the step tiny because no finite one is left) is (ReturnCode.Stalled, NonFinite), converged = -2, at the last accepted point. The iteration and time caps are not converged (MaxIters, MaxTime), a failed solve is Failure. A rounding-level cost disagreement (NLLSsolver's bit 10, as at an exact fit) is neither (Core 0.11.1): NLLSsolver stops one iteration after it, whatever that iteration shows, so a stop with it is no tolerance stop. The stops that are no tolerance — the consecutive-rejection cap and any stop after a cost disagreement (its rule the tolerance's bit, else NoRule) — are judged by the stationarity postcondition at the returned point, ReturnCode.Stalled (converged = -2) when it fails. Stationary means the cost is zero by the exact-fit test — below the rounding of the final point's residuals, F < (16ε)²·Σᵢ sᵢ² over their operand scales sᵢ (_exact_fit_threshold, Core 0.10.4: a run that starts at an exact fit, a restart from a solve's minimum, ends at one), floored by the square of the residual-vector norm the data resolve, stops.residual_resolution (0 by default; stops.ftol is the relative cost-decrease stop, never this test). Otherwise stationary means every column of the Jacobian is numerically orthogonal to the residual, max_j |Jⱼᵀr| / (‖Jⱼ‖ ‖r‖) ≤ stops.stationarity_tol (√ρ′-weighted per datum or block when robust: is_stationary).
VisualGeometryToolkitCore.loss_robustifier — Method
loss_robustifier(shape::AbstractLossShape, loss_width::Real)NLLSsolver's robustifier (an NLLSsolver.AbstractRobustifier) for the loss shape at loss_width. NLLSsolver hands a robustifier the squared residual norm cost and reads robustify(k, cost) = ρ and robustifydcost(k, cost) = (ρ, ρ′, ρ″); here ρ is Core's ρ(shape, cost, loss_width²) in the stack's convention ρ′(0) = w_max (no factor ½), ρ′ its weight and ρ″ the derivative of that weight (Core has no closed ρ″ per shape; ForwardDiff differentiates the weight).
VisualGeometryToolkitCore.nlls_features — Method
nlls_features() -> (; schur::Bool)Whether the loaded NLLSsolver has the Schur-complement linear system for eliminable variables (NLLSsolver.MultiVariateLSschur, NLLSsolver.iseliminable; upstream pull request #60, open). Until #60 merges a registered NLLSsolver lacks it and the bundle takes NLLSsolver's sparse LDL over every unknown — the same optimum, slower; the stack's fork has it.
VisualGeometryToolkitCore.nlls_rows_and_jacobian — Method
nlls_rows_and_jacobian(blocks, variables) -> (r, J::SparseMatrixCSC)The rows of NLLSsolver residual blocks at variables (an NLLSsolver problem's variable vector) and their sparse Jacobian in the variables' chart coordinates — NLLSsolver.computeresjac of every block with all its variables free — the rows in block order, each variable's NLLSsolver.nvars columns in variable order (a run-time size included). What nlls_termination's stall postcondition reads, and a covariance or a GCV linearization of the same fit.
VisualGeometryToolkitCore.nlls_stop_reasons — Method
nlls_stop_reasons(bits::Integer) -> Vector{Symbol}Every reason NLLSsolver's termination bits (result.termination) state, in bit order: :cost_infinite (0), :cost_nan (1), :relative_cost_decrease (2, below reldcost), :absolute_cost_decrease (3, below absdcost), :delta_infinite (4), :delta_nan (5), :delta_size (6, the LM update δ below dstep), :max_consecutive_rejections (7, maxfails iterations whose cost exceeded the best), :max_iterations (8), :max_time (9), :cost_disagreement (10, the cost and the relinearization's cost at an accepted point differ beyond isapprox's default tolerance — rounding near an exact fit sets it; NLLSsolver stops one iteration later, and it is no failure), :nonfinite_start (11, the start point's cost or gradient is not finite: no step is tried), :nonfinite_gradient (12, the gradient at an accepted point is not finite: the solve stops there, its best point kept), :callback (16), :relative_increment_size (31, Core's relative step stop, LmStops' xtol_rel: ‖Δx‖ ≤ xtolrel·(‖x‖ + xtolrel)). A report of the stop; nlls_stop_code is the one decision read from the same bits.
VisualGeometryToolkitCore.reduce_cost — Method
reduce_cost(partials::AbstractMatrix) -> ½‖r‖²residual_cost!'s value for a device state: half the sum of row 1 of its per-work-item partial sums (the layout of reduce_normal_equations; only row 1 is read, so a cost kernel may write a 1 × W matrix), summed on the array's backend.
VisualGeometryToolkitCore.reduce_cost — Method
reduce_cost(row!, args...; partials) -> ½‖r‖²A device LM state's residual_cost! in one call: row!(partials, w, args...) for every work item w as one kernel on partials' backend (as reduce_normal_equations's row form), then reduce_cost(partials) (row 1: each work item's Σ ‖rᵢ‖²). partials is overwritten.
VisualGeometryToolkitCore.reduce_normal_equations — Method
reduce_normal_equations(row!, ::Val{N}, args...; partials) -> (½‖r‖², Jᵀr::SVector{N}, JᵀJ::SMatrix{N, N})A device LM state's residual_normal_equations! in one call: row!(partials, w, args...) for every work item w (each column of partials) as one kernel on partials' backend — the stack's one row launch, KernelAbstractions on every backend, the CPU's included, so the sums are the same bits on a device — then the columns reduced (reduce_normal_equations(partials, Val(N))). row! writes work item w's share into column w in that layout (1 + N + N² rows). partials is the state's scratch (its column count the work items), overwritten.
VisualGeometryToolkitCore.reduce_normal_equations — Method
reduce_normal_equations(partials::AbstractMatrix, ::Val{N}) -> (½‖r‖², Jᵀr::SVector{N}, JᵀJ::SMatrix{N, N})residual_normal_equations!'s value for a device state, from its per-work-item partial sums. Column w of partials is work item w's share over its rows, 1 + N + N² entries: Σ ‖rᵢ‖², then the N of Σ Jᵢᵀrᵢ, then the N × N of Σ JᵢᵀJᵢ, column-major. The columns are summed where they are, on the array's backend (sum(partials; dims = 2)), and only the 1 + N + N² totals come to the host. The result is isbits. The cost alone is reduce_cost.
VisualGeometryToolkitCore.residual_cost! — Function
residual_cost!(r, lm, θ) -> ½‖r(θ)‖²
residual_normal_equations!(r, J, lm, θ::SVector{N}) -> (½‖r‖², Jᵀr::SVector{N}, JᵀJ::SMatrix{N, N})THE CHART LM'S TWO REDUCTIONS of the rows: what lmsolve_chart! reads.
residual_cost!gives the cost at a trial point.residual_normal_equations!gives the cost, the gradient and the Gauss–Newton Hessian at a linearization. It also feeds the stall postcondition, whose cosine|Jⱼᵀr| / (‖Jⱼ‖‖r‖)readsganddiag(H).
The defaults evaluate residual_rows! and residual_jacobian_rows! into the caller's buffers r and J, and reduce on the host.
A state whose rows live on a DEVICE overrides both with one kernel that evaluates every row and its Jacobian and reduces them where they are. The rows never reach the host; r and J go unused. Only the N × N step is the host's.
VisualGeometryToolkitCore.residual_jacobian_rows! — Function
residual_rows!(r, lm, θ) -> r
residual_jacobian_rows!(J, lm, θ) -> JTHE CHART-LM PROTOCOL — one pair for every model: the residual and Jacobian rows the chart LM, NLLSsolver, minimizes in lmsolve_chart!.
lm is the per-call LINEARIZATION STATE a refit builds once: the anchor the chart is centred on, the whitening frozen there, the data views and the √weights. θ is the CHART vector, not a model. The rows are √w-WEIGHTED and live in chart coordinates — a different currency from a RANSAC problem's UNWEIGHTED whitened_residuals!(r, problem, model) in data units. Two names, because one name with two currencies is what the frame-in = frame-out rule exists to prevent.
Ceres analogue: together they are what a CostFunction::Evaluate fills — residual_rows! the residuals buffer, residual_jacobian_rows! the jacobians — with the manifold's retract_jacobian (Ceres' PlusJacobian) already folded into the chart directions. GTSAM's nearest equivalent is a factor's linearize(values), which returns the same rows and Jacobian as a JacobianFactor at the linearization point rather than filling caller buffers.
Both write into caller-owned buffers and return them; neither allocates. Methods live with the models (VisualGeometryToolkitEstimation's problems).
VisualGeometryToolkitCore.residual_normal_equations! — Function
residual_cost!(r, lm, θ) -> ½‖r(θ)‖²
residual_normal_equations!(r, J, lm, θ::SVector{N}) -> (½‖r‖², Jᵀr::SVector{N}, JᵀJ::SMatrix{N, N})THE CHART LM'S TWO REDUCTIONS of the rows: what lmsolve_chart! reads.
residual_cost!gives the cost at a trial point.residual_normal_equations!gives the cost, the gradient and the Gauss–Newton Hessian at a linearization. It also feeds the stall postcondition, whose cosine|Jⱼᵀr| / (‖Jⱼ‖‖r‖)readsganddiag(H).
The defaults evaluate residual_rows! and residual_jacobian_rows! into the caller's buffers r and J, and reduce on the host.
A state whose rows live on a DEVICE overrides both with one kernel that evaluates every row and its Jacobian and reduces them where they are. The rows never reach the host; r and J go unused. Only the N × N step is the host's.
VisualGeometryToolkitCore.residual_rows! — Function
residual_rows!(r, lm, θ) -> r
residual_jacobian_rows!(J, lm, θ) -> JTHE CHART-LM PROTOCOL — one pair for every model: the residual and Jacobian rows the chart LM, NLLSsolver, minimizes in lmsolve_chart!.
lm is the per-call LINEARIZATION STATE a refit builds once: the anchor the chart is centred on, the whitening frozen there, the data views and the √weights. θ is the CHART vector, not a model. The rows are √w-WEIGHTED and live in chart coordinates — a different currency from a RANSAC problem's UNWEIGHTED whitened_residuals!(r, problem, model) in data units. Two names, because one name with two currencies is what the frame-in = frame-out rule exists to prevent.
Ceres analogue: together they are what a CostFunction::Evaluate fills — residual_rows! the residuals buffer, residual_jacobian_rows! the jacobians — with the manifold's retract_jacobian (Ceres' PlusJacobian) already folded into the chart directions. GTSAM's nearest equivalent is a factor's linearize(values), which returns the same rows and Jacobian as a JacobianFactor at the linearization point rather than filling caller buffers.
Both write into caller-owned buffers and return them; neither allocates. Methods live with the models (VisualGeometryToolkitEstimation's problems).
VisualGeometryToolkitCore.sqrt_weights — Method
The per-row √weight buffer of a ManifoldLmWorkspace, filled by the caller's refit.
VisualGeometryToolkitCore.static_lm — Method
static_lm(fj, x₀::SVector{N, T}, lb, ub, stops::StaticLmStops{N, T}[, bound]) -> (x, converged, J, e, rule::StopRule)The stack's ONE device-side Levenberg–Marquardt (the spline lenses' inverse at N = 2, any static N): Marquardt-scaled, bounded to the box [lb, ub] (a step is clipped to it), with an unrolled Cholesky-type solve and explicit fused products, so it allocates nothing, never throws, and runs inside a KernelAbstractions kernel with the same bits in every compiled copy. fj(x) returns (r, J, …) (the residual SVector, its SMatrix Jacobian, anything else returned with them as e); stops its stop settings (StaticLmStops); bound a relative step radius (nothing: none). converged is the device LM's success rule — the point is STATIONARY (unlike the host LM's tolerance stops, which Core 0.11.0 converges without the test): zero to what the stops resolve (the cost below the exact-fit floor, the gradient below its floor, or the undamped Gauss–Newton step from the point below the step tolerance: the device form of the host's exact-fit test), or max_j |Jⱼᵀr| / (‖Jⱼ‖ ‖r‖) ≤ stops.stationarity_tol, the host LM's cosine; on the box the gradient of a coordinate a bound holds (its descent leaves the box) is dropped, the bounded problem's stationarity — and its cost is below stops.acceptance. rule is the stop that fired: ExactFit (the cost floor), ToleranceMet (the gradient floor), IncrementSize (the step), CostDecrease (the relative cost decrease) or IterationCap; static_lm_termination gives the §14 record. NLLSsolver (lmsolve_chart!) is every host fit's LM.
VisualGeometryToolkitCore.static_lm_termination — Method
static_lm_termination(converged::Bool, rule::StopRule) -> (ReturnCode.T, StopRule)The §14 termination record of a static_lm solve: ReturnCode.Success when it converged; otherwise ReturnCode.MaxIters at the iteration cap and ReturnCode.Stalled at any other stop (a step, cost or gradient stop short of the tolerance).
Index
VisualGeometryToolkitCore.EliminableVisualGeometryToolkitCore.LevenbergDampingVisualGeometryToolkitCore.LmDampingVisualGeometryToolkitCore.LmProblemVisualGeometryToolkitCore.LmStopsVisualGeometryToolkitCore.ManifoldLmWorkspaceVisualGeometryToolkitCore.MarquardtDampingVisualGeometryToolkitCore.RowsWorkspaceVisualGeometryToolkitCore.StaticLmStopsVisualGeometryToolkitCore.finite_costVisualGeometryToolkitCore.is_stationaryVisualGeometryToolkitCore.is_stationaryVisualGeometryToolkitCore.is_stationaryVisualGeometryToolkitCore.lift_initVisualGeometryToolkitCore.lift_jacobian!VisualGeometryToolkitCore.lift_modelVisualGeometryToolkitCore.lift_refresh!VisualGeometryToolkitCore.lift_residualsVisualGeometryToolkitCore.lift_retractVisualGeometryToolkitCore.lift_rowsVisualGeometryToolkitCore.lift_sizeVisualGeometryToolkitCore.lift_validVisualGeometryToolkitCore.lmsolve_chart!VisualGeometryToolkitCore.loss_robustifierVisualGeometryToolkitCore.nlls_featuresVisualGeometryToolkitCore.nlls_rows_and_jacobianVisualGeometryToolkitCore.nlls_stop_reasonsVisualGeometryToolkitCore.point_norms!VisualGeometryToolkitCore.reduce_costVisualGeometryToolkitCore.reduce_costVisualGeometryToolkitCore.reduce_normal_equationsVisualGeometryToolkitCore.reduce_normal_equationsVisualGeometryToolkitCore.residual_cost!VisualGeometryToolkitCore.residual_jacobian_rows!VisualGeometryToolkitCore.residual_normal_equations!VisualGeometryToolkitCore.residual_rows!VisualGeometryToolkitCore.rows_providerVisualGeometryToolkitCore.rows_workspaceVisualGeometryToolkitCore.sqrt_weightsVisualGeometryToolkitCore.static_lmVisualGeometryToolkitCore.static_lm_terminationVisualGeometryToolkitCore.task_buffersVisualGeometryToolkitCore.task_buffers