Lift core and schedules
The joint-(θ,z) machinery behind HQ, Gnc and the research lifts. It runs on VisualGeometryToolkitCore's chart-rows contract (rows_provider, lift_init, lift_refresh!, lift_jacobian!, lift_retract, …), which VisualGeometryToolkitEstimation implements for its problems, so one code path serves every liftable problem.
Lift state and z-blocks
LocalOptimizationDoneRight.LiftState — Type
LiftState{D}
LiftState{D}(n)The lift's own buffers on a D-dof chart for n points: the line process z and its back-substitution terms (dvec, gzv), and the reduced normal equations (Hbuf, gbuf). The stacked rows, their Jacobian, the per-point norms and the participation mask are the chart-rows provider's (VisualGeometryToolkitCore RowsWorkspace{D, C}). lift_state builds one per (task, size).
LocalOptimizationDoneRight.lift_state — Function
lift_state(::Val{D}, n) -> LiftState{D}The lift's state for n points under the one reuse policy (VisualGeometryToolkitCore's task_buffers).
LocalOptimizationDoneRight.LiftZBlock — Type
LiftZBlockThe z-block of a joint-(θ,z) lift. JointGaussNewton (the default) reads the loss's closed forms through lift_zblock; WelschConvexNewton is the convexified-Newton z-block of the Welsch lift.
LocalOptimizationDoneRight.JointGaussNewton — Type
JointGaussNewton()The Gauss–Newton z-block: per point the joint system is [w̄·JᵢᵀJᵢ, zᵢ·Jᵢᵀrᵢ; ·, ‖rᵢ‖² + hreg + μ] with (rinv2, hreg) = lift_zblock(loss, w̄) and z-gradient zᵢ(‖rᵢ‖² − rinv2). Any object answering lift_zblock and lift_window is a loss for it — a DeployedLoss or a TabulatedLift.
LocalOptimizationDoneRight.WelschConvexNewton — Type
WelschConvexNewton()The convexified-Newton z-block of the Welsch lift (Zach & Bourmaud, ECCV 2018, Eq. 15). Per point, for Φᵢ = w‖rᵢ‖² + κ²(w), w = z², κ² the Welsch conjugate — Φ carries no ½, so every derivative is twice the Gauss–Newton block's:
∂Φ/∂θ = 2w Jᵀr, ∂Φ/∂z = 2z(‖r‖² − rinv2),θθ = 2w JᵀJ, θz = 4z Jᵀr, zz = 2(‖r‖² − rinv2) + 4w·κ²″(w),with rinv2 from lift_zblock and the z-block convexified to max(zz, 8‖r‖²) + μ so the Schur-reduced θ-Hessian stays positive semidefinite. The curvature w·κ²″(w) is Welsch's own (it is c²), so the loss must be a deployed WelschShape (checked).
LocalOptimizationDoneRight.lift_window — Function
lift_window(loss) -> (w̄lo, w̄hi)The clamp window of the normalized line-process weight w̄ = z² the lift runs in: (1e-9, 1) for a closed-form loss, the table's own grid for a TabulatedLift.
LocalOptimizationDoneRight.TabulatedLift — Type
TabulatedLift(M; γ = 1)Buffers for an M-node tabulated half-quadratic conjugate, filled by tabulate!. A loss for the lift's Gauss–Newton z-block (any codimension): it answers lift_zblock, lift_window, lift_wmax and lift_conjugate. γ scales the conjugate (the lifting regularizer's strength: γ > 1 makes the lift more reluctant to switch points off).
LocalOptimizationDoneRight.tabulate! — Function
tabulate!(tab::TabulatedLift, ω; warm = false) -> w_maxFill tab for the weight function ω(x) -> (ω, dω/dx) (a Float64 pair) of the squared residual x, which must decrease strictly from w_max = ω(0). The grid spans w_max·[1e-9, 1 − 1e-9] log-spaced; each node's r²(w) is a Newton root of ω(x) = w started from the adjacent node's root, or — with warm = true, for a table re-built after a small change of ω — from the SAME node's previous root.
tabulate!(tab::TabulatedLift, m::StudentTMixture; warm = false) -> w_maxTabulate the half-quadratic conjugate κ² of the Student-t + uniform mixture's IRLS weight — which has no closed form — from the weight and its slope, VisualGeometryToolkitCore's posterior_weight and posterior_weight_derivative.
LocalOptimizationDoneRight.cubic_hermite — Function
cubic_hermite(f0, d0, f1, d1, u, h)The cubic Hermite interpolant on one interval of width h at the fraction u ∈ [0, 1], from the node values f0, f1 and node slopes d0, d1 (slopes per unit of the abscissa, so they enter scaled by h). Generic over the number type, so it runs on device inside a kernel.
LocalOptimizationDoneRight.lift_raw_window — Function
lift_raw_window(tab::TabulatedLift) -> (wlo, whi)The table's weight grid ends on the RAW (unnormalized) weight scale — the clamp window of a caller that works in raw weights; lift_window is the same window normalized by lift_wmax.
Continuation schedules
LocalOptimizationDoneRight.LoSchedule — Type
LoScheduleA continuation schedule for graduated local optimization: owns the current continuation multiplier and the advance/terminate bookkeeping.
The contract (all four verbs; see the header for the consuming loop shape):
schedule_init(sched, mu0, max_iter) -> state: mutable schedule state from the seed-derived start multipliermu0and the TOTAL inner-iteration budgetmax_iter(schedules that split the budget into rungs derive the rung length here — defined once, never re-inlined by engines).scale_mult(state) -> Float64: the current continuation multiplier (the GNC μ, or the loss-width multiplier).isterminal(state; open=true) -> Bool: whether the schedule has reached its terminal objective. A stalled inner step may end the engine ONLY when this is true.advance!(state, stalled::Bool; open=true): per-iteration bookkeeping. A stalled step at a non-terminal position advances the schedule (rung ladders: early rung advance; time-indexed anneals: jump to terminal) — the stall-advance semantics, defined here once.
LocalOptimizationDoneRight.schedule_init — Function
schedule_init(sched::LoSchedule, mu0, max_iter) -> stateThe mutable state of the schedule sched for one run: from the start multiplier mu0 (derived from the seed) and the total inner-iteration budget max_iter. A schedule that splits the budget into rungs derives the rung length here. See LoSchedule for the consuming loop.
LocalOptimizationDoneRight.scale_mult — Function
scale_mult(state) -> Float64The current continuation multiplier of a schedule state: the GNC μ, or the loss-width multiplier (1 at the terminal objective of an anneal).
LocalOptimizationDoneRight.advance! — Function
advance!(state, stalled::Bool; open = true) -> nothingOne iteration's bookkeeping of a schedule state. A scheduled advance moves the multiplier on; a stalled inner step (stalled = true) at a non-terminal position also advances it (a rung ladder moves to its next rung early, a time-indexed anneal jumps to its terminal width). open is the engine's observation that the schedule may still make progress; a schedule that does not read it ignores it.
LocalOptimizationDoneRight.isterminal — Function
isterminal(state; open = true) -> BoolWhether the schedule state has reached its terminal objective. A stalled inner step may end the engine only when this holds; open as in advance!.
LocalOptimizationDoneRight.NoSchedule — Type
NoSchedule()The trivial schedule of a static-objective engine: multiplier 1, always terminal (a stalled step ends the engine immediately).
LocalOptimizationDoneRight.MuLadder — Type
MuLadder(factor; direction = :down, cap = Inf)The GNC rung ladder, a schedule that moves μ by factor per rung.
μ starts at a seed-derived mu0 and moves toward its terminal value — direction = :down anneals μ → 1 (GM / annealed-width Welsch surrogates; terminal at μ = 1), direction = :up anneals μ → cap (the TLS surrogate; terminal when the caller reports the middle band empty via open = false, or at μ ≥ cap).
schedule_init splits the TOTAL budget into rungs exactly as the GncIrls engines always did: n_rungs from the μ0 → terminal ladder at factor (down: ⌈log(μ0)/log(factor)⌉ + 1 including the terminal μ = 1 phase; up: ⌈log(cap/μ0)/log(factor)⌉), rung_len = max(1, ⌊max_iter/n_rungs⌋).
advance! moves to the next rung when the rung budget is spent OR the inner step stalled (the stall-early advance — see the file header).
MuLadder(factor; direction = :down, cap = Inf, converged_rung = false)CONVERGED-RUNG mode (converged_rung = true): no per-rung budget split — each rung runs until the inner step stalls and ONLY a stall advances the schedule (the Yang–Carlone-faithful setting; max_iter becomes a SAFETY ceiling enforced by the consuming loop, not a parity budget). Equivalent to an infinite rung_len; the budget contract is mode-aware: parity mode spends exactly the split, converged-rung mode is bounded only by the ceiling.
LocalOptimizationDoneRight.with_converged_rung — Function
with_converged_rung(s::MuLadder, converged_rung::Bool) -> MuLadderThe same ladder (factor, direction, cap) in the other rung mode: true advances a rung only on a stall, false splits the budget across the rungs.
LocalOptimizationDoneRight.gnc_schedule — Function
gnc_schedule(loss, factor) -> MuLadderThe rung ladder for a loss's graduation.
A BandAnnealed shape anneals μ UP to the hard-surrogate cap (VisualGeometryToolkitCore's gnc_mu_cap() — the same cap gnc_mu0 guards to); the μ-scaled families anneal μ DOWN to 1, the target loss. Only the direction/cap mapping is per-family — rung arithmetic (nrungs, runglen) is MuLadder.
Dispatches on gnc_surrogate like the rest of the gnc_* family, so a shape with no graduation path is a MethodError rather than a tag that falls through to a default branch.
LocalOptimizationDoneRight.GeometricAnneal — Type
GeometricAnneal(octaves)A width multiplier that decays geometrically from 2^octaves to 1 over the iteration budget.
The time-indexed continuation of the scheduled-Welsch family: at iteration t of T the width multiplier is 2^{octaves·(1 − (t−1)/(T−1))} — 2^oct at t = 1 decaying geometrically to exactly 1 at t = T (T ≤ 1 ⇒ 1).
Stall semantics (the D1 fix, defined here once): a stalled inner step at t < T JUMPS the schedule to its terminal position (t → T) and the engine continues at the terminal width until a terminal stall or the iteration budget — a stall never ends the engine at a wide surrogate.