Robust Statistics and Solvers API
The robust-statistics toolkit and the generic block-coordinate-descent loop: the shared machinery under the contracts of the Robust Estimation API page. The chart-rows contract and the chart LM are on the Chart LM API page.
Robust-Statistics Toolkit
The consensus scale, the Student-t + uniform mixture and its posterior-weight state, shared by the scorers, the local optimizers and the mixture fits.
VisualGeometryToolkitCore.IGPrior — Type
IGPrior(alpha0, beta0)Inverse-Gamma prior on σ²: π(σ²) ∝ (σ²)^{-(α₀+1)} exp(-β₀/σ²). Conjugate to the Gaussian inlier likelihood, so the marginal reduces to a closed-form sweep update.
The Jeffreys prior π(σ²) ∝ 1/σ² is the limiting α₀ = β₀ = 0 case, built by JeffreysPrior() (or IGPrior()); one struct handles both.
Fields
alpha0::Float64— shape hyperparameter (0 ⇒ Jeffreys)beta0::Float64— scale hyperparameter (0 ⇒ Jeffreys)
VisualGeometryToolkitCore.JeffreysPrior — Method
JeffreysPrior() -> IGPriorThe Jeffreys scale prior π(σ²) ∝ 1/σ²: IGPrior(0.0, 0.0), the default prior of every scale estimator and scorer in the stack. A function returning the value, not a second name of the type — test alpha0 == 0 rather than dispatching on a name.
VisualGeometryToolkitCore.fit_scale — Method
fit_scale(prior::IGPrior, rss, dof) -> s2Fit the squared scale ŝ² as the inverse-gamma MAP, (rss + 2β₀)/(dof + 2α₀).
Returns ŝ², the SQUARED scale — never a linear σ̂.
ŝ² is PER COMPONENT: rss sums squared NORMS of dg-vector residuals, so dof counts components — `νdata = (k − modeldof)·dgfor a hard partition, ordg·Σπᵢin the IRLS M-step (updatescale!). The2α₀/2β₀pseudo-counts make a refinement inherit the scoring prior (β₀floors ŝ² at low inlier counts);IGPrior(0, 0)(Jeffreys) givesrss/dof`.
The first argument is THE ESTIMATOR: IGPrior selects the inverse-gamma MAP, its prior being that estimator's parameters. The residuals are TAKEN as inliers, no initial guess is needed, and no inlier decision is made here.
The result is floored at eps(), so a zero rss under Jeffreys returns eps(), not a NaN. A caller that would rather HOLD its previous scale in that case must test the dof itself at the call site.
VisualGeometryToolkitCore.partition_rss — Method
partition_rss(order, residuals, k) -> Float64The residual sum of squares of the partition order[1:k]: Σ_{j ≤ k} residuals[order[j]]², from UNSQUARED residuals (signed scalars or norms), accumulated in Float64 whatever their storage eltype. order is a scorer's consensus_order (or a copy of it).
VisualGeometryToolkitCore.partition_student_t — Method
partition_student_t(prior::IGPrior, rss, k; model_dof, codimension = 1) -> (ν, ŝ²)The Student-t of a hard partition of k points with residual sum of squares rss. It is the scoring marginal's posterior predictive over it under prior, and THE seed of every Student-t in the stack: counted dof ν_data = (k − model_dof)·codimension, then
ν = max(ν_data + 2α₀, 2), ŝ² = fit_scale(prior, rss, ν_data).The ν ≥ 2 clamp keeps the seed's variance finite (a Student-t has one only for ν > 2) at a thin partition, and fit_scale floors the QUOTIENT at eps. One rule for every caller: both PosteriorWeightState seeds, the partition mixture of posterior_weights!/posterior_inlier_probs!, the consensus scale consensus_s2 and a RANSAC result's σ̂. model_dof is the caller's: the sweep's minimal_sample_size for the scoring marginal, one more for a local-optimization seed that also estimates the scale.
VisualGeometryToolkitCore.square_distances! — Method
square_distances!(sq, r, n) -> sqsq[i] = r[i]² for i ≤ n, squared in sq's OWN precision (x = eltype(sq)(r[i]), then x·x): a Float64 buffer squares a Float32 residual exactly. THE one residual-squaring loop of the stack — the refill of a PosteriorWeightState's sq_distances, the per-point scores a scorer sweeps, and the pool staging.
VisualGeometryToolkitCore.weighted_rss — Method
weighted_rss(w, sq_distances, n) -> Float64The weighted residual sum of squares Σ_{i ≤ n} wᵢ·rᵢ² of SQUARED residuals, accumulated in Float64 left to right from 0.0. A zero-weight term contributes exactly 0: an excluded point may carry an infinite squared residual (the Sampson degeneracy rule — a vanishing projected variance), and 0·Inf = NaN would poison the sum and everything read from it (the ŝ² M-step of update_scale!, an IRLS cost and its stop rule).
VisualGeometryToolkitCore.weighted_sq — Method
weighted_sq(w, sq_r) -> w·sq_r, exactly 0 at w = 0One term of weighted_rss, for a caller summing weights it computes on the fly rather than holding in a buffer (an ECM scale over a loss's own IRLS weights). A zero weight contributes exactly 0 even against an infinite squared residual, where 0·Inf = NaN.
VisualGeometryToolkitCore.GauInlier — Type
GauInlier(s2; nu = Inf, gamma = 1/2, d_g)Everything the Gaussian-uniform mixture needs EXCEPT the outlier half-width — the half both directions of the boundary share.
s2inlier variance sigma^2nueffective dof:Infis the Gaussian inlier, a finite value the scale-marginalised (Student-t) one. The Gaussian IS the nu -> Inf limit, and the two closed forms below agree there.gammathe label priorPr(z_i = 1); a general gamma addslog(gamma/(1-gamma))to the boundary.d_gthe codimension, REQUIRED. It enters the outlier density as the EXPONENT(2·outlier_halfwidth)^-d_g, so no value of it is a safe default.
VisualGeometryToolkitCore.StudentTMixture — Type
StudentTMixture(ν, s_hat_sq, log_two_outlier_halfwidth, d_g[, inlier_prior = 1/2])
StudentTMixture{T}(m::StudentTMixture)The Student-t inlier + uniform outlier mixture of one E-step, with every per-residual constant precomputed. Its parameters are ν degrees of freedom, squared scale ŝ² = s_hat_sq, outlier support of half-width outlier_halfwidth per axis (log_two_outlier_halfwidth = log(2·outlier_halfwidth), density p_out = (2·outlier_halfwidth)^-d_g), inlier mixing proportion π = inlier_prior. The loggammas are evaluated HERE, once.
An immutable isbits value, so it can be an argument of a KernelAbstractions kernel, and the three scalar functions of it — inlier_posterior, posterior_weight, mixture_nll — are allocation-free plain functions of a squared residual, callable inside a kernel as VGC's ρ is. StudentTMixture{Float32}(m) converts the constants for a Float32 kernel.
These are THE formulas of the mixture: soft_posterior_weights! (the E-step over a buffer) and posterior_weights!/posterior_inlier_probs! (over a partition) build one of these and call the same scalar kernel.
VisualGeometryToolkitCore.StudentTMixture — Method
StudentTMixture{T}(ν, s_hat_sq, log_two_outlier_halfwidth, d_g[, inlier_prior = 1/2]; lgamma = loggamma)The mixture built IN T (every constant computed in T, not in Float64 and rounded), with the log-gamma function supplied: kernel-lawful, so a device kernel whose ν and ŝ² change per work item builds one per item and calls inlier_posterior / posterior_weight on it. lgamma is the device's (CUDA's __nv_lgamma, Core's lgamma_lanczos elsewhere); the host default is SpecialFunctions' loggamma. StudentTMixture(…) is StudentTMixture{Float64}(…).
VisualGeometryToolkitCore.decision_boundary — Method
decision_boundary(m::GauInlier, outlier_halfwidth) -> Float64The residual at which the MAP rule flips between inlier and outlier: z* = 1 iff gamma*f_in > (1-gamma)*f_out holds exactly when norm(r) is below it.
Returns 0.0 when the outlier component already explains every residual at least as well (the mixture admits nothing), rather than a negative root.
VisualGeometryToolkitCore.decision_width — Method
decision_width(m::GauInlier, boundary) -> outlier_halfwidthThe mixture's method of decision_width, and the inverse of decision_boundary: the per-axis outlier half-width that puts the MAP boundary at boundary. A HALF-WIDTH and not a radius — the outlier support is a box, a product of intervals, never a ball, which is why the codimension enters as the exponent.
VisualGeometryToolkitCore.inlier_posterior — Method
inlier_posterior(m::StudentTMixture, sq_r) -> P(inlier | r)The posterior probability that a residual with squared norm sq_r is an inlier, π·t / (π·t + (1−π)·p_out). Scalar and kernel-callable.
A non-finite sq_r (Inf or NaN) is the outlier's: its posterior is 0, so it is no inlier (is_map_inlier), and its posterior_weight is 0.
VisualGeometryToolkitCore.mixture_nll — Method
mixture_nll(m::StudentTMixture, sq_r) -> −log(π·t_ν(r; ŝ²) + (1−π)·p_out)The negative log-density of the mixture at one residual — the per-point summand of the mixture NLL. Computed against the outlier term in log space, −(log((1−π)p_out) + softplus(log π·t − log((1−π)p_out))), so it is finite for an infinite residual (it is the outlier term's) and for an exact inlier. Scalar and kernel-callable.
VisualGeometryToolkitCore.next_nu — Method
next_nu(ν, sq_distances, s_hat_sq, w_fixed, n; d_g=1, kwargs...) -> ν_newM-step: Newton update for ν maximizing the EM Q-function with fixed E-step weights.
Maximizes Q(ν) = Σ wi · log t{dg}(ri; ν, ŝ²) w.r.t. ν, where wi are the fixed posterior inlier probabilities from the E-step (not recomputed), ri² the squared NORM of a d_g-vector residual and ŝ² the per-component scale:
log t_d(r; ν, ŝ²) = logΓ((ν+d)/2) − logΓ(ν/2) − (d/2)·log(νπŝ²) − ((ν+d)/2)·log(1 + z), z = r²/(νŝ²)
∂Q/∂ν = Σ wi · [½ψ((ν+d)/2) − ½ψ(ν/2) − d/(2ν) − ½log(1 + zi) + (ν+d)zi/(2ν(1+zi))]
∂²Q/∂ν² = Σ wi · [¼ψ₁((ν+d)/2) − ¼ψ₁(ν/2) + d/(2ν²) + zi/(2ν(1+zi)) − zi(ν + 2d + d·zi)/(2ν²(1+zi)²)]
with z_i the SCALE-NORMALISED squared residual.
Up to max_newton Newton steps from the current ν, each clamped to [ν_min, ν_max]. Newton is taken only where Q is concave (∂²Q < 0), where its step is uphill; elsewhere the step is geometric, uphill along the gradient — ν ← 2ν if ∂Q/∂ν > 0, ν ← ν/2 otherwise.
VisualGeometryToolkitCore.next_nu_from_sums — Method
next_nu_from_sums(ν, dQ, d2Q_data, sum_w, ψ1_half_νdg, ψ1_half_ν; d_g = 1, ν_min = 2, ν_max = 1e4) -> (ν_new, converged)One safeguarded Newton update of next_nu from the reduced sums dQ = Σwᵢ·dqᵢ, d2Q_data = Σwᵢ·d2q_dataᵢ (nu_point_terms) and sum_w = Σwᵢ, with ψ1_half_νdg = ψ₁((ν + d_g)/2) and ψ1_half_ν = ψ₁(ν/2) the caller's trigammas. ∂²Q = sum_w·(¼ψ₁((ν+d)/2) − ¼ψ₁(ν/2) + d/(2ν²)) + d2Q_data; Newton is taken only where Q is concave (∂²Q < 0, its step then uphill), elsewhere the step is geometric along the gradient (2ν or ν/2); the result is clamped to [ν_min, ν_max]. converged is true when the weights vanish (sum_w < 1e-10, ν returned unchanged) or |dQ/sum_w| < 1e-8. Generic in the float type, allocation-free: the ν update of a device kernel.
VisualGeometryToolkitCore.nu_point_terms — Method
nu_point_terms(z, ν, ψ_half_νdg, ψ_half_ν; d_g = 1) -> (dq, d2q_data)One point's terms of next_nu's Q-derivatives at ν (its docstring states both): dq its summand of ∂Q/∂ν and d2q_data the data part of its summand of ∂²Q/∂ν² (the ν-only part is the sum's, Σwᵢ times a constant, added by next_nu_from_sums), at the scale-normalised squared residual z = r²/(ν·ŝ²), with ψ_half_νdg = ψ((ν + d_g)/2) and ψ_half_ν = ψ(ν/2) the caller's digammas. Generic in the float type and allocation-free: a device kernel sums wᵢ·dq and wᵢ·d2q_data over its points (a workgroup reduction) and hands the sums to next_nu_from_sums, the same arithmetic as the host loop of next_nu.
VisualGeometryToolkitCore.posterior_weight — Method
posterior_weight(m::StudentTMixture, sq_r) -> wThe IRLS weight of the mixture at sq_r: P(inlier | r) · (ν + d_g)/(ν·ŝ² + r²), the responsibility times the Student-t's own weight. Scalar and kernel-callable. 0 for a non-finite sq_r (Inf or NaN), as inlier_posterior is.
VisualGeometryToolkitCore.posterior_weight_derivative — Method
posterior_weight_derivative(m::StudentTMixture, sq_r) -> dw/d(sq_r)The slope of posterior_weight in the squared residual, −w/(ν·ŝ² + r²) · (1 + (ν + d_g)/2 · (1 − P(inlier | r))) — the Student-t weight's own decay plus the responsibility's. w is strictly decreasing in sq_r, so this is negative wherever w > 0; it is what a Newton inversion of the weight (a tabulated half-quadratic conjugate, LocalOptimizationDoneRight's TabulatedLift) needs. Scalar and kernel-callable.
VisualGeometryToolkitCore.soft_posterior_weights! — Function
soft_posterior_weights!(w, inlier_posterior, sq_distances, ν, s_hat_sq, log_two_outlier_halfwidth, n, d_g=1[, inlier_prior=1/2])E-step: compute posterior inlier probability and combined IRLS weight.
Stores inlier_posterior[i] = P(inlier | r_i) separately for the ν M-step, and w[i] = inlier_posterior[i] · u_i (combined weight for the θ solve).
d_g is the constraint codimension (1 for scalar residuals, 2 for 2D).
A datum whose squared residual is not finite (Inf or NaN) gets inlier_posterior[i] = w[i] = 0: it is no inlier, and every sum read from the E-step (the ŝ² and inlier-prior blocks, ν's sums, the cost Σwᵢrᵢ²) skips it.
The separation is critical: the ν Newton update must use fixed E-step weights (not recomputed from the changing ν), otherwise ν and inlier_posterior couple in a positive feedback loop that drives ν → ∞.
VisualGeometryToolkitCore.ConsensusDof — Type
ConsensusDof()The update policy of a Student-t dof HELD at the value its consensus seed gave it: the posterior-predictive dof of the scorer's consensus set, ν = 2α₀ + (k* − model_dof)·d_g (partition_student_t, with its ν ≥ 2 floor), where α₀ is the scale prior's shape (0 under Jeffreys). The seed sets it once; the ν block never moves it afterwards.
Why hold it there: a Gaussian whose scale carries an inverse-gamma posterior marginalizes to a Student-t with exactly that dof — ν measures how well the consensus set DETERMINES σ, not the shape of the inlier tail. Estimating ν instead lets the fit trade one for the other: on a contaminated set a heavy inlier tail (ν → 2) absorbs the outliers — the identifiability collapse this policy prevents.
VisualGeometryToolkitCore.Estimated — Type
Estimated()The update policy of a nuisance part that is ESTIMATED: its M-step block runs (update_scale!(pws, n), update_inlier_prior!(pws, n), update_nu!(pws, n)). One value for every part.
VisualGeometryToolkitCore.FixedNu — Type
FixedNu(ν)The update policy of a Student-t dof HELD at ν (positive, finite): the ν block writes it.
VisualGeometryToolkitCore.FixedPrior — Type
FixedPrior(inlier_prior)The update policy of an inlier prior HELD at inlier_prior ∈ (0, 1): the π block writes it (through the E-step's one clamp, [1e-3, 1 − 1e-3]).
VisualGeometryToolkitCore.FixedS2 — Type
FixedS2(s2)The update policy of a scale HELD at the squared scale s2 (positive, finite): the ŝ² block writes it.
VisualGeometryToolkitCore.PosteriorWeightState — Type
PosteriorWeightStateMutable state for computing robust IRLS weights from a Student-t inlier + uniform outlier mixture model. Holds the sufficient statistics (ν, ŝ², logtwooutlierhalfwidth, the inlier prior π) and per-point buffers (w, inlierposterior, r²).
The Posterior in the name is the posterior over the inlier indicator: the weights w/inlier_posterior are P(inlier | r). The noise scale σ² also has a posterior, but it is marginalized away, so it is held here only as the scalar ν/ŝ², never as a posterior.
The per-point buffers are supplied by the caller (typically a workspace's); construction-time allocation is performed only by the n-constructor and median_seeded_posterior.
VisualGeometryToolkitCore.PosteriorWeightState — Method
PosteriorWeightState(sq_distances, n, model_dof, k; order, prior, w, inlier_posterior, sq_r,
log_two_outlier_halfwidth, codimension = 1)The state seeded from a hard partition: the first k entries of order (a scorer's consensus_order over these same squared residuals), with no fresh sort. The seed is the partition's Student-t under prior (partition_student_t), so it equals the scoring predictive over order[1:k]; the E-step runs once.
Precondition: order[1:k] is a partition of sq_distances[1:n] and k > model_dof.
VisualGeometryToolkitCore.PosteriorWeightState — Method
PosteriorWeightState(n; ν, s_hat_sq, log_two_outlier_halfwidth, prior, codimension = 1, inlier_prior = 1/2)A state with FRESH length-n buffers at the given mixture, for a caller that fills the residuals itself and runs the E-step (e.g. mixture_ecm!) before reading any weight. The buffers are uninitialised; ŝ² is floored at eps and the inlier prior clamped to [1e-3, 1 − 1e-3] (the one clamp, update_inlier_prior!'s). The scale prior prior (an IGPrior) is required: the stack's default prior is a configuration's, not this constructor's.
VisualGeometryToolkitCore.StudentTMixture — Method
StudentTMixture(pws::PosteriorWeightState)The mixture the state's E-step evaluates: its current ν, ŝ², outlier support, codimension and inlier prior.
VisualGeometryToolkitCore.inlier_prior — Method
inlier_prior(pws::PosteriorWeightState) -> Float64The mixing proportion π the E-step weighs with: the prior probability that a residual is an inlier (1/2 unless estimated or held elsewhere).
VisualGeometryToolkitCore.median_seeded_posterior — Method
median_seeded_posterior(sq, n; outlier_halfwidth, ν, prior, codimension = 2) -> PosteriorWeightStateA PosteriorWeightState seeded from the MEDIAN residual, for a caller with no partition to seed from. Every point starts an inlier candidate at the scale ŝ² = mad_scale² — the median residual norm over the median of χ_d (mad_scale, on the norms √sq), floored at eps — at the caller's start ν (large for a near-Gaussian start) under the scale prior prior, both required (a configuration's values, not this function's), and the E-step run once. Allocates its own buffers (sq[1:n] is copied). codimension is 1 or 2. A NaN residual is no inlier candidate: the median is over the others (an infinite residual stays in it, an outlier's large norm), and the E-step gives it weight 0 (soft_posterior_weights!). With every residual NaN there is no median: ŝ² is NaN.
VisualGeometryToolkitCore.mixture_ecm! — Method
mixture_ecm!(pws, r, n)One ECM cycle of the Student-t + uniform mixture with the mixing proportion ESTIMATED (ν held fixed), from the residuals r[1:n] (unsquared). It squares them into sq_distances(pws), then runs the E-step (update_weights!), the scale block (update_scale!) and the inlier-prior block (update_inlier_prior!), in that order. Each block is an exact conditional maximisation, so the mixture NLL (mixture_nll) never rises. Returns nothing.
VisualGeometryToolkitCore.mixture_nll — Method
mixture_nll(pws::PosteriorWeightState, r, n) -> Float64The mixture negative log-likelihood Σ_{i ≤ n} −log[π·t_ν(rᵢ; ŝ²) + (1−π)·p_out] of the residuals r[1:n] (UNSQUARED) at the state's current (ν, ŝ², π). It sums the per-point mixture_nll(m, rᵢ²) of StudentTMixture(pws) in Float64. Reads the state; writes nothing.
VisualGeometryToolkitCore.posterior_inlier_probs! — Method
posterior_inlier_probs!(w, sq_distances, order, k; model_dof, log_two_outlier_halfwidth, prior,
codimension = 1)Posterior inlier probabilities w[i] ∈ [0, 1] of the hard partition order[1:k], without the IRLS weight factor — the same mixture as posterior_weights!, so that is this times uᵢ.
VisualGeometryToolkitCore.posterior_weights! — Method
posterior_weights!(w, sq_distances, order, k; model_dof, log_two_outlier_halfwidth, prior,
codimension = 1)Student-t posterior weights w[i] = P(inlier | rᵢ) · uᵢ of the hard partition order[1:k] of the squared residuals: the partition's Student-t (partition_student_t under prior: ν = (k − model_dof)·d_g + 2α₀, at least 2, and ŝ² = (RSS + 2β₀)/((k − model_dof)·d_g + 2α₀)) against the uniform outlier support, uᵢ = (ν + d_g)/(ν·ŝ² + r²ᵢ). Per point this is posterior_weight of that StudentTMixture. Fills every entry of w.
VisualGeometryToolkitCore.reset_posterior! — Method
reset_posterior!(pws; ν, s_hat_sq, log_two_outlier_halfwidth, prior, codimension, inlier_prior) -> pwsPosteriorWeightState(n; …) IN PLACE: the same parameters (ŝ² floored at eps, π clamped) on pws's existing buffers, whose contents are left as they are — that constructor's buffers are uninitialized, so nothing may read them before writing. A keyword left out keeps the state's CURRENT value (its ν, ŝ², outlier support, scale prior, codimension and inlier prior), so a caller re-seeding one parameter states only that one (the floor and the clamp, idempotent, are applied as to a given value).
VisualGeometryToolkitCore.s_hat_sq — Method
s_hat_sq(pws::PosteriorWeightState) -> Float64The current squared scale estimate ŝ² of the Student-t inlier density (a SQUARE; see fit_scale).
VisualGeometryToolkitCore.seed_posterior! — Method
seed_posterior!(pws, sq_distances, n, model_dof, k; order, prior, log_two_outlier_halfwidth,
codimension = 1) -> pwsThe partition seeding of PosteriorWeightState(sq_distances, n, model_dof, k; …) IN PLACE, on pws's own buffers: the same squared residuals, partition Student-t and first E-step, the inlier prior back at 1/2. What a caller that keeps one state across calls (a local optimizer's workspace) re-seeds with.
VisualGeometryToolkitCore.sq_distances — Method
sq_distances(pws::PosteriorWeightState) -> Vector{Float64}The squared Mahalanobis distances the E-step weighs — the buffer update_scale! and update_weights! read, refilled by the caller between iterations.
VisualGeometryToolkitCore.student_t_dof — Method
student_t_dof(pws::PosteriorWeightState) -> Float64The Student-t degrees of freedom ν of the inlier density — not the model's DOF (minimal_sample_size), and not Distributions' dof.
VisualGeometryToolkitCore.update_inlier_prior! — Method
update_inlier_prior!(pws, n, policy) -> πThe inlier-prior block under its update policy: Estimated() is update_inlier_prior!(pws, n); FixedPrior holds π.
VisualGeometryToolkitCore.update_inlier_prior! — Method
update_inlier_prior!(pws, n)M-step, inlier-prior block: overwrite the mixing proportion π with the mean inlier posterior of the E-step, and nothing else. The mean Σπᵢ/n is clamped to [1e-3, 1 − 1e-3] (the E-step reads it through log((1 − π)/π)). Call after update_weights! filled the posteriors it reads. Returns π.
VisualGeometryToolkitCore.update_nu! — Method
update_nu!(pws, n, policy) -> νThe ν block under its update policy: Estimated() is update_nu!(pws, n); FixedNu holds ν; ConsensusDof keeps the seed's.
VisualGeometryToolkitCore.update_nu! — Method
update_nu!(pws, n)M-step, ν block: overwrite the Student-t dof ν with next_nu (the safeguarded Newton MLE) from the E-step's inlier posteriors, the current squared residuals and the CURRENT ŝ², and nothing else. Call after update_scale!, which it reads. Returns ν.
VisualGeometryToolkitCore.update_scale! — Method
update_scale!(pws, n, policy) -> ŝ²The scale block under its update policy. Estimated() is update_scale!(pws, n); FixedS2 holds ŝ².
VisualGeometryToolkitCore.update_scale! — Method
update_scale!(pws, n)M-step, scale block: overwrite ŝ² from the E-step's weights and the current squared residuals, and nothing else. Call after the residual block fills sq_distances(pws); the ν block is update_nu!, called after this.
ŝ² is the ECM step of the d_g-variate Student-t with scale ŝ²·I:
ŝ²_new = Σ πᵢ uᵢ rᵢ² / (d_g · Σ πᵢ), uᵢ = (ν + d_g)/(ν + rᵢ²/ŝ²),with πᵢ the inlier posteriors and rᵢ² squared NORMS. The E-step's weight is precision-scaled, wᵢ = πᵢ·(ν + d_g)/(νŝ² + rᵢ²) = πᵢuᵢ/ŝ², so the numerator is ŝ²·Σwᵢrᵢ² at the ŝ² that E-step used, and the inverse-gamma prior enters as fit_scale(prior, ŝ²·Σwᵢrᵢ², d_g·Σπᵢ). Returns ŝ².
VisualGeometryToolkitCore.update_weights! — Method
update_weights!(pws, n)E-step: recompute posterior inlier probabilities and combined IRLS weights from current ν, ŝ², and squared residuals.
VisualGeometryToolkitCore.truncated_log_normaliser — Method
truncated_log_normaliser(shape, sq_loss_width, depth, r_max) -> Float64log Z̃ = log ∫_{−r_max}^{r_max} exp(−depth·ρ(shape, r²/sq_loss_width, 1)) dr — the normaliser of the density a loss shape induces on the truncated domain [−r_max, r_max], as log 2∫₀^{r_max} (the integrand is even), by adaptive Gauss–Kronrod (QuadGK) at rtol 1e-12. The integrand is a well of width c = √sq_loss_width on a flat floor, so for c ≪ r_max an unsplit rule never samples the well: the domain is split at c·4ᵏ < r_max, which holds the result to ≲1e-12 relative over every width and depth in use.
Block Coordinate Descent
VisualGeometryToolkitCore.AbstractBlockCoordinateMethod — Type
AbstractBlockCoordinateMethodAbstract type for the problem side of block_coordinate_descent!: the model block, its residuals, and the per-iteration bookkeeping.
Each concrete subtype defines extension points:
init_state!(method, prob, θ₀)— build the state and compute the initial r/σ/w. It carries!because a method may fill buffers its own workspace holds (VisualGeometryToolkitEstimation's posterior IRLS seedsmethod.ws's residual buffers, which the iterations then read); the method is the mutated argumentupdate_model!(state, method, prob, θ)— the model block: one weighted update of θ (weighted least squares, LM, Newton), or θ unchanged;nothingwhen there is no update to make (the run stops with:solve_failed)update_residuals!(state, method, prob, θ)— compute residuals + sq_distances from θpost_iteration!(state, method, prob, θ, iter)— per-iteration bookkeeping (best-tracking, counters the stopping criteria read)stopping_criterion(method)— the method's ownStoppingCriterion(defaultStopNever)block_coordinate_result(state, method, prob, θ, stop_reason, final_iter, stop_rule)— package result
VisualGeometryToolkitCore.Recorded — Type
Recorded(state)A block_coordinate_descent! state that also keeps a per-iteration trace: iterates (the model each iteration produced), cost (the state's current_cost after post_iteration!), s2 (the likelihood's current_s2, the squared scale, NaN where it holds none) and reason (a Ref to the stop reason). Give it in place of the state; the driver runs every block and every criterion on the wrapped state, so a recorded run is the bare run, iterate for iterate. The bare state never records — off by default, nothing to branch on.
VisualGeometryToolkitCore.StopAfterIteration — Type
StopAfterIteration(n)Stops with :max_iterations once n iterations have run (before the first, when n ≤ 0). block_coordinate_descent! adds it, LAST, from its max_iter, so on the final iteration a method's own reason wins.
VisualGeometryToolkitCore.StopNever — Type
StopNever()Never stops: the default stopping_criterion of a method that runs its whole budget.
VisualGeometryToolkitCore.StopWhenAny — Type
StopWhenAny(criteria::Tuple)
a | bStops at the first of criteria, in order, whose stop_reason is not :continue, with that reason. a | b builds one and flattens nested ones.
VisualGeometryToolkitCore.StopWhenSolveFailed — Type
StopWhenSolveFailed()Stops with :solve_failed when the model block returned nothing (a singular or non-finite solve, an underdetermined refit): checked right after update_model!, before any other block runs. block_coordinate_descent! adds it FIRST.
VisualGeometryToolkitCore.StoppingCriterion — Type
StoppingCriterionWhen a block_coordinate_descent! run ends, and why. A criterion is an immutable, concretely typed value; it answers through stop_reason(criterion, state, method, prob, θ, θ_old, iter), which returns :continue or the reason the run ends (:converged, :max_iterations, :solve_failed, or any instance's own Symbol such as :left_basin). Nothing is stored in the criterion: the counters a criterion reads live in the solver state, written by post_iteration!.
Criteria compose with | into a StopWhenAny, evaluated left to right; the first reason other than :continue wins. The tuple is part of the type, so the composed check compiles to the chain of branches it stands for.
The Manopt.jl correspondence: Manopt's criteria are mutable functors that store their reason; these are pure, and the reason is the return value.
VisualGeometryToolkitCore.block_coordinate_descent! — Method
block_coordinate_descent!(likelihood, method, prob, θ₀; max_iter) -> resultBlock coordinate descent on a negative log-likelihood, over three blocks:
- model —
update_model!(themethod): weighted least squares, LM, Newton, or nothing at all (a fixed-model method such as a seed EM, which returns θ unchanged); - nuisance —
update_nuisance!(thelikelihood): scale, mixing proportion, ν, Barron α, or nothing; - weights —
update_weights!(thelikelihood): EM responsibilities, loss weights, or GNC surrogate weights.
update_residuals! is bookkeeping between the model and nuisance blocks: it recomputes the residuals block from the new model and descends on nothing. One iteration (step_solver!) is one cycle through every block, in the order model → residuals → nuisance → weights, then post_iteration!. See update_nuisance! for why the nuisance block is not named "scale".
Stopping
The run's criterion is
StopWhenSolveFailed() | stopping_criterion(method) | StopAfterIteration(max_iter)evaluated in that order by stop_solver! after every iteration: a failed model block ends the run at once (:solve_failed, no other block run); otherwise the method's own criterion is read after post_iteration!, and only then the budget — on the last iteration a method's reason wins over :max_iterations. max_iter ≤ 0 runs no iteration. The result is block_coordinate_result(state, method, prob, θ, reason, iterations, rule) with θ the last model the model block produced (θ₀ if none).
Monotonicity
Instances: EM (under the Neal–Hinton free-energy view EM is coordinate ascent on the free energy, i.e. descent on its negative); IRLS / half-quadratic (VisualGeometryToolkitEstimation's Irls{K} LO strategy is one — the strategy, not this loop); Barron-adaptive; GNC.
"Descent" is on the negative log-likelihood, and monotonicity is each INSTANCE's claim, not the loop's: the best iterate is kept (a method tracks it in post_iteration! with keep_best and returns it from block_coordinate_result), but the loop never rejects a step. An instance proves monotonicity through its post_iteration! trace. GNC is the declared exception — it changes its objective between iterations.
The Manopt.jl names
The loop is Manopt's solve! loop; the names are public, not exported, so a future bridge extends Manopt's functions rather than clashing with them:
| Manopt.jl | here |
|---|---|
AbstractManoptSolverState | the method's state (any type; RVG's *State) |
initialize_solver! | initialize_solver! |
step_solver! | step_solver!: one BCD cycle, the four blocks + post_iteration! |
stop_solver! | stop_solver! |
StoppingCriterion, get_reason | StoppingCriterion, stop_reason (pure; the reason is returned) |
StopAfterIteration, StopWhenAny (criteria or-ed) | StopAfterIteration, StopWhenAny (criteria or-ed) |
RecordSolverState | Recorded |
get_solver_result | block_coordinate_result |
Argument order is Julia Base's: the inputs the loop mutates come first (state, in the method below, then likelihood), then the inputs it only reads (the method, the problem, the seed).
VisualGeometryToolkitCore.block_coordinate_descent! — Method
block_coordinate_descent!(state, likelihood, method, prob, θ₀; max_iter) -> resultBlock coordinate descent with pre-allocated state (skips init_state!). state may be a Recorded one.
VisualGeometryToolkitCore.block_coordinate_result — Function
block_coordinate_result(state, method::AbstractBlockCoordinateMethod, prob, θ, stop_reason, final_iter, stop_rule)Package the run of block_coordinate_descent! as the method's result (a FitResult for the stack's fits), from the final state, model, stop_reason and iteration count.
VisualGeometryToolkitCore.current_cost — Method
current_cost(state) -> Float64The objective a state tracks at its current iterate, for Recorded. NaN unless the state's type implements it.
VisualGeometryToolkitCore.current_s2 — Method
current_s2(likelihood) -> Float64The squared scale ŝ² a weight policy currently holds, for Recorded. NaN unless the policy's type implements it.
VisualGeometryToolkitCore.init_state! — Function
init_state!(method::AbstractBlockCoordinateMethod, prob, θ₀) -> stateBuild the solver state of block_coordinate_descent! and compute the initial residuals, scale and weights at θ₀. A method may fill buffers its own workspace holds, hence the !. An extension point: the method's package adds the method.
VisualGeometryToolkitCore.initialize_solver! — Method
initialize_solver!(state, likelihood, method, prob, θ₀, criterion) -> (reason::Symbol, rule::StopRule)Start a block_coordinate_descent! run: clears a Recorded trace, and returns the reason the run ends before its first iteration (:max_iterations for a non-positive budget) or :continue. The state itself is built beforehand — by init_state! or the caller.
VisualGeometryToolkitCore.keep_best — Method
keep_best(best, θ, cost) -> (best′, improved::Bool)Best-tracking for a block_coordinate_descent! instance that claims descent. The loop never rejects an iterate, so such an instance keeps its best one as best = Attributed(θ, (; cost)) (cost a Float64): its post_iteration! offers every iterate here, and its block_coordinate_result returns best.value. Returns (Attributed(θ, (; cost)), true) when cost is STRICTLY below best.cost, and (best, false) otherwise. Pure and allocation-free: the caller stores the result.
VisualGeometryToolkitCore.post_iteration! — Method
post_iteration!(state, method::AbstractBlockCoordinateMethod, prob, θ, iter) -> nothingPer-iteration bookkeeping of block_coordinate_descent!, after the weight block: best-model tracking and the counters a StoppingCriterion reads. The default does nothing.
VisualGeometryToolkitCore.step_solver! — Method
step_solver!(state, likelihood, method, prob, θ, iter) -> θ′ or nothingOne iteration — one cycle through the blocks, in the frozen order: update_model! (the model block; nothing ends the cycle there, with no other block run), update_residuals!, update_nuisance!(likelihood), update_weights!(likelihood), post_iteration!. Returns the new model.
VisualGeometryToolkitCore.stop_reason — Function
stop_reason(criterion, state, method, prob, θ, θ_old, iter) -> Symbol:continue, or the reason the run ends after iteration iter, which moved θ_old to θ (θ is nothing when the model block failed). Pure: it reads the state and writes nothing. Implement it for a new StoppingCriterion.
VisualGeometryToolkitCore.stop_rule — Method
stop_rule(criterion::StoppingCriterion, method) -> StopRuleThe StopRule a criterion's stop records, for the method it stopped: NoRule by default; Core's own criteria StopAfterIteration → IterationCap, StopWhenSolveFailed → NonFinite (a failed model block). A package adds a method for each criterion it defines (and may specialise on the method). block_coordinate_descent! asks it of the member of a StopWhenAny that fired — the first whose stop_reason is not :continue, in evaluation order — and hands it to block_coordinate_result, so no consumer re-evaluates the criteria to learn which stopped the run.
VisualGeometryToolkitCore.stop_solver! — Method
stop_solver!(state, criterion, method, prob, θ, θ_old, iter) -> (reason::Symbol, rule::StopRule)The run's stop_reason after iteration iter (θ is nothing when its model block failed), with the stop_rule of the criterion that fired (NoRule while the run continues); the reason recorded on a Recorded state.
VisualGeometryToolkitCore.stopping_criterion — Method
stopping_criterion(method::AbstractBlockCoordinateMethod) -> StoppingCriterionThe method's own termination test, evaluated after post_iteration! and before the iteration budget (StopAfterIteration). Default StopNever: the run ends on the budget or a failed solve only.
VisualGeometryToolkitCore.update_model! — Function
update_model!(state, method::AbstractBlockCoordinateMethod, prob, θ) -> θ′ | nothingThe model block of block_coordinate_descent!: one weighted update of θ at fixed weights and nuisance (a weighted least-squares solve, an LM step, Newton), or θ unchanged. nothing means there is no update to make, and the run stops with :solve_failed. A fit fit_<fit>'s method calls its <fit>_step here.
VisualGeometryToolkitCore.update_residuals! — Function
update_residuals!(state, method::AbstractBlockCoordinateMethod, prob, θ) -> stateThe residual block of block_coordinate_descent!: writes the residuals and squared residuals of θ into the state, and nothing else.
Index
VisualGeometryToolkitCore.AbstractBlockCoordinateMethodVisualGeometryToolkitCore.ConsensusDofVisualGeometryToolkitCore.EstimatedVisualGeometryToolkitCore.FixedNuVisualGeometryToolkitCore.FixedPriorVisualGeometryToolkitCore.FixedS2VisualGeometryToolkitCore.GauInlierVisualGeometryToolkitCore.IGPriorVisualGeometryToolkitCore.PosteriorWeightStateVisualGeometryToolkitCore.PosteriorWeightStateVisualGeometryToolkitCore.PosteriorWeightStateVisualGeometryToolkitCore.RecordedVisualGeometryToolkitCore.StopAfterIterationVisualGeometryToolkitCore.StopNeverVisualGeometryToolkitCore.StopWhenAnyVisualGeometryToolkitCore.StopWhenSolveFailedVisualGeometryToolkitCore.StoppingCriterionVisualGeometryToolkitCore.StudentTMixtureVisualGeometryToolkitCore.StudentTMixtureVisualGeometryToolkitCore.StudentTMixtureVisualGeometryToolkitCore.JeffreysPriorVisualGeometryToolkitCore.block_coordinate_descent!VisualGeometryToolkitCore.block_coordinate_descent!VisualGeometryToolkitCore.block_coordinate_resultVisualGeometryToolkitCore.current_costVisualGeometryToolkitCore.current_s2VisualGeometryToolkitCore.decision_boundaryVisualGeometryToolkitCore.decision_widthVisualGeometryToolkitCore.fit_scaleVisualGeometryToolkitCore.init_state!VisualGeometryToolkitCore.initialize_solver!VisualGeometryToolkitCore.inlier_posteriorVisualGeometryToolkitCore.inlier_priorVisualGeometryToolkitCore.keep_bestVisualGeometryToolkitCore.median_seeded_posteriorVisualGeometryToolkitCore.mixture_ecm!VisualGeometryToolkitCore.mixture_nllVisualGeometryToolkitCore.mixture_nllVisualGeometryToolkitCore.next_nuVisualGeometryToolkitCore.next_nu_from_sumsVisualGeometryToolkitCore.nu_point_termsVisualGeometryToolkitCore.partition_rssVisualGeometryToolkitCore.partition_student_tVisualGeometryToolkitCore.post_iteration!VisualGeometryToolkitCore.posterior_inlier_probs!VisualGeometryToolkitCore.posterior_weightVisualGeometryToolkitCore.posterior_weight_derivativeVisualGeometryToolkitCore.posterior_weights!VisualGeometryToolkitCore.reset_posterior!VisualGeometryToolkitCore.s_hat_sqVisualGeometryToolkitCore.seed_posterior!VisualGeometryToolkitCore.soft_posterior_weights!VisualGeometryToolkitCore.sq_distancesVisualGeometryToolkitCore.square_distances!VisualGeometryToolkitCore.step_solver!VisualGeometryToolkitCore.stop_reasonVisualGeometryToolkitCore.stop_ruleVisualGeometryToolkitCore.stop_solver!VisualGeometryToolkitCore.stopping_criterionVisualGeometryToolkitCore.student_t_dofVisualGeometryToolkitCore.truncated_log_normaliserVisualGeometryToolkitCore.update_inlier_prior!VisualGeometryToolkitCore.update_inlier_prior!VisualGeometryToolkitCore.update_model!VisualGeometryToolkitCore.update_nu!VisualGeometryToolkitCore.update_nu!VisualGeometryToolkitCore.update_residuals!VisualGeometryToolkitCore.update_scale!VisualGeometryToolkitCore.update_scale!VisualGeometryToolkitCore.update_weights!VisualGeometryToolkitCore.weighted_rssVisualGeometryToolkitCore.weighted_sq